---

Buffer Class Template Reference

Template class definition for basic buffer type object. More...

#include <Buffer.h>

Inheritance diagram for Buffer::

List of all members.

Public Methods
	Buffer ()
	Basic constructor. More...
	Buffer (int l)
	Constructor (with size, don't wait). More...
	~Buffer ()
	Basic destructor. More...
void	DumpBag (ostream &aStream)
	Dump the reference pointer bag. More...
void	ReferenceBy (BasicPointer *p)
	Add a pointer to the reference bag. More...
void	DereferenceBy (BasicPointer *p)
	Remove a pointer from the reference bag. More...
ostream &	Print (ostream &aStream)
	Print this object to an ostream. More...
void	Release ()
	Release this buffer. More...
void	Route ()
	Route this buffer (and release the buffer). More...
bool	Accept (struct timeval *pTO=NULL)
	Accept a list of blocks from elsewhere. More...
bool	Resize (int siz, bool w)
	Resize this buffer. More...
Pointer< Buffer< ALLOC, BLKTYPE, BTYPE >, BTYPE > &	operator & ()
	Get pointer of (prefix operator). More...
BTYPE &	operator[] (const int &idx)
	Subscript access to this buffer. More...
int	GetLen ()
	Return the number of slots in the buffer. More...
int	FreeSpace (BasicPointer &p)
	Return the buffer free space. More...
int	FreeSpace ()
	Return the buffer free space. More...
size_t	Write (int aFd, size_t aStart, size_t aLen)
	Write a buffer to a file descriptor. More...
size_t	Read (int aFd, size_t aStart, size_t aLen)
	Read a buffer to a file descriptor. More...
virtual void	DumpNative (ostream &aStream, int aCnt)
	Dump the buffer in its native tongue with length. More...
void	DumpNative (ostream &aStream)
	Dump the buffer in its native tongue. More...
void	Dump (ostream &aStream, int aCnt)
	Dump the buffer as hex and character data. More...
void	Dump (ostream &aStream)
	Dump the buffer as hex and character data. More...
void	SetTag (unsigned int aTag)
	Set the buffer routing tag. More...
unsigned int	GetTag ()
	Get the buffer routing tag. More...
void	SetMask (unsigned int aMask)
	Set the buffer routing mask. More...
unsigned int	GetMask ()
	Get the buffer routing mask. More...
Protected Methods
void	Init (int l)
	Initialize this buffer. More...
int	ExpandToPageSize ()
	Expand this buffer's size to the current maximum. More...
void	Nullify ()
	Nullify all pointers to this buffer. More...

---

Detailed Description

template<class ALLOC, class BLKTYPE, class BTYPE>
class Buffer< ALLOC, BLKTYPE, BTYPE >

The Buffer template class defines the basic structure of a buffer object as it is used in the SpectroDAQ system. This template expects a block type and a allocator type as parameters. See the Block and BufferAllocator classes in BufferAllocator.h for more information. Additionally the primitive type used by the block parameter needs to be specified (e.g. int, char, ...).

 To correctly instantiate a Buffer object you need to:

    Where:
      BTYPE - primative type used by buffer blocks.
      A_Block - block object type (see BufferAllocator)
      A_BufferAllocator - buffer allocator object type 
            (see BufferAllocator)

    1. class A_Block : public Block<BTYPE> {...}
    2. class A_BufferAllocator : public BufferAllocator<A_Block> {...}
    3. class A_Buffer : public Buffer<A_BufferAllocator,A_Block,
                                              BTYPE> {...}
 

Author:

Eric Kasten

Version:

0.4.0

---

Constructor & Destructor Documentation

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::Buffer (  )  [inline]

Basic constructor for this class. Parameters: None   Returns: this

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::Buffer (  int l )  [inline]

Constructor where the size can be specified. The size is specified in units of the primitive type (BTYPE). The acquisition doesn't wait for completion if requisite number of blocks cannot be acquired. Thus, the buffer may still be of zero length upon return from the constructor. Parameters: l   The desired initial length as a count of primitive units Returns: this

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::~Buffer (  )  [inline]

Basic destructor for this class. Parameters: None   Returns: None

---

Member Function Documentation

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::Accept (  struct timeval * pTO = NULL )  [inline]

This method accepts a buffer (as a list of blocks) that was transmited using Route(). This buffer should be tagged with the appropriate tag/mask combination to match the desired type(s) of buffers for which reception is desired. The pTO parameter indicates the length of time to wait for an arriving buffer. If pTO is NULL, then wait forever. For a buffer on the server to be accepted by this buffer the tag/mask of the buffer and the buffer on the server must be as follows: (server_tag & buffer_mask) == (buffer_tag & buffer_mask) Parameters: pTO   Indicates how long to wait for a buffer. Returns: If a buffer was accepted Return values: true   A buffer was accepted false   A buffer wasn't accepted

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::DereferenceBy (  BasicPointer * p )  [inline]

Removes a pointer (see Pointer.h) from the reference bag. Utility function typically not used externally. Parameters: p   A BasicPointer that references this Buffer. Returns: None

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::Dump (  ostream & aStream )  [inline]

Dump all of this buffer to an ostream. The contents are printed as both hex characters and (if printable) ascii characters. Printing begins at the start of the buffer. Parameters: aStream   the ostream on which to print Returns: None

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::Dump (  ostream & aStream, int aCnt )  [inline]

Dump part of this buffer to an ostream. The contents are printed as both hex characters and (if printable) ascii characters. Printing begins at the start of the buffer. Parameters: aStream   the ostream on which to print aCnt   The number of characters to print Returns: None

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::DumpBag (  ostream & aStream )  [inline]

Method used for debugging Buffer objects. Dumps the pointers from the pointer reference bag (see Pointer.h). Shouldn't be used in normal Buffer usage. Parameters: aStream   The ostream for printing. Returns: None

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::DumpNative (  ostream & aStream )  [inline]

Dump all of this buffer to an ostream. The contents are printed using the default format of the buffer's primitive units. Printing begins at the start of the buffer. Parameters: aStream   the ostream on which to print Returns: None

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::DumpNative (  ostream & aStream, int aCnt )  [inline, virtual]

Dump part of this buffer to an ostream. The contents are printed using the default format of the buffer's primitive units. Printing begins at the start of the buffer. Parameters: aStream   the ostream on which to print aCnt   The number of units to print Returns: None

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::ExpandToPageSize (  )  [inline, protected]

Expand this buffer's size to the current maximum. The current maximum is determined by the number of blocks acquired to fullfil the user's requested buffer size. This is an internal utility method. m None Returns: The current size

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::FreeSpace (  )  [inline]

Return the free space in the buffer as calcluated as the difference between request length and the slots used. Parameters: None   Returns: The amount of free space available

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::FreeSpace (  BasicPointer & p )  [inline]

Return the free space in the buffer as calcluated as the difference between the pointer index and requested length. Parameters: p   The BasicPointer used to calculate the difference. Returns: The amount of free space available Exceptions: DAQOutOfBounds   If the index pointer is out-of-bounds

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::GetLen (  )  [inline]

Retruns the number of primitive objects (BTYPE) that can be contained in this buffer. Parameters: None   Returns: The number of slots in the buffer

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::GetMask (  )  [inline]

Returns the current routing mask of this buffer. This is set by SetMask(). Parameters: None   Returns: The current routing mask

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::GetTag (  )  [inline]

Returns the current routing tag of this buffer. This is set either by SetTag() or when a buffer is Accept()ed. Parameters: None   Returns: The current routing tag

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::Init (  int l )  [inline, protected]

Initialize this buffer. This is usually called by a constructor method. A size in primitive units (BTYPE) can be specified. Parameters: l   A size in primitive units Returns: None

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::Nullify (  )  [inline, protected]

Nullify all pointers to this buffer. That is, if there are any Pointer references to this buffer they should be updated such that they point to no object. This is an internal utility method. Parameters: None   Returns: None

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::Print (  ostream & aStream )  [inline, virtual]

Print a representation of this object to an ostream. Parameters: aStream   The ostream on which to print this. Returns: The ostream Reimplemented from Printable.

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::Read (  int aFd, size_t aStart, size_t aLen )  [inline]

Read in the contents of this buffer from a file descriptor. The read begins at the position indicated (in primitive type units) within the buffer and continues for the specified length. Parameters: aFd   The file descriptor from which to read aStart   Buffer position frow which to begin reading. aLen   Number of primitive units to read Returns: The number of primitive units read Exceptions: DAQOutOfBounds   If aLen or aStart are out-of-bounds OSException   On file descriptor read errors

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::ReferenceBy (  BasicPointer * p )  [inline]

Adds a pointer (see Pointer.h) to the reference bag. Utility function typically not used externally. Parameters: p   A BasicPointer that references this Buffer. Returns: None

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::Release (  )  [inline]

Release all the underlying storage blocks associated with this buffer. After the Release() the buffer's length will be zero. Parameters: None   Returns: None

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::Resize (  int siz, bool w )  [inline]

Resizes this buffer to a larger or smaller size. The size is specified as a count of the number of primative units (BTYPE). Parameters: siz   The desired new size for the buffer w   Set to true if you want this method to block Returns: If the resize succeeded Return values: true   if the resize succeeded false   if the resize failed

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::Route (  )  [inline]

Send this buffer up to the SpectroDAQ server for transmital to another machine and/or process. This buffer will of zero length once Routed. m None Returns: None

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::SetMask (  unsigned int aMask )  [inline]

Set this buffer's routing mask. This mask is used to help determine where this buffer should be sent when Route() is called. Parameters: aMask   The desired mask Returns: None

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::SetTag (  unsigned int aTag )  [inline]

Set this buffer's routing tag. This tag is used to help determine where this buffer should be sent when Route() is called. Parameters: aTag   The desired routing tag Returns: None

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::Write (  int aFd, size_t aStart, size_t aLen )  [inline]

Write the contents of this buffer to a file descriptor. The write begins at the position indicated (in primitive type units) within the buffer and continues for the specified length. Parameters: aFd   The file descriptor on which to write aStart   Buffer position frow which to begin writing. aLen   Number of primitive units to write Returns: The number of primitive units written Exceptions: DAQOutOfBounds   If aLen or aStart are out-of-bounds OSException   On file descriptor write errors

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::operator & (  )  [inline]

Returns a Pointer (see Pointer) object that points to this. Parameters: None   Returns: A Pointer object to this

template<class ALLOC, class BLKTYPE, class BTYPE> Buffer< ALLOC, BLKTYPE, BTYPE >::operator[] (  const int & idx )  [inline]

This method provides subscript access to the contents of this buffer. The units returned are the primitive type (BTYPE). Parameters: idx   The position (starting at 0) to access. Returns: The primitive value at the specified location Exceptions: DAQOutOfBounds   If the index is out-of-bounds DAQCorrupt   If the buffer appears to be corrupt

---

The documentation for this class was generated from the following file:

• Buffer.h

---