Opaque user data
[Win32 Tools Library]
Collaboration diagram for Opaque user data:
|
Detailed Description
Opaque user data is the name given to the concept of storing an arbitrary number of void * pieces of 'user data' in a class. The user of the class knows what the data is, the class itself doesn't care and, to it, the data is opaque. Generally the class that supports user data inherits from IIndexedOpaqueUserData and when it's created it has x 'slots' of user data created with it. Users of the class can then store their own things in the class. Classes that allocate objects that support user data generally inherit from IProvideUserData which allows the users to request a user data 'slot' and get given an index to it. Generally users request their slots before the first object that supports user data from this allocator is allocated (so all objects have the same number of slots!). Indices are allocated by name (and this is often the name of the class doing the requesting) so that there's no need for a central repository of information relating to how many user data slots each object needs to support. An example of this code in action can be seen in the IO Tools library with the IBufferAllocator and IBuffer interfaces and the Socket Tools library with the ISocketAllocator and various socket classes. The extensible nature of this design means that it's easy for code to be layered on top of the existing code that uses (and requires) user data in the sockets or buffers and for it to require as much or as little user data as it likes. The intefaces for this should probably be moved to the C++ Tools library as there's no dependency on Win32.
Classes | |
| class | IIndexedOpaqueUserData |
| Provides an interface that allows access to 'opaque user data' that is data that is stored as either a void * or an unsigned long and that is basically anything that the user wants to store. The data is stored by index and an implementation of this class is free to store the data in any way that it sees fit. An index represents a single storage location so a call to GetUserPointer() and GetUserData() on the same index will return the same data, just viewed in different ways. More... | |
| class | TIndexedOpaqueUserData |
| Implements IIndexedOpaqueUserData in terms of a std::vector of void *. More... | |
| class | IProvideUserData |
| An interface that works with IIndexedOpaqueUserData to allow users of a class that provides opaque user data to request a named 'slot' for their data. Generally what happens is that an allocator will expose this interface and the allocated items will expose the interface to access the user data. Users of the allocator can request named slots of user data before allocating the first item and then all items are created with the required amount of user data space. More... | |
| class | CNamedIndex |
| A class that provides a collection of named indices. That is it allows you to Add() or Find() a name to a collection and return an index that identifies that name within the collection. Once you have added as many names as you wish you can convert the collection of names into a read-only collection by calling Lock() on the collection. The class is designed to be used to allow unrelated blocks of code to request a unique index for use in accessing opaque user data from an instance of IIndexedOpaqueUserData. The blocks of code needing an index typically request one by name (usually based on the name of the class doing the requesting). Once all names have been requested, Lock() is called and the size of the user data block required is calculated by calling GetMaxIndexValue() to return the number of indices requested. More... | |
| class | COpaqueUserData |
| A class that provides a single instance of 'opaque user data' (that is data that is stored as either a void * or an unsigned long and that is basically anything that the user wants to store). This represents a single storage location so a call to GetUserPointer() and GetUserData() will return the same data, just viewed in different ways. More... | |
| class | CBuffer |
| An implementation of the IBuffer interface which includes its own custom new and delete functionality so that the memory for the buffer and the memory for the rest of the class are allocated as a single block of memory. Note that the 'user data' is also allocated as part of the main buffer memory and the class knows how to access the various memory areas correctly. Note that the buffers may be allocated using VirtualAlloc() to align the memory on page boundaries; in this case, it's best to create buffers with a size that is a multiple of the system's page size less the size of the buffer object, see CBufferAllocator for more details. More... | |
| class | CBufferAllocator |
| An implementation of IAllocateBuffers which pools buffer instances for later reuse. More... | |
| class | IAllocateBuffers |
| An interface to a class that allocates instances of IBuffer of a fixed size. Each instance of IBuffer has opaque user data associated with it and so this allocator derives from IProvideUserData to allow the user to request user data "slots" from the allocator; you must request all of your slots before calling Allocate() for the first time. More... | |
| class | IBufferChain |
| class | CDatagramServerSocket |
| A datagram socket that allows you to SendTo() any host but restricts who you can RecvFrom(), basically you can only recv data from the port that the associated server is listening on. More... | |
| class | CDatagramServerSocketAllocator |
| A socket allocator that allocates datagram server sockets. Note that most of the work is down in CSocketAllocator. More... | |
| class | CDatagramSocket |
| A datagram socket that allows you to RecvFrom() and SendTo() any host. More... | |
| class | CDatagramSocketAllocator |
| A socket allocator that allocates datagram sockets. Note that most of the work is down in CSocketAllocator. More... | |
| class | IPoolableSocket |
| The IPoolableSocket interface provides the 'poolability' of the sockets. Poolable sockets are pooled using a CNodeList and so, for a socket to be pooled it must derive from CNodeList::Node. When a socket is used from the pool or released to the pool the allocator passes the socket's user data to the allocation monitor and so poolable sockets must support IIndexedOpaqueUserData. More... | |
| class | CSequencedStreamSocket |
| A stream socket that supports read and write sequencing. More... | |
| class | CSequencedStreamSocketAllocator |
| A socket allocator that allocates instances of CSequencedStreamSocket Note that most of the work is down in CSocketAllocator. More... | |
| class | CSocketAllocator |
| A base class for socket allocation. There are several different types of socket that are used through the library. Most of the work involved in allocating sockets and managing a pool of sockets is the same for all types. The only things that change are the type of the socket that is being allocated and the way the socket is created. Derived classes provide this functionality. More... | |
| class | CStreamSocket |
| A stream socket. Note that this socket does NOT support read and write sequencing. More... | |
| class | CStreamSocketAllocator |
| A socket allocator that allocates instances of CStreamSocket. Note that most of the work is down in CSocketAllocator. More... | |
