struct OperationTraits

Usage notes:

block::Operation is a c++ wrapper around the block_op_t object. It provides

capabilities to interact with a block_op buffer which is used to traverse the

block stack. On deletion, it will automatically free itself.

block::BorrowedOperation provides an unowned variant of block::Operation. It adds

functionality to store and call a complete callback which isn't present in

block::Operation. In addition, it will call the completion on destruction if it

wasn't already triggered.

block::OperationPool provides pooling functionality for block::Operation reuse.

block::OperationQueue provides a queue interface for tracking block::Operation and

block::BorrowedOperation objects.

Available methods for both Operation and BorrowedOperation include:

block_op_t* operation(); // accessor for inner type.

// Takes ownership of inner type. Should only be used when transferring

// ownership to another driver.

block_op_t* take();

Available to Operation and BorrowedOperation if they templatize of Storage:

Storage* private_storage(); // accessor for private storage.

Available to Operation:

void Release(); // Frees the inner type.

Available to BorrowedOperation:

void Complete(zx_status_t); // Completes the operation.

////////////////////////////////////////////////////////////////////////////

Example: Basic allocation with a pool:

block::OperationPool

<

> pool;

const size_t op_size = block::Operation

<

>::OperationSize(parent_op_size);

for (int i = 0; i

<

kNumRequest; i++) {

std::optional

<block

::Operation> request;

request = block::Operation::Alloc(op_size, parent_op_size);

if (!request) return ZX_ERR_NO_MEMORY;

pool.add(*std::move(request));

}

////////////////////////////////////////////////////////////////////////////

Example: Enqueue incoming operation into a block::OperationQueue:

class Driver {

public:

<

...>

private:

block::BorrowedOperationQueue

<

> operations_;

const size_t parent_op_size_;

};

void Driver::BlockImplQueue(block_op_t* op, block_queue_callback completion_cb, void* cookie) {

operations_.push(block::BorrowedOperation

<

>(op, cb, parent_req_size_));

}

////////////////////////////////////////////////////////////////////////////

Example: Using private context only visible to your driver:

struct PrivateStorage {

bool valid;

size_t count_metric;

}

using BlockOperation = block::BorrowedOperation

<PrivateStorage

>;

void Driver::BlockImplQueue(block_op_t* op, block_queue_callback completion_cb, void* cookie) {

BlockOperation block_op(op, cb, parent_req_size_));

ZX_DEBUG_ASSERT(block_op.operation()->command.opcode == BLOCK_OPCODE_READ);

block_op.private_storage()->valid = true;

block_op.private_storage()->count_metric += 1;

<

...>

}