IPQ (InterProcessQueue) provides a generic way for information to be shared between processes or threads. More...

#include <carma/util/IPQbufferBase.h>

Inheritance diagram for carma::util::IPQbufferBase:

Public Member Functions
int	getElementSize () const
	Returns the size of each element in the queue in bytes. More...

::std::string	getFileName () const
	Get the filename. More...

unsigned int	getGetOffset () const
	Useful only for debugging. More...

unsigned int	getLostElementCount () const
	Get the number of elements lost on the last read. More...

unsigned int	getMaxOffset () const
	Useful only for debugging. More...

int	getNumAvailable () const
	Gets the number of unread elements available in the queue. More...

unsigned int	getPutOffset () const
	Used internally, but made public for debugging. More...

int	getQueueSize () const
	Returns the allocated size of the queue. More...

bool	isDataAvailable () const
	Checks to see if there are any unread elements (would a read not block?). More...

bool	isEmpty () const
	Checks to see if the queue is empty. More...

unsigned int	read ()
	Read the oldest unread element from the queue. More...

bool	readNewest ()
	Get the newest element from the queue (with locking). More...

bool	readNewestConditionalCopy ()
	Reads and copies the newest element from the queue into the localElement buffer, but only if has not been previously read. More...

void	setNoneAvailable ()
	Sets the number of available (unread) elements to zero (catches up) More...

virtual	~IPQbufferBase ()
	Destructor Making this d'tor virtual causes the d'tors of inheriting classes to be called first when the d'tor is called on this base class (polymorphic), followed by the base class d'tor. More...

Public Member Functions inherited from carma::util::IPQinterface
virtual int	getElementSize () const =0
	Returns the size of each element in the queue in bytes. More...

virtual ::std::string	getFileName () const =0
	Get the filename. More...

virtual unsigned int	getGetOffset () const =0
	Useful only for debugging. More...

virtual unsigned int	getLostElementCount () const =0
	Get the number of elements lost on the last read. More...

virtual unsigned int	getMaxOffset () const =0
	Useful only for debugging. More...

virtual int	getNumAvailable () const =0
	Gets the number of unread elements available in the queue. More...

virtual unsigned int	getPutOffset () const =0

virtual int	getQueueSize () const =0
	Returns the allocated size of the queue. More...

virtual bool	isDataAvailable () const =0
	Checks to see if there are any unread elements (would a read not block?). More...

virtual bool	isEmpty () const =0
	Checks to see if the queue is empty. More...

virtual unsigned int	read ()=0
	Read the oldest unread element from the queue. More...

virtual bool	readNewest ()=0
	Get the newest element from the queue (with locking). More...

virtual bool	readNewestConditionalCopy ()=0
	Reads and copies the newest element from the queue into the localElement buffer, but only if has not been previously read. More...

virtual void	setNoneAvailable ()=0
	Sets the number of available (unread) elements to zero (catches up) More...

virtual	~IPQinterface ()=0
	Destructor Making this d'tor virtual causes the d'tors of inheriting classes to be called first when the d'tor is called on this base class (polymorphic), followed by the base class d'tor. More...

Protected Member Functions
virtual bool	createBuffer ()=0
	Create a new file or shared memory. More...

::std::string	getTrimmedFilename ()
	Get the trimmed filename. More...

void	init ()
	This does all the real constructor work. More...

	IPQbufferBase (void *localElement, int elementSize, const ::std::string &filename, bool isCreator=false, int nElements=0, unsigned int testOffset=0)
	Constructor for a read/write queue. More...

virtual bool	openBuffer ()=0
	Open an existing file or shared memory. More...

void	trimShmemFilename ()
	Shared memory filenames must contain only one '/' and it must be the first character; this routine fixes up the filename. More...

void	write ()
	Put an element into the queue. More...

Protected Member Functions inherited from carma::util::IPQinterface
virtual void	write ()=0
	Useful only for debugging. More...

Protected Attributes
bool	debug_

int	fileDescriptor_

const int	openMask_

const int	protectionMask_

Friends
class	BlockedOnSemaphoreQuitRequestHandler

Detailed Description

IPQ (InterProcessQueue) provides a generic way for information to be shared between processes or threads.

The queues are fixed in length (number of elements) and width (element size). The queues may be transient in shared memory or persistent in memory mapped files with these implementations provides by classes that implement the abstract methods of this class. This buffer class provides the actual storage mechanism. It also provides read and write methods to be inherited by the derived classes. This class throws exceptions, in particular on the constructor and the write methods, so make sure you catch them! Because this is a circular queue, if the reader falls more than the queue depth behind the writer then elements will be overwritten that can never be read and are lost forever. The read methods returns the number of lost elements.
Note that each instance of reader has its own set of pointers to keep track of where it is in the queue. A single instance shared by multiple threads has this feature, so it may only be useful if one of the threads is designated as the master reader. An exception is if the threads are just reading the most recent element off the top of the queue, in other words not really using the queue feature but more as a data sharing mechanism between writers and readers.

Some facts about Linux interactions with this class.

Shared memory is limited in size to half the physical memory size.
Shared memory exists in /dev/shm and can be deleted just like any file.
If you are using large objects (structures) for the elements, you can run into limitations caused by stack size. Increase stacksize with:
- csh(limit stacksize <sizeKB>) or
- sh(ulimit [-S][-H] -s <sizeKB>
Shared memory is much faster than a memory mapped file.
Memory mapped files off a fileserver are very slow.
Memory mapped files are limited to 2GB in size.

See Also: IPQreader, IPQwriter

Definition at line 77 of file IPQbufferBase.h.

Constructor & Destructor Documentation

carma::util::IPQbufferBase::IPQbufferBase	(	void *	localElement,
		int	elementSize,
		const ::std::string &	filename,
		bool	isCreator = `false`,
		int	nElements = `0`,
		unsigned int	testOffset = `0`
	)

protected

Constructor for a read/write queue.

The read pointer is placed at the bottom of the queue.

Parameters

localElement	address of the data buffer for reads/writes
elementSize	of an individual queue element in bytes
filename	Memory mapped or shared memory filename. Note that if a persistent file is used, it must be on a a native file system and not on an NFS mounted filesystem. On Linux the open will work, but information is not shared between processes, so you will just hang at some point.
isCreator	Controls file creation If true, create a new file, if one doesn't exist, and make its size match nElements
nElements	Number of elements to allocate (queue length); ignored if not a creator. Default is zero.
testOffset	When shared memory is created, set the putoffset to have testOffset full queues before it wraps around. Obviously for testing wrap around; zero (default) inhibits this feature.

Exceptions

std::exception

virtual carma::util::IPQbufferBase::~IPQbufferBase ( )

virtual

Destructor Making this d'tor virtual causes the d'tors of inheriting classes to be called first when the d'tor is called on this base class (polymorphic), followed by the base class d'tor.

Member Function Documentation

virtual bool carma::util::IPQbufferBase::createBuffer ( )

protectedpure virtual

Create a new file or shared memory.

The internal variable fileDescriptor must contain the descriptor to the open file after this call. Follow the return convention. Don't throw an exception, the next layer up takes care of that.

Returns: true if file open, false if not

int carma::util::IPQbufferBase::getElementSize ( ) const

Returns the size of each element in the queue in bytes.

Returns: the size of each element in the queue in bytes.

::std::string carma::util::IPQbufferBase::getFileName ( ) const

Get the filename.

unsigned int carma::util::IPQbufferBase::getGetOffset ( ) const

Useful only for debugging.

unsigned int carma::util::IPQbufferBase::getLostElementCount ( ) const

Get the number of elements lost on the last read.

If the writer gets too far ahead of the reader it can overwrite unread elements making them lost forever.

Returns: Number of elements lost on last read

unsigned int carma::util::IPQbufferBase::getMaxOffset ( ) const

Useful only for debugging.

int carma::util::IPQbufferBase::getNumAvailable ( ) const

Gets the number of unread elements available in the queue.

Returns: the number of unread elements in the queue

See Also: getQueueSize()

unsigned int carma::util::IPQbufferBase::getPutOffset ( ) const

Used internally, but made public for debugging.

int carma::util::IPQbufferBase::getQueueSize ( ) const

Returns the allocated size of the queue.

The queue may not be full, and some of it may be already read.

Returns: the size of the queue (but it may not be full!)

See Also: getNumAvailable()

::std::string carma::util::IPQbufferBase::getTrimmedFilename ( )

protected

Get the trimmed filename.

void carma::util::IPQbufferBase::init ( )

protected

This does all the real constructor work.

Mandatory: the child class must call this in its constructor.

Exceptions

std::exception

bool carma::util::IPQbufferBase::isDataAvailable ( ) const

Checks to see if there are any unread elements (would a read not block?).

Returns: true if a read would not block

bool carma::util::IPQbufferBase::isEmpty ( ) const

Checks to see if the queue is empty.

Returns: true if the queue is empty

virtual bool carma::util::IPQbufferBase::openBuffer ( )

protectedpure virtual

Open an existing file or shared memory.

The internal variable fileDescriptor must contain the descriptor to the open file after this call. Follow the return convention. Don't throw an exception, the next layer up takes care of that.

Returns: true if file open, false if not

unsigned int carma::util::IPQbufferBase::read ( )

Read the oldest unread element from the queue.

This is a blocking read that will wait for new data if there is no unread data available. This method does a lock/copy/unlock on the queue. At the completion of the read the data is copied into the localElement buffer

Returns: number of elements lost in the queue that can never be retrieved.

Exceptions

std::exception

bool carma::util::IPQbufferBase::readNewest ( )

Get the newest element from the queue (with locking).

This is not a blocking operation. If the queue is empty false is returned, otherwise true. At the completion of this method, no elements will be unread and the data from the most recent element will be copied into the localElement buffer.

Returns: true if the queue is not empty

Exceptions

std::exception

bool carma::util::IPQbufferBase::readNewestConditionalCopy ( )

Reads and copies the newest element from the queue into the localElement buffer, but only if has not been previously read.

This method does not block. If the queue is empty no data are copied and false is returned. This method does a lock/copy/unlock on the queue if there is an unread element.

Returns: true if data are copied

Exceptions

std::exception

void carma::util::IPQbufferBase::setNoneAvailable ( )

Sets the number of available (unread) elements to zero (catches up)

void carma::util::IPQbufferBase::trimShmemFilename ( )

protected

Shared memory filenames must contain only one '/' and it must be the first character; this routine fixes up the filename.

void carma::util::IPQbufferBase::write ( )

protected

Put an element into the queue.

This method does a lock/insert/unlock on the queue.

Exceptions

std::exception

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

carma/util/IPQbufferBase.h

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation