Circ v2.1 (Part 1)

int CircOpen (char *allocate, char *keyname, int size)
------------------------------------------------------

Opens a circular buffer for master (size>0) or slave (size=0) process
access. The master process actually creates, initializes and removes the
shared memory and semaphore object used. The slave process just maps to
an already existing circular buffer  
 
 allocate: Can be used to pass a pointer of a preallocated buffer. 
  If allocate=NULL CircOpen() of CircOpenMulti() will do the appropriate
  allocation e.g. creating shared memory or doing a malloc() for threads.

 keyname : Key name to identify the associated shared memory segment
  and semaphores for the inter-process-communication. Actually two files 
  <keyname>._CIRC_SHM and <keyname>._CIRC_SEM are automatically created
  and removed by the master process at CircOpen() and CircClose() time.
           
 size: Total size of the circular buffer in bytes. Only if size>0 the 
  appropriate space is allocated and setup and only the master process
  should do that once. Slave processes should call CircOpen() with 
  size=0 to map to an existing circular.
 
 Returns value:
  >= 0 : circular buffer identifier.
  <  0 : open failed.

int CircOpenMulti (char* allocate, char* keyname, int size, 
		   int cid_amount, int* cid_array)
------------------------------------------------------------

The same as CircOpen() but allows to open and maintain a specified number
of circular buffers using only one piece of shared memory and semaphore.
This is especially useful for parallel tasks like event building. It 
simplifies the management of the circular buffers but for small events 
normal CircOpen() with it's associated semaphore might be faster. 

The first three arguments are the same as for CircOpen(). <cid_amount> 
circular buffers will be opened and the identifiers are returned in 
<cid_array>. If size=0 <cid_amount> is treated as maximum value and 
should be appropriate for the size of array <cid_array>.

Note: <size> is the size to be allocated for ALL circular buffers. 
      CircCloseMulti() must be used for close.

Returns value:
 > 0 : number of circular buffers opened or found.
 < 0 : open failed.

int CircClose (int cid)
-----------------------

Closes the specified multiple circular buffer. 

Note: Only the master of the circular buffer will remove the shared 
      memory and semaphore. 

 cid: circular buffer id returned by CircOpen().

 Return values:
  = 0 if everything was ok.
  < 0 in case of error(s).

int CircCloseMulti (int cid_amount, int* cid_array)
---------------------------------------------------

Closes the specified multiple circular buffer. 

Note: Only the master of the circular buffer will remove shared 
      memory and semaphore. 

 cid_amount and cid_array: number and array of circular buffers
      returned by CircOpenMulti().

 Return values:
  = 0 if everything was ok.
  < 0 in case of error(s).

int CircReset (int cid)
-----------------------

Resets the specified circular buffer. Note: This function (re)initializes 
the circular buffer. It should be handled with care because it destroys
all events currently stored.

 cid: circular buffer id returned by CircOpen() or CircOpenMulti().

 Return values:
  = 0 if everything was ok.
  < 0 in case of error(s).

char* CircGetAddress (int cid)
------------------------------

Returns the base address of the circular buffer associated with 
identifier <cid>. For special purposes only.

 cid: circular buffer id returned by CircOpen() or CircOpenMulti().

 Return values:
  NULL in case of error, otherwise pointer to the circular buffer.

int CircGetContents (int cid)
-----------------------------

Returns the number of events currently in this circular buffer.

 cid: circular buffer id returned by CircOpen() or CircOpenMulti().

 Return values:
  >= 0: events in circular buffer.
  <  0: error.

int CircGetSize (int cid)
-------------------------

Returns the actual size of the circular buffer.

 cid: circular buffer id returned by CircOpen() or CircOpenMulti().

 Return values:
  >  0: size of the circular buffer in bytes.
  <= 0: error.

int CircGetSizeMulti (int cid_amount, int* cid_array)
-----------------------------------------------------

Returns the actual total size of the multiple circular buffer.

 cid_amount, cid_array : number and array of circular buffer ids
                         returned by CircOpenMulti().

 Return values:
  >  0: total size of all circular buffers in bytes.
  <= 0: error.

char* CircReserve (int cid, int number, int size)
-------------------------------------------------

Reserve space for an event in the circular buffer.

 cid   : circular buffer id returned by CircOpen() or CircOpenMulti().
 number: number of this event.
 size  : event size to be reserved.

 Return values:
  pointer to a free block in the circular buffer memory. 
  (char*)-1 if no space is available (buffer full).

int CircValidate (int cid, int number, char *ptr, int size)
-----------------------------------------------------------

Validate event reseved with CircReserve() and release unused space.

 cid   : circular buffer id returned by CircOpen() or CircOpenMulti().
 number: number of this event as already given by CircReserve().
 ptr   : pointer of reserved space returned by CircReserve().
 size  : real size of this event in bytes.

 Return values:
  = 0 if everything was ok
  < 0 in case of error(s)

char* CircLocate (int cid, int *number, int *size)
--------------------------------------------------

Locate the next event in the circular buffer.

 cid   : circular buffer id returned by CircOpen() or CircOpenMulti().
 number: number of this event.
 size  : size in bytes of event found.

 Return values:
  pointer where event was found.
  (char*)-1 if no events available (buffer empty).

int CircRelease (int cid)
-------------------------

Release latest event and free space in circular buffer.

 cid: circular buffer id returned by CircOpen() or CircOpenMulti().

 Return Values: 
   = 0 if everything was ok.  
   < 0 in case of error(s).  

int CircLocateMulti (int mask, int cid_amount, int* cid_array, 
		     char** buffer_array, int* number_array,
		     int* size_array)
---------------------------------------------------------------

Like Circloc() but allows to locate a set of events in a multiple circular
buffer with one semaphore lock operation. <mask> defines the circular 
buffer ids in <cid_arrary> to be tested. For each event located the bit in 
<mask> is cleared and finally returned.   

Note: polling must be done by the user. For example:

      mask = 0xf;
      while ( (mask = CircLocateMulti(mask, 4, ...)) =! 0)
        sleep_a_bit;

 cid_amount, cid_array : number and array of circular buffer ids
                         returned by CircOpenMulti().
 buffer_arrary (output): array of pointers to located event.
 number_arrary (output): array of event numbers found.
 size_arrary   (output): array of event size found.

 Return Values:
  mask of not located buffers. 
  mask=0 means that all locates have been successful.
  (char*)-1 in case of error(s).

int CircReleaseMulti (int mask, int cid_amount, int* cid_array)
---------------------------------------------------------------

Release latest event in the circular buffers defined by a bit set in
<mask>. Useful together with CircLocateMulti().

 cid_amount, cid_array : number and array of circular buffer ids
                         returned by CircOpenMulti().

 Return Values:
  = 0 if everything was ok.
  < 0 in case of error(s).

char* CircLocateAhead (int cid, int *number, int *size)
-------------------------------------------------------

Locate the next not yet located event in the circular buffer. This 
function behaves mainly like CircLocate() but allows to locate events 
in advance for parallel execution.

Note: Events can only be released in sequence. Your code must handle 
      this case correctly! You must call CircReleaseAhead() to release 
      an event.

 cid   : circular buffer id returned by CircOpen().
 number: number of this event.
 size  : size in bytes of this event.

 Return Values:
  pointer where this event was located.
  (char*)-1 if there is no more event available.

int CircReleaseAhead (int cid)
------------------------------

Release latest event located with CircLocateAhead() and free space in 
circular buffer.

 cid: circular buffer id returned by CircOpen().

 Return Values:
  = 0 if everything was ok.
  < 0 in case of error(s).

int CircPut (int cid, int number, char *buf, int size)
------------------------------------------------------

Put an event into the circular buffer. Actually CircReserve(), memcpy()
and CircValidate() are used. Convenient to copy data into the circular
buffer.

 cid   : circular buffer id returned by CircOpen() or CircOpenMulti().
 number: number of this event.
 buf   : pointer to event buffer.
 size  : event lenght.

 Return Values:
  >=0 if everything was ok.
  < 0 in case of error(s).

int CircGet (int cid, int *number, char *buf, int max_len)
----------------------------------------------------------

Get an event from the circular buffer.  CircLocate(), memcpy() and CircRelease()
are used to implement this function. Convenient to copy data out of
the circular buffer.

 cid    : circular buffer id returned by CircOpen() or CircOpenMulti().
 number : number of this event.
 buf    : pointer to event buffer.
 max_len: maximum event lenght.

 Return Values:
  length of event if everything was ok.
  < 0 in case of error(s).

char* CircSearch (int cid, int *number, int *size)
--------------------------------------------------

Locate the next event in the circular buffer newer than the last processed.

 cid   : circular buffer id returned by CircOpen() or CircOpenMulti().
 number: Input/output data
         input = number of the last processed event
         output number of the event found 
 size  : size in bytes of event found.

 Return values:
  pointer where event was found.
  (char*)-1 if no events available (buffer empty).

int CircCopied (int cid,char* eventptr)
---------------------------------------

Release latest event processed by monitoring deamon.

 cid: circular buffer id returned by CircOpen() or CircOpenMulti().
 eventptr is a pointer to the event returned by CircSearch().

 Return Values: 
   = 0 if everything was ok.  
   < 0 in case of error(s).  

Circ.h

The header file for package Circ: Should be included by 
each application using the circular buffer interface!