class OperationNode

A problem exists whereby a series of drivers reuse the same object as it

traverses the driver stack for a specific subsystem. There exists a public

section specified by a banjo protocol, along with a private section for

each layer in driver stack appended to the end of it like so:

---------------------

| Public Definition |

---------------------

| Driver 1 Private |

---------------------

| Driver 2 Private |

---------------------

| ... |

---------------------

| Driver N Private |

---------------------

Driver N in this case would perform the allocation of the entire struct.

Driver 1 in the example above would be the device driver which talks

directly to hardware. The request would only be "owned" by a single

driver at a time, but only Driver N (the one who allocated the request)

would be allowed to free it.

This library provides a generic solution to the private section problem

which exists for types such as usb_request_t, node_operation_t,

block_op_t, and others. Specialized wrappers for each of those types

can be built on top this library.

operation::Operation and operation::BorrowedOperation provide some additional

safety to prevent leaks and out of bounds accesses. They will ensure that the

underlying buffer is returned to the caller, or delete it if the current

owner was responsible for allocating the request. In addition, they help

provide an easy way to determine the size of the request by simply specifying

the parent device's operation size.

operation::OperationPool provides a simple pool that allows reuse of

pre-allocated operation::Operation objects.

operation::{Borrowed,}OperationQueue provide safe queues to place operations

in while they are pending. These queues rely on intrusive node data built

into the wrapper type, stored in the private storage section.

operation::{Borrowed,}OperationList provides lists to place operations in

while they are pending. Operations cannot be stored in both an

operation::{Borrowed,}OperationQueue and operation::{Borrowed,}Operation:List

in the same driver layer, as they both use the same memory to store

the intrusive node data.

In order to use make use of the Operation and OperationNode classes, a new

type must be created which inherits from it like so:

class Foo : public Operation

<Foo

, OperationTraits, void>;

class Bar : public BorrowedOperation

<Bar

, OperationTraits, CallbackTraits, void>;

OperationTraits must be a type which implements the following function

and type signatures:

// Defines public definition which is wrapped.

using OperationType = foo_operation_t;

// Performs an allocation for the operation.

static OperationType* Alloc(size_t op_size);

// Frees the allocation created by Alloc above.

static void Free(OperationType* op);

CallbackTraits must be a type which implements the following function

and type signatures:

// The type here can be anything. It should match the callback provided to

// the BorrowedOperation constructor.

using CallbackType = void(void* ctx, ARGS, foo_operation_t*);

// In case Complete is not called by BorrowedOperation owners, these are

// the args to trigger Complete with.

static std::tuple

<ARGS

> AutoCompleteArgs();

// Should call the callback, transforming and positioning args as necessary.

static void Callback(CallbackType*, void*, OperationType*, ARGS);

Where ARGS is a variadic number of types left to the implementer.