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

#include <carma/util/IPQfileWriter.h>

Inheritance diagram for carma::util::IPQfileWriter< E >:

Public Member Functions
	IPQfileWriter (const ::std::string &filenameString, bool isCreator=false, int nElements=0, unsigned int testOffset=0)
	Constructor for a writer of a memory mapped file. More...

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

Public Member Functions inherited from carma::util::IPQbufferBase
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...

Additional Inherited Members
Protected Member Functions inherited from carma::util::IPQfileBuffer
	IPQfileBuffer (void *localElement, int elementSize, const ::std::string &filename, bool isCreator=false, int nElements=0, unsigned int testOffset=0)
	Constructor for persistent queue. More...

Protected Member Functions inherited from carma::util::IPQbufferBase
::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...

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 inherited from carma::util::IPQbufferBase
bool	debug_

int	fileDescriptor_

const int	openMask_

const int	protectionMask_

Detailed Description

template<class E>
class carma::util::IPQfileWriter< E >

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).

A templatized class (or structure) is intimately associated with the queue. All writes are done from the local copy, and all reads go into it. Note that all methods of the input class become part of the methods of of the IPQ class, effectively adding the queue methods to the class. The queue storage is simple, with fixed memory allocation, so the input class should have no pointers - just memory. Hierarchies are allowed, as long as it is done with composition and not pointers. Methods have no effect on the queue storage (it may be dangerous to use pointers to the internal data because it is going to get moved around).

***** DANGER ***** ** Any class that is virtual (polymorphic = has a vtable = overrides ** a virtual function) will screw up in subtle ways because ** the pointer to the writer's vtable will get copied into ** the reader's object -> not what you want!

The queues have independent read and write pointers. The write pointers are an intrinsic part of each queue, but the read pointers are unique to each instance of a reader. The read pointer is initialized in the constructor to point to the oldest data in the queue. A writer is also a reader.

The constructors can throw exceptions - make sure that you catch them!

Example of use:

Class X {
public:
    double getA() { return A; }
    int    getB() { return B; }
    char   getC() { return C; }
    void   setB(int b) { B=b; }
private:
    char   C;
    double A;
    int    B;
};

// Make a queue that can contain 100 X's
try {
   IPQfileWriter<X> Xwriter("a.ipq", 100);
} catch (const Error & e) { cout<<e; exit(); }
Xwriter.setB(123);  // Mess with X object
Xwriter.write();    // Write current X into queue
Xwriter.setB(456);
Xwriter.write();    // Write again
Xwriter.read()      // Read the first X from queue (into internal X)
cout<<Xwriter.getB()<<endl;  // Will print '123'

Definition at line 81 of file IPQfileWriter.h.

Constructor & Destructor Documentation

template<class E >

carma::util::IPQfileWriter< E >::IPQfileWriter	(	const ::std::string &	filenameString,
		bool	isCreator = `false`,
		int	nElements = `0`,
		unsigned int	testOffset = `0`
	)

Constructor for a writer of a memory mapped file.

If one already exists that matches the call, then it is used. But if the existing file is not big enough, the file will be removed and recreated. The file is persistent. Note that an IPQfilewriter is also a reader and has all of the methods of a reader.

Parameters

filenameString	Memory mapped filename
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.
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

See Also: IPQbuffer

Definition at line 122 of file IPQfileWriter.h.

Member Function Documentation

template<class E >

void carma::util::IPQfileWriter< E >::write ( )

Put an element into the queue.

This method does a lock/insert/unlock on the queue. Moves up from protected in IPQfileBuffer to full public here.

Definition at line 140 of file IPQfileWriter.h.

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

carma/util/IPQfileWriter.h

Public Member Functions

Additional Inherited Members

Detailed Description

template<class E> class carma::util::IPQfileWriter< E >

Constructor & Destructor Documentation

Member Function Documentation

template<class E>
class carma::util::IPQfileWriter< E >