et_fifo.c File Reference

#include "et_fifo.h"
#include "et_private.h"

Functions
int	et_fifo_openProducer (et_sys_id id, et_fifo_id *fid, const int *bufIds, int idCount)
int	et_fifo_openConsumer (et_sys_id id, et_fifo_id *fid)
void	et_fifo_close (et_fifo_id fid)
	Routine to close the fifo handle opened with et_fifo_openProducer or et_fifo_openConsumer. More...
et_fifo_entry *	et_fifo_entryCreate (et_fifo_id fid)
	Routine to allocate a structure holding a fifo entry (array of ET events) associated with the given fifo id. More...
void	et_fifo_freeEntry (et_fifo_entry *entry)
	Routine to free a fifo entry created with et_fifo_entryCreate. More...
int	et_fifo_newEntry (et_fifo_id fid, et_fifo_entry *entry)
	This routine is called when a user wants an array of related, empty buffers from the ET system into which data can be placed. More...
int	et_fifo_newEntryTO (et_fifo_id fid, et_fifo_entry *entry, struct timespec *deltatime)
	This routine is called when a user wants an array of related, empty buffers from the ET system into which data can be placed. More...
int	et_fifo_getEntry (et_fifo_id fid, et_fifo_entry *entry)
	This routine is called when a user wants an array of related, data-filled buffers from the ET system. More...
int	et_fifo_getEntryTO (et_fifo_id fid, et_fifo_entry *entry, struct timespec *deltatime)
	This routine is called when a user wants an array of related, data-filled buffers from the ET system. More...
int	et_fifo_putEntry (et_fifo_entry *entry)
	This routine is called when a user wants to place an array of related, data-filled buffers (single FIFO entry) back into the ET system. More...
et_event **	et_fifo_getBufs (et_fifo_entry *entry)
	This routine gives access to the ET events or buffers in a fifo entry obtained by calling either et_fifo_getEntry, et_fifo_getEntryTO, et_fifo_newEntry, or et_fifo_newEntryTO. More...
int	et_fifo_getEntryCount (et_fifo_id id)
	This routine gets the max number of fifo entries possibly available to consumer. More...
int	et_fifo_getFillLevel (et_fifo_id id)
size_t	et_fifo_getBufSize (et_fifo_id id)
	This routine gets the max size of each buffer in bytes. More...
int	et_fifo_getEntryCapacity (et_fifo_id id)
	This routine gets the max number of buffers in each FIFO entry. More...
int	et_fifo_getIdCount (et_fifo_id id)
	This routine gets the number of buffers assigned an id in each FIFO entry. More...
int	et_fifo_getBufIds (et_fifo_id id, int *bufIds)
	This routine gets the array of ids assigned to buffers in each FIFO entry. More...
void	et_fifo_setId (et_event *ev, int id)
	This routine sets an id value associated with this ET event/buffer. More...
int	et_fifo_getId (et_event *ev)
	This routine gets an id value associated with this ET event/buffer. More...
void	et_fifo_setHasData (et_event *ev, int hasData)
	This routine sets whether this ET event has data in it. More...
int	et_fifo_hasData (et_event *ev)
	This routine gets whether this ET event has data in it or not. More...
int	et_fifo_allHaveData (et_fifo_id id, et_fifo_entry *entry, int *incompleteBufs, size_t *incompleteBytes)
	This routine gets whether all events (associated with an id) in the given ET fifo entry have data in it or not. More...
et_event *	et_fifo_getBuf (int id, et_fifo_entry *entry)
	Find the event/buffer in the fifo entry corresponding to the given id. More...

Detailed Description

These routines use an ET system as a FIFO. The idea is that an ET system divides its events (or buffers) into groups (or arrays) of fixed size. Each array is then a single FIFO entry. Thus the FIFO's entries are each an array of related buffers.

When requesting an entry, this interface does so in arrays of this fixed size. Likewise, when putting them back it does so only in the same arrays. In order to use this interface, the ET system should be run using the et_start_fifo program and not et_start. This sets up the ET to be comprised of properly grouped events. It also creates one station, called "Users" to which the consumers of FIFO entries will attach.

This interface is intended to be used by connecting to a local ET system using shared memory - providing a fast, wide FIFO available to multiple local processes. Although it could be used by remote users of the ET system, it's advantages would be lost.

These routines are threadsafe with the exception of et_fifo_getBuf, but that should never be called on the same arg with different threads. These routines are designed to work as follows:

• et_open to open ET system and get id
• et_fifo_openProducer or et_fifo_openConsumer to get fifo id as either a producer or consumer of entries
  • Makes sure ET is setup properly
  • Attaches to GrandCentral station if producing entries
  • Attaches to Users station if consuming entries
• et_fifo_newEntry to get pointer to et_fifo_entry if producing fifo entry
• et_fifo_newEntryTO to get pointer to et_fifo_entry if producing fifo entry
• et_fifo_getEntry to get pointer to et_fifo_entry if consuming fifo entry
• et_fifo_getEntryTO to get pointer to et_fifo_entry if consuming fifo entry
• et_fifo_putEntry when finished with fifo entry
• et_fifo_close when finished with fifo interface
• et_close when finished with ET system
• For operations on a fifo entry:
  • et_fifo_getBufs to get access to all the events of a single fifo entry
  • et_fifo_getBuf to get access to a single event of a single fifo entry
• For operations on fifo in general:
  • et_fifo_getEntryCapacity to get the number of events in array. Need only be done once.
  • et_fifo_getBufSize to get available size of each event. Need only be done once.
  • et_fifo_getIdCount to get the number of buffers assigned an id in each entry.
  • et_fifo_getBufIds to get the array of ids assigned to buffers in each entry.
  • et_fifo_getEntryCount to get the total number of entries existing in the fifo available to consumer.
  • et_fifo_getFillLevel to get the number of fifo entries containing unconsumed data, which is the fill level of the fifo.
• For operations on a specific event/buffer in an entry:
  • et_fifo_getId to get an id for a particular event
  • et_fifo_setId to set an id for a particular event
  • et_fifo_setHasData to set whether this event has data in it or not.
  • et_fifo_hasData to get whether this ET event has data in it or not.
  • et_event_getlength to get the size of valid data for a particular event

The first integer of an event's control array is reserved to hold an id to distinguish it from the other events. It's initially set to -1. Note that once you call et_fifo_getBufs and get pointers to the events, you have full access to the control array of each event by calling et_event_getcontrol and et_event_setcontrol and are not restricted to using et_fifo_getId and et_fifo_setId which only access the first integer of the control array. The control array is of size ET_STATION_SELECT_INTS.