Circ v5 (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).

int CircResetStatistics (int cid)
---------------------------------

Resets the specified circular buffer statistics. 
Does not modify the content of the 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 CircSetDead (int cid)
-------------------------

Set the specified buffer in the dead condition.
After this operation, Reserve and Validate commands are forbidden.

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

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

Set the specified multiple buffer in the dead condition.
After this operation, Reserve and Validate commands are forbidden.

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

int CircIsAlive (int cid)
-------------------------

Tells if the master have clossed the connection.

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

 Return values:
  true (>0) if new events can arrive
  false (0) else 

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 readable events currently in this circular buffer.

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

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

int CircGetOccupancy (int cid)
------------------------------

Returns the memory currently allocated in this circular buffer.

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

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

int CircGetStatistics (int cid, TCircStatistics *stat)
------------------------------------------------------

Returns the current statistics.

 cid: circular buffer id returned by CircOpen() or CircOpenMulti().
 stat: will be filled with the statistics

 Return values:
  == 0: no error
  <  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 CircValidateParam (int cid, int number, char *ptr, int size, int setready)
----------------------------------------------------------------------

Conditionaly validate event reseved with CircReserve() and release unused space.

WARNING: Do not mix CircValidate and CircCondValidate calls!
         From the first call to CircCondValidate up to the call to
         CircCondConfirm or CircCondRemove, no CircValidate are allowed!

 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.
 setready : if true(!=0), the event can be read from the circular buffer
              (same as CircValidate)
            else, the event will be ready for reading after a call to CircCondConfirm
              (same as CircCondValidate)

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

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)

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

Conditionaly validate event reseved with CircReserve() and release unused space.
The event will be ready to be read after a call to CircCondConfirm.

WARNING: Do not mix CircValidate and CircCondValidate calls!
         From the first call to CircCondValidate up to the call to
         CircCondConfirm or CircCondRemove, no CircValidate are allowed!

 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)

int CircCondConfirm(int cid)
----------------------------

All the conditionaly validated events are finaly validated,
i.e. they can be read out from the 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 CircCondRemove(int cid)
---------------------------

All the conditionaly validated events are removed from the circular buffer.
All the events must be validated to do this operation!

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

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