#include "brttutil.h" Pmtfifo * pmtfifo_create (int maxqueue, int block, int check) int pmtfifo_set_timeout (Pmtfifo *mtf, double timeout) int pmtfifo_destroy (Pmtfifo *mtf, void (*free_value) (void *ptr)) int pmtfifo_flush (Pmtfifo *mtf, void (*free_value) (void *ptr)) int pmtfifo_push (Pmtfifo *mtf, void *ptr) int pmtfifo_pop (Pmtfifo *mtf, void **ptr) int pmtfifo_unpop (Pmtfifo *mtf, void *ptr) int pmtfifo_data_available (Pmtfifo *mtf) int pmtfifo_release_block (Pmtfifo *mtf) int pmtfifo_release_blocks (Pmtfifo *mtf)
These define an MT-safe interface to a FIFO queue of pointers. This particular version is implemented using the standard POSIX versions of mutexes and condition variables. Any number of threads may push and/or pop pointers to/from the FIFO. A "push" puts a pointer into the head of the FIFO and a "pop" removes a pointer from the tail of the FIFO. Note that management of memory associated with any of the pointers must be done by the application program.
pmtfifo_create will create a Pmtfifo object and return a pointer to the object, or NULL if there is an error. maxqueue controls the blocking behavior of pushes and is the maximum allowed size of the FIFO queue before blocking occurs on the push. If maxqueue is set to 0, then the FIFO will grow indefinitely and pushes will never block. block controls the blocking behavior of pops and if set, then will cause pops to block when the FIFO is empty until the FIFO is non-empty. If check is set, then the Pmtfifo pointer is stored in an associative array and is checked for validity each time a push or pop is executed.
pmtfifo_set_timeout will set the FIFO blocking characteristic and also set a blocking-with-timeout condition. The timeout argument is a timeout value in seconds for a blocking pmtfifo_pop. If timeout is less than zero, then the FIFO is set to block indefinitely, just like specifying block as 1 in pmtfifo_create. If timeout is equal to zero, then the FIFO is set to be non-blocking, just like specifying block as 0 in pmtfifo_create.
pmtfifo_destroy will free all resources associated with a Pmtfifo and return 0, or -1 if an error occurs. free_value is a pointer to a function that will be called for each pointer in the FIFO with a single argument of the pointer for use to free any resources associated with the pointers, or NULL to ignore the pointers.
pmtfifo_flush will temporarily suspend all FIFO writing and reading, flush the contents of the FIFO and resume FIFO writing and reading and return 0, or -1 if an error occurs. free_value is a pointer to a function that will be called for each pointer in the FIFO with a single argument of the pointer for use to free any resources associated with the pointers, or NULL to ignore the pointers.
pmtfifo_push will push a new pointer onto the head of the FIFO and return 0, or -1 if an error occurs.
pmtfifo_pop will pop the oldest pointer from the tail of the FIFO, returning it in *ptr. Note that *ptr is set to NULL for all of the conditions where no data is returned. Return codes for pmtfifo_pop are as follows.
pmtfifo_unpop will push a previously popped pointer back onto the tail of the FIFO. This behaves like pmtfifo_push, except that the pointer is appended to the tail of the FIFO so that it will be the next pointer to be popped.
pmtfifo_data_available is always non-blocking and returns the number of pointers in the queue, if data is available to be popped, 0 if the FIFO is empty, or -1 if an error occurs.
pmtfifo_release_block will release any existing blocked pmtfifo_pop calls. The released pmtfifo_pop call will return PMTFIFO_RELEASED.
pmtfifo_release_blocks will release any existing blocked pmtfifo_pop calls, as well as turn the FIFO into a non-blocking FIFO for all subsequent pmtfifo_pop calls. The released pmtfifo_pop call will return PMTFIFO_RELEASED. However, all subsequent pmtfifo_pop calls will return PMTFIFO_NODATA or PMTFIFO_OK, the normal behavior for non-blocking FIFOs.