Device Cache

Topics:

Overview
Block Diagram
Conditional Directives
Enumerations
Device Cache Functions
Device Bucket Cache Functions
Device Cache Pointer Functions

Overview

The Device Cache consist of series of cooperating classes used to buffer raw data as it moved to and from input and output devices, such as disk files, stream sockets, datagram sockets, serial ports, etc. It was specifically designed to handle large data transfers in the form of continuous streams or controlled bursts. The Device Cache works through multiple inheritance with three primary classes comprising the user interface: the gxDeviceCache class, the gxDeviceBucketCache class, and the gxDeviceCachePtr class.

The gxDeviceCache class is an abstract base class used to define the methods needed to interface a device with the memory cache. The derived class determines the type of device the cache will be linked to. The derived class is also responsible for defining the methods used to read and write to and from the device as well as keep track of the device status. The device cache will buffer a stream of binary data as is it is written to or read from the device the derived class is using to perform I/O operations.

The gxDeviceBucketCache class is responsible for the allocation and de-allocation of a fixed number of cache buckets and incorporates functions used to handle requests for memory-based I/O buffers. The cache must determine whether an I/O buffer is already loaded. If the buffer is not loaded the cache reserves a bucket and loads the buffer into memory. This cache design uses cache pointers to reference cache buckets directly, with each cache pointer being initialized after the bucket is reserved. Cache buckets are organized into a doubly linked list with the number of buckets determined when a gxDeviceBucketCache object is constructed.

The gxDeviceCachePtr class is used to access cache buckets directly, which allows the user to load and unload I/O buffers as needed. Cache pointers are used to work in conjunction with the cache buckets. Each cache pointer stores a pointer to the bucket containing the I/O memory buffer and a pointer to the cache the cache pointer is connected to.

Conditional Directives

This cache design supports both variable length and fixed length cache buckets. In order to support multiple bucket types the MBTYPE definition is used to define the bucket data type. The bucket data type is set by a conditional directive that allows the device cache classes to use variable or fixed length buffers. Each type must be determined at compile time and only one type can be used for each compile. NOTE: Resizable cache buckets will be used by default. The following conditional directives can be used to support the following bucket data types:

__SMEMORY_BLOCK__ - Fixed length memory (static) blocks using the MemoryBlock type.

__VMEMORY_BUFFER__ - Resizable memory buffers using the MemoryBuffer type.

Enumerations

This gxDeviceTypes enumeration is used to define the various devices types used by the communications library.

enum gxDeviceTypes {
  gxDEVICE_VOID = 0,        // Not pointing to any valid device
  gxDEVICE_CONSOLE,         // Using the console for I/O operations 
  gxDEVICE_DATAGRAM_SOCKET, // Using a datagram socket for I/O  
  gxDEVICE_DISK_FILE,       // Using a disk file for I/O operations
  gxDEVICE_MEMORY_BUFFER,   // Using a memory buffer for I/O operations
  gxDEVICE_NULL,            // Dump I/O into the bit bucket
  gxDEVICE_SERIAL_PORT,     // Using a serial port for I/O operations
  gxDEVICE_STREAM_SOCKET    // Using a stream socket for I/O operations
};

Device Cache Functions

gxDeviceCache::gxDeviceCache()
gxDeviceCache::~gxDeviceCache()
gxDeviceCache::Read()
gxDeviceCache::ReadyForReading()
gxDeviceCache::ReadyForWriting()
gxDeviceCache::Write()

gxDeviceCache::gxDeviceCache() - Default class constructor.

virtual gxDeviceCache::~gxDeviceCache() - Class destructor provided for virtuality.

virtual void gxDeviceCache::Read(void *buf, unsigned Bytes, gxDeviceTypes dev) Pure virtual member function used by the device cache classes to read a specified number of bytes from an input device. The "dev" variable is used to map the input device and must correspond to one of the integer constants defined in the gxDeviceTypes enumeration.

int gxDeviceCache::ReadyForReading() - Public member function used by the device cache classes to determine if an input device is ready for to be read.

int gxDeviceCache::ReadyForWriting() - Public member function used by the device cache classes to determine if an output device is can be written to.

virtual void gxDeviceCache::Write(const void *buf, unsigned Bytes, gxDeviceTypes dev) - Pure virtual member function used by the device cache classes to write a specified number of bytes to an output device. The "dev" variable is used to map the output device and must correspond to one of the integer constants defined in the gxDeviceTypes enumeration.

Device Bucket Cache Functions

The gxDeviceBucket data structure is a cache node used to define how each bucket will be loaded/stored and which device will be used for every input/output operation. gxDeviceBucket objects are organized in a contiguous circular linked list by the gxDeviceBucketCache class.

class gxDeviceBucket: public MBTYPE
{
public:
  gxDeviceTypes o_device; // Output device this bucket is connected to
  gxDeviceTypes i_device; // Input device this bucket is connected to
  gxDeviceBucket *prev;   // Previous bucket in the list
  gxDeviceBucket *next;   // Next bucket in the list
};

gxDeviceBucket functions:
gxDeviceBucket::FlushBucket()
gxDeviceBucket::IsDirty()
gxDeviceBucket::ReadBucket()
gxDeviceBucket::ResetBucket()
gxDeviceBucket::WriteBucket()

void gxDeviceBucket::FlushBucket(gxDeviceCache &dev) - Public member function used to flush this cache bucket to the specified device and reset the dirty flag.

int gxDeviceBucket::IsDirty() - Public member function that returns true when the bucket is in use or false when empty. This "is_dirty" flag locks the bucket following a read operation and unlocks the bucket following a write operation.

void gxDeviceBucket::ReadBucket(gxDeviceCache &dev, unsigned bytes = 0) - Public member function used to read a specified number of bytes from this device. If a zero byte size is specified the bucket will be locked and the bucket data must be loaded manually.

void gxDeviceBucket::ResetBucket() - Public member function used to reset the all the bucket flags and direct all I/O operations to a void device.

void gxDeviceBucket::WriteBucket(gxDeviceCache &dev) - Public member function used to write the contents of this cache bucket to the specified device.

The gxDeviceBucketCache class is used to handle the allocation and de-allocation of buckets. The cache must determine whether an object is already loaded. If the object is not loaded the cache reserves a bucket and loads the object into memory.

gxDeviceBucketCache::gxDeviceBucketCache(unsigned num) - Class constructor responsible for allocating a specified number of cache buckets and organizing the buckets in a contiguous circular linked list

gxDeviceBucketCache::~gxDeviceBucketCache() - Class destructor responsible for flushing the cache and de-allocating the cache buckets.

gxDeviceBucket *gxDeviceBucketCache::AllocBucket(gxDeviceTypes o_dev, gxDeviceTypes i_dev,unsigned bytes = 0) - Public member function used to connect a cache bucket to the specified I/O device and read a specified number of bytes from the input device. Returns a pointer to the bucket or a null value if an error occurred.

unsigned gxDeviceBucketCache::BucketsInUse() - Public member function use to obtain the total number of dirty buckets.

void gxDeviceBucketCache::Clear() - Public member function used to flush all buckets in the cache.

void gxDeviceBucketCache::Connect(gxDeviceCache *dev) - Public member function used to connect the cache to an I/O device. NOTE: This function will clear the cache if previously connected.

gxDeviceBucket *gxDeviceBucketCache::ConstructCache(unsigned num) - Public member function used to construct and initialize and array of buckets. NOTE: This implementation uses contiguous memory for the cache buckets. Returns a pointer to the bucket array or a null value if an error occurs.

void gxDeviceBucketCache::DestroyCache() - Public member function used to flush all the cache buckets and frees the memory allocated for the cache bucket array.

void gxDeviceBucketCache::Disconnect() - Public member function used to clear and disconnect the cache from a previously connected I/O device.

int gxDeviceBucketCache::Flush() - Public member function used to flush all the buckets in the cache. Returns true if successful or false if an error occurs.

int gxDeviceBucketCache::GetBuckets() - Public member function that returns the total number of cache buckets that have been allocated.

gxDeviceBucket *gxDeviceBucketCache::GetHead() - Public member function that returns a pointer to the first bucket.

gxDeviceBucket *gxDeviceBucketCache::GetTail() - Public member function that returns a pointer to the last bucket.

int gxDeviceBucketCache::IsEmpty() - Public member function that returns true if no memory has been allocated for the cache bucket array of the cache bucket array has been destroyed.

int gxDeviceBucketCache::rFlush() - Public member function used to flush all buckets in reverse order. Returns true if successful or false if an error occurs.

Device Cache Pointer Functions

gxDeviceCachePtr::gxDeviceCachePtr()
gxDeviceCachePtr::~gxDeviceCachePtr()
gxDeviceCachePtr::Alloc()
gxDeviceCachePtr::GetInputDevice()
gxDeviceCachePtr::GetOutputDevice()
gxDeviceCachePtr::Release()
gxDeviceCachePtr::SetCache()
gxDeviceCachePtr::SetInputDevice()
gxDeviceCachePtr::SetOutputDevice()
gxDeviceCachePtr::operator*()
gxDeviceCachePtr::operator->()

gxDeviceCachePtr::gxDeviceCachePtr(gxDeviceBucketCache &c, gxDeviceTypes o_dev,gxDeviceTypes i_dev) - Class constructor used to connect the pointer to a previously constructed cache. The "i_dev" and "o_dev" variables are used to map the I/O device and must correspond to one of the integer constants defined in the gxDeviceTypes enumeration.

gxDeviceCachePtr::gxDeviceCachePtr(const gxDeviceCachePtr &ob) - Copy constructor that will release the bucket this object forcing this pointer to reference another bucket.

gxDeviceCachePtr& gxDeviceCachePtr::operator=(const gxDeviceCachePtr &ob) - Assignment operator that will release the bucket this object forcing this pointer to reference another bucket.

gxDeviceCachePtr::~gxDeviceCachePtr() - Class destructor.

MBTYPE *gxDeviceCachePtr::Alloc(unsigned bytes = 0) - Public member function used to reserve a cache bucket and automatically loads a specified number of bytes into the bucket from the input device the bucket is connected to. NOTE: If a zero byte value is specified no data will be read from the input device.

gxDeviceTypes gxDeviceCachePtr::GetInputDevice() - Public member function used to retrieve the current input device. Returns an integer constant defined in the gxDeviceTypes enumeration.

gxDeviceTypes gxDeviceCachePtr::GetOutputDevice() - Public member function used to retrieve the current output device. Returns an integer constant defined in the gxDeviceTypes enumeration.

void gxDeviceCachePtr::Release() - Public member function used to release the bucket this pointer is currently holding.

void gxDeviceCachePtr::SetCache(gxDeviceBucketCache *c) - Public member function used to connect this pointer to a previously constructed cache object.

void gxDeviceCachePtr::SetInputDevice(gxDeviceTypes dev) - Public member function used to set the input device. The "dev" variable is used to set the input device and must correspond to one of the integer constants defined in the gxDeviceTypes enumeration.

void gxDeviceCachePtr::SetOutputDevice(gxDeviceTypes dev) - Public member function used to set the output device. The "dev" variable is used to set the output device and must correspond to one of the integer constants defined in the gxDeviceTypes enumeration.

gxDeviceBucket & gxDeviceCachePtr::operator*() - Overloaded indirection operator that allows device cache pointers to dereference the bucket this object is currently referencing.

gxDeviceBucket *gxDeviceCachePtr::operator->() - Overloaded arrow operator used to reference a device cache pointer to the bucket it is currently referencing.

End Of Document