VxWorks Reference Manual : Libraries
rngLib - ring buffer subroutine library
rngCreate( ) - create an empty ring buffer
rngDelete( ) - delete a ring buffer
rngFlush( ) - make a ring buffer empty
rngBufGet( ) - get characters from a ring buffer
rngBufPut( ) - put bytes into a ring buffer
rngIsEmpty( ) - test if a ring buffer is empty
rngIsFull( ) - test if a ring buffer is full (no more room)
rngFreeBytes( ) - determine the number of free bytes in a ring buffer
rngNBytes( ) - determine the number of bytes in a ring buffer
rngPutAhead( ) - put a byte ahead in a ring buffer without moving ring pointers
rngMoveAhead( ) - advance a ring pointer by n bytes
This library provides routines for creating and using ring buffers, which are first-in-first-out circular buffers. The routines simply manipulate the ring buffer data structure; no kernel functions are invoked. In particular, ring buffers by themselves provide no task synchronization or mutual exclusion.
However, the ring buffer pointers are manipulated in such a way that a reader task (invoking rngBufGet( )) and a writer task (invoking rngBufPut( )) can access a ring simultaneously without requiring mutual exclusion. This is because readers only affect a read pointer and writers only affect a write pointer in a ring buffer data structure. However, access by multiple readers or writers must be interlocked through a mutual exclusion mechanism (i.e., a mutual-exclusion semaphore guarding a ring buffer).
This library also supplies two macros, RNG_ELEM_PUT and RNG_ELEM_GET, for putting and getting single bytes from a ring buffer. They are defined in rngLib.h.
int RNG_ELEM_GET (ringId, pch, fromP) int RNG_ELEM_PUT (ringId, ch, toP)Both macros require a temporary variable fromP or toP, which should be declared as register int for maximum efficiency. RNG_ELEM_GET returns 1 if there was a character available in the buffer; it returns 0 otherwise. RNG_ELEM_PUT returns 1 if there was room in the buffer; it returns 0 otherwise. These are somewhat faster than rngBufPut( ) and rngBufGet( ), which can put and get multi-byte buffers.
rngLib.h
rngCreate( ) - create an empty ring buffer
RING_ID rngCreate ( int nbytes /* number of bytes in ring buffer */ )
This routine creates a ring buffer of size nbytes, and initializes it. Memory for the buffer is allocated from the system memory partition.
The ID of the ring buffer, or NULL if memory cannot be allocated.
rngDelete( ) - delete a ring buffer
void rngDelete ( RING_ID ringId /* ring buffer to delete */ )
This routine deletes a specified ring buffer. Any data currently in the buffer will be lost.
N/A
rngFlush( ) - make a ring buffer empty
void rngFlush ( RING_ID ringId /* ring buffer to initialize */ )
This routine initializes a specified ring buffer to be empty. Any data currently in the buffer will be lost.
N/A
rngBufGet( ) - get characters from a ring buffer
int rngBufGet ( RING_ID rngId, /* ring buffer to get data from */ char * buffer, /* pointer to buffer to receive data */ int maxbytes /* maximum number of bytes to get */ )
This routine copies bytes from the ring buffer rngId into buffer. It copies as many bytes as are available in the ring, up to maxbytes. The bytes copied will be removed from the ring.
The number of bytes actually received from the ring buffer; it may be zero if the ring buffer is empty at the time of the call.
rngBufPut( ) - put bytes into a ring buffer
int rngBufPut ( RING_ID rngId, /* ring buffer to put data into */ char * buffer, /* buffer to get data from */ int nbytes /* number of bytes to try to put */ )
This routine puts bytes from buffer into ring buffer ringId. The specified number of bytes will be put into the ring, up to the number of bytes available in the ring.
The number of bytes actually put into the ring buffer; it may be less than number requested, even zero, if there is insufficient room in the ring buffer at the time of the call.
rngIsEmpty( ) - test if a ring buffer is empty
BOOL rngIsEmpty ( RING_ID ringId /* ring buffer to test */ )
This routine determines if a specified ring buffer is empty.
TRUE if empty, FALSE if not.
rngIsFull( ) - test if a ring buffer is full (no more room)
BOOL rngIsFull ( RING_ID ringId /* ring buffer to test */ )
This routine determines if a specified ring buffer is completely full.
TRUE if full, FALSE if not.
rngFreeBytes( ) - determine the number of free bytes in a ring buffer
int rngFreeBytes ( RING_ID ringId /* ring buffer to examine */ )
This routine determines the number of bytes currently unused in a specified ring buffer.
The number of unused bytes in the ring buffer.
rngNBytes( ) - determine the number of bytes in a ring buffer
int rngNBytes ( RING_ID ringId /* ring buffer to be enumerated */ )
This routine determines the number of bytes currently in a specified ring buffer.
The number of bytes filled in the ring buffer.
rngPutAhead( ) - put a byte ahead in a ring buffer without moving ring pointers
void rngPutAhead ( RING_ID ringId, /* ring buffer to put byte in */ char byte, /* byte to be put in ring */ int offset /* offset beyond next input byte where to put byte */ )
This routine writes a byte into the ring, but does not move the ring buffer pointers. Thus the byte will not yet be available to rngBufGet( ) calls. The byte is written offset bytes ahead of the next input location in the ring. Thus, an offset of 0 puts the byte in the same position as would RNG_ELEM_PUT would put a byte, except that the input pointer is not updated.
Bytes written ahead in the ring buffer with this routine can be made available all at once by subsequently moving the ring buffer pointers with the routine rngMoveAhead( ).
Before calling rngPutAhead( ), the caller must verify that at least offset + 1 bytes are available in the ring buffer.
N/A
rngMoveAhead( ) - advance a ring pointer by n bytes
void rngMoveAhead ( RING_ID ringId, /* ring buffer to be advanced */ int n /* number of bytes ahead to move input pointer */ )
This routine advances the ring buffer input pointer by n bytes. This makes n bytes available in the ring buffer, after having been written ahead in the ring buffer with rngPutAhead( ).
N/A