Bayonne2 / Common C++ 2 Framework
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Member Functions | Static Public Attributes | Protected Member Functions | Private Attributes | Related Functions
Buffer Class Referenceabstract

The buffer class represents an IPC service that is built upon a buffer of fixed capacity that can be used to transfer objects between one or more producer and consumer threads. More...

#include <buffer.h>

Inheritance diagram for Buffer:
Inheritance graph
[legend]
Collaboration diagram for Buffer:
Collaboration graph
[legend]

Public Member Functions

 Buffer (size_t capacity)
 Create a buffer object of known capacity. More...
 
virtual ~Buffer ()
 In derived functions, may be used to free the actual memory used to hold buffered data. More...
 
size_t getSize (void)
 Return the capacity of the buffer as specified at creation. More...
 
size_t getUsed (void)
 Return the current capacity in use for the buffer. More...
 
size_t wait (void *buf, timeout_t timeout=0)
 Let one or more threads wait for an object to become available in the buffer. More...
 
size_t post (void *buf, timeout_t timeout=0)
 Post an object into the buffer and enable a waiting thread to receive it. More...
 
size_t peek (void *buf)
 Peek at the current content (first object) in the buffer. More...
 
virtual bool isValid (void)
 New virtual to test if buffer is a valid object. More...
 
void signal (bool broadcast)
 Signal a conditional object and a waiting threads. More...
 
bool wait (timeout_t timer=0, bool locked=false)
 Wait to be signaled from another thread. More...
 
void enterMutex (void)
 Locks the conditional's mutex for this thread. More...
 
void lock (void)
 In the future we will use lock in place of enterMutex since the conditional composite is not a recursive mutex, and hence using enterMutex may cause confusion in expectation with the behavior of the Mutex class. More...
 
bool tryEnterMutex (void)
 Tries to lock the conditional for the current thread. More...
 
bool test (void)
 
void leaveMutex (void)
 Leaving a mutex frees that mutex for use by another thread. More...
 
void unlock (void)
 

Static Public Attributes

static const size_t timeout
 value to return when a timed operation returned with a timeout. More...
 

Protected Member Functions

virtual size_t onPeek (void *buf)=0
 Invoke derived class buffer peeking method. More...
 
virtual size_t onWait (void *buf)=0
 Invoke derived class object request from buffer. More...
 
virtual size_t onPost (void *buf)=0
 Invoke derived class posting of object to buffer. More...
 

Private Attributes

size_t _size
 
size_t _used
 

Related Functions

(Note that these are not member functions.)

size_t get (Buffer &b, void *o, timeout_t t=0)
 
size_t put (Buffer &b, void *o, timeout_t t=0)
 
size_t peek (Buffer &b, void *o)
 

Detailed Description

The buffer class represents an IPC service that is built upon a buffer of fixed capacity that can be used to transfer objects between one or more producer and consumer threads.

Producer threads post objects into the buffer, and consumer threads wait for and receive objects from the buffer. Semaphores are used to to block the buffer from overflowing and indicate when there is data available, and mutexes are used to protect multiple consumers and producer threads from stepping over each other.

The buffer class is an abstract class in that the actual data being buffered is not directly specified within the buffer class itself. The buffer class should be used as a base class for a class that actually impliments buffering and which may be aware of the data types actually are being buffered. A template class could be created based on buffer for this purpose. Another possibility is to create a class derived from both Thread and Buffer which can be used to implement message passing threads.

Author
David Sugar dyfet.nosp@m.@ost.nosp@m.el.co.nosp@m.m Producer/Consumer buffer for use between threads.

Definition at line 81 of file buffer.h.

Constructor & Destructor Documentation

Buffer::Buffer ( size_t  capacity)

Create a buffer object of known capacity.

Parameters
capacityis the integer capacity of the buffer.
virtual Buffer::~Buffer ( )
virtual

In derived functions, may be used to free the actual memory used to hold buffered data.

Member Function Documentation

void Conditional::enterMutex ( void  )
inherited

Locks the conditional's mutex for this thread.

Remember that Conditional's mutex is NOT a recursive mutex!

See Also
leaveMutex
size_t Buffer::getSize ( void  )
inline

Return the capacity of the buffer as specified at creation.

Returns
size of buffer.

Definition at line 135 of file buffer.h.

size_t Buffer::getUsed ( void  )
inline

Return the current capacity in use for the buffer.

Free space is technically getSize() - getUsed().

Returns
integer used capacity of the buffer.
See Also
getSize

Definition at line 144 of file buffer.h.

virtual bool Buffer::isValid ( void  )
virtual

New virtual to test if buffer is a valid object.

Returns
true if object is valid.

Reimplemented in FixedBuffer.

void Conditional::leaveMutex ( void  )
inherited

Leaving a mutex frees that mutex for use by another thread.

See Also
enterMutex
void Conditional::lock ( void  )
inlineinherited

In the future we will use lock in place of enterMutex since the conditional composite is not a recursive mutex, and hence using enterMutex may cause confusion in expectation with the behavior of the Mutex class.

See Also
enterMutex

Definition at line 686 of file thread.h.

virtual size_t Buffer::onPeek ( void *  buf)
protectedpure virtual

Invoke derived class buffer peeking method.

Returns
size of object found.
Parameters
bufpointer to copy contents of head of buffer to.

Implemented in ost::BayonneMsgport, and FixedBuffer.

virtual size_t Buffer::onPost ( void *  buf)
protectedpure virtual

Invoke derived class posting of object to buffer.

Returns
size of object posted.
Parameters
bufpointer to object being posted to the buffer.

Implemented in ost::BayonneMsgport, and FixedBuffer.

virtual size_t Buffer::onWait ( void *  buf)
protectedpure virtual

Invoke derived class object request from buffer.

Returns
size of object returned.
Parameters
bufpointer to hold object returned from the buffer.

Implemented in ost::BayonneMsgport, and FixedBuffer.

size_t Buffer::peek ( void *  buf)

Peek at the current content (first object) in the buffer.

Returns
size of object in the buffer.
Parameters
bufpointer to store object found in the buffer.
size_t Buffer::post ( void *  buf,
timeout_t  timeout = 0 
)

Post an object into the buffer and enable a waiting thread to receive it.

Returns
size of object posted in bytes.
Parameters
bufpointer to object to store in the buffer.
timeouttime to wait.
void Conditional::signal ( bool  broadcast)
inherited

Signal a conditional object and a waiting threads.

Parameters
broadcastthis signal to all waiting threads if true.
bool Conditional::test ( void  )
inlineinherited

Definition at line 701 of file thread.h.

bool Conditional::tryEnterMutex ( void  )
inherited

Tries to lock the conditional for the current thread.

Behaves like enterMutex , except that it doesn't block the calling thread.

Returns
true if locking the mutex was succesful otherwise false
See Also
enterMutex
leaveMutex
void Conditional::unlock ( void  )
inlineinherited

Definition at line 711 of file thread.h.

size_t Buffer::wait ( void *  buf,
timeout_t  timeout = 0 
)

Let one or more threads wait for an object to become available in the buffer.

The waiting thread(s) will wait forever if no object is ever placed into the buffer.

Returns
size of object passed by buffer in bytes.
Parameters
bufpointer to store object retrieved from the buffer.
timeouttime to wait.
bool Conditional::wait ( timeout_t  timer = 0,
bool  locked = false 
)
inherited

Wait to be signaled from another thread.

Parameters
timertime period to wait.
lockedflag if already locked the mutex.

Friends And Related Function Documentation

size_t get ( Buffer b,
void *  o,
timeout_t  t = 0 
)
related

Definition at line 350 of file buffer.h.

size_t peek ( Buffer b,
void *  o 
)
related

Definition at line 358 of file buffer.h.

size_t put ( Buffer b,
void *  o,
timeout_t  t = 0 
)
related

Definition at line 354 of file buffer.h.

Field Documentation

size_t Buffer::_size
private

Definition at line 88 of file buffer.h.

size_t Buffer::_used
private

Definition at line 89 of file buffer.h.

const size_t Buffer::timeout
static

value to return when a timed operation returned with a timeout.

Definition at line 118 of file buffer.h.


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