Endpoint Library Documentation: Management Classes

The block and memory management classes work with an endpoint which has mixed in the ManagedEndpoint class. One example is AsyncWskEndpoint.

When data comes in on a ManagedEndpoint, it sends it to the associated BlockManager, which exports the GetBufferPtr() member for this purpose. (This function returns a pointer to a buffer where the ManagedEndpoint should store the data, and the size of that buffer, in bytes. Nothing else can be safely assumed about this block of memory.) The ManagedEndpoint then calls BlockManager::HandleNewData(). This function looks at the new data and decides if a complete block (or more) has arrived; if it has, that block is sent on to the MemoryManager.

The LengthPrefixedBlockManager handles packets with a network-ordered length prefix. It is smart enough to handle one to four bytes of prefix (more, actually, if the size of "long" on your machine is larger than four bytes), user-selectable.

The other included block manager is StreamBlockManager which simply calls every block it gets from the ManagedEndpoint a block. This is most useful when you don't want to bother with management but still want to use an endpoint that's managed. In that case, you would probably also select one of the stock memory managers.

The MemoryManager defines the memory allocation policy of the endpoint. When the BlockManager tells the MemoryManager about new data, the MemoryManager copies it into buffers that it manages. It then tells the ManagedEndpoint about the new data through the protected NewDataArrived() member function.

The MemoryManager's buffers can be static or dynamic, in normal memory or in some form of secondary memory the MemoryManager is allowed to store that block any way it sees fit. Like STL's custom allocators, this mechanism can be used to completely change the way the endpoint allocates memory. Also like STL, most people will simply choose one of the default allocators, usually SparseMemoryManager which maintains a list of dynamically-allocated blocks of memory.

ContiguousMemoryManager is still on the drawing boards at this point. When written, it will allocate a large, contiguous buffer on construction, and then allocate chunks from that buffer as required. This method can be useful sometimes, but also susceptible to buffer overruns. Since I haven't written a program recently where that tradeoff was required or even acceptable, I've not written it yet.