Base FIFO implementation that allows arbitrary element sizes and arbitrary element storage. More...

Files
file	fifo-constants.h
	Provides constants for the abstract FIFO implementation (guac_fifo).

file	fifo-types.h
	Provides type definitions for the abstract FIFO implementation (guac_fifo).

file	fifo.h
	Provides an abstract FIFO implementation (guac_fifo), which can support arbitrary element sizes and storage.

Data Structures
struct	guac_fifo
	Generic base structure for a FIFO of arbitrary events. More...

Macros
#define	GUAC_FIFO_STATE_READY 1
	The bitwise flag used by the "state" member of guac_fifo to represent that the fifo has space for at least one item.

#define	GUAC_FIFO_STATE_NONEMPTY 2
	The bitwise flag used by the "state" member of guac_fifo to represent that the fifo contains at least one item.

#define	GUAC_FIFO_STATE_INVALID 4
	The bitwise flag used by the "state" member of guac_fifo to represent that the fifo is no longer valid and may not be used for any further operations.

Functions
void	guac_fifo_init (guac_fifo fifo, void items, size_t max_items, size_t item_size)
	Initializes the given guac_fifo such that it may be safely included in shared memory and accessed by multiple processes.

void	guac_fifo_destroy (guac_fifo *fifo)
	Releases all underlying resources used by the given guac_fifo, such as pthread mutexes and conditions.

void	guac_fifo_invalidate (guac_fifo *fifo)
	Marks the given FIFO as invalid, preventing any further additions or removals from the FIFO.

int	guac_fifo_is_valid (guac_fifo *fifo)
	Returns whether the given FIFO is still valid.

void	guac_fifo_lock (guac_fifo *fifo)
	Acquires exclusive access to this guac_fifo.

void	guac_fifo_unlock (guac_fifo *fifo)
	Relinquishes exclusive access to this guac_fifo.

int	guac_fifo_enqueue (guac_fifo fifo, const void item)
	Adds a copy of the given item to the end of the given FIFO, and signals any waiting threads that the FIFO is now non-empty.

int	guac_fifo_enqueue_and_lock (guac_fifo fifo, const void item)
	Atomically adds a copy of the given item to the end of the given FIFO, signals any waiting threads that the FIFO is now non-empty, and leaves the given FIFO locked.

int	guac_fifo_dequeue (guac_fifo fifo, void item)
	Removes the oldest (first) item from the FIFO, storing a copy of that item within the provided buffer.

int	guac_fifo_dequeue_and_lock (guac_fifo fifo, void item)
	Atomically removes the oldest (first) item from the FIFO, storing a copy of that item within the provided buffer.

int	guac_fifo_timed_dequeue (guac_fifo fifo, void item, int msec_timeout)
	Removes the oldest (first) item from the FIFO, storing a copy of that item within the provided buffer.

int	guac_fifo_timed_dequeue_and_lock (guac_fifo fifo, void item, int msec_timeout)
	Atomically removes the oldest (first) item from the FIFO, storing a copy of that item within the provided buffer.

Detailed Description

Base FIFO implementation that allows arbitrary element sizes and arbitrary element storage.

Function Documentation

◆ guac_fifo_dequeue()

int guac_fifo_dequeue	(	guac_fifo *	fifo,
		void *	item )

Removes the oldest (first) item from the FIFO, storing a copy of that item within the provided buffer.

If the FIFO is currently empty, this function will block until at least one item has been added to the FIFO or until the FIFO becomes invalid.

Parameters

fifo	The FIFO to remove an item from.
item	The buffer that should receive a copy of the removed item.

Returns: Non-zero if an item was successfully removed, zero if items cannot be removed from the FIFO because the FIFO has been invalidated.

◆ guac_fifo_dequeue_and_lock()

int guac_fifo_dequeue_and_lock	(	guac_fifo *	fifo,
		void *	item )

Atomically removes the oldest (first) item from the FIFO, storing a copy of that item within the provided buffer.

If this function successfully removes an item, the FIFO is left locked after this function returns. If the FIFO is currently empty, this function will block until at least one item has been added to the FIFO or until the FIFO becomes invalid.

Parameters

fifo	The FIFO to remove an item from.
item	The buffer that should receive a copy of the removed item.

Returns: Non-zero if an item was successfully removed, zero if items cannot be removed from the FIFO because the FIFO has been invalidated.

◆ guac_fifo_destroy()

void guac_fifo_destroy ( guac_fifo * fifo )

Releases all underlying resources used by the given guac_fifo, such as pthread mutexes and conditions.

The given guac_fifo MAY NOT be used after this function has been called. This function MAY NOT be called while exclusive access to the underlying state flag is held by any thread.

This function does NOT free() the given guac_fifo pointer. If the memory associated with the given guac_fifo has been manually allocated, it must be manually freed as necessary.

Parameters

fifo	The FIFO to destroy.

◆ guac_fifo_enqueue()

int guac_fifo_enqueue	(	guac_fifo *	fifo,
		const void *	item )

Adds a copy of the given item to the end of the given FIFO, and signals any waiting threads that the FIFO is now non-empty.

If there is insufficient space in the FIFO, this function will block until at space is available. If the FIFO is invalid or becomes invalid, this function returns immediately.

Parameters

fifo	The FIFO to add an item to.
item	The item to add.

Returns: Non-zero if the item was successfully added, zero if items cannot be added to the FIFO because the FIFO has been invalidated.

◆ guac_fifo_enqueue_and_lock()

int guac_fifo_enqueue_and_lock	(	guac_fifo *	fifo,
		const void *	item )

Atomically adds a copy of the given item to the end of the given FIFO, signals any waiting threads that the FIFO is now non-empty, and leaves the given FIFO locked.

If there is insufficient space in the FIFO, this function will block until at space is available. If the FIFO is invalid or becomes invalid, this function returns immediately and the FIFO is not locked.

Parameters

fifo	The FIFO to add an item to.
item	The item to add.

Returns: Non-zero if the item was successfully added, zero if items cannot be added to the FIFO because the FIFO has been invalidated.

◆ guac_fifo_init()

void guac_fifo_init	(	guac_fifo *	fifo,
		void *	items,
		size_t	max_items,
		size_t	item_size )

Initializes the given guac_fifo such that it may be safely included in shared memory and accessed by multiple processes.

This function MUST be invoked once (and ONLY once) for each guac_fifo being used, and MUST be invoked before any such FIFO is used.

The FIFO is empty upon initialization.

Parameters

fifo	The FIFO to initialize.
items	The storage that the base implementation should use for queued items. This storage MUST be large enough to contain the maximum number of items as a contiguous array.
max_items	The maximum number of items supported by the provided storage.
item_size	The number of bytes required for each individual item in storage.

◆ guac_fifo_invalidate()

void guac_fifo_invalidate ( guac_fifo * fifo )

Marks the given FIFO as invalid, preventing any further additions or removals from the FIFO.

Attempts to add/remove items from the FIFO from this point forward will fail immediately, as will any outstanding attempts to remove items that are currently blocked.

This function is primarily necessary to allow for threadsafe cleanup of queues. Lacking this function, there is no guarantee that an outstanding call to guac_fifo_dequeue() won't still be indefinitely blocking. Internally, such a condition would mean that the mutex of the state flag is still held, which would mean that the FIFO can never be safely destroyed.

Parameters

fifo	The FIFO to invalidate.

◆ guac_fifo_is_valid()

int guac_fifo_is_valid ( guac_fifo * fifo )

Returns whether the given FIFO is still valid.

A FIFO is valid if it has not yet been invalidated through a call to guac_fifo_invalidate().

Parameters

fifo	The FIFO to test.

Returns: Non-zero if the given FIFO is still valid, zero otherwise.

◆ guac_fifo_lock()

void guac_fifo_lock ( guac_fifo * fifo )

Acquires exclusive access to this guac_fifo.

When exclusive access is no longer required, it must be manually relinquished through a call to guac_fifo_unlock(). This function may be safely called while the current thread already has exclusive access, however every such call must eventually have a matching call to guac_fifo_unlock().

NOTE: It is intended that locking/unlocking a guac_fifo may be used in lieu of a mutex to guard concurrent access to any number of shared resources related to the FIFO.

Parameters

fifo	The guac_fifo to lock.

◆ guac_fifo_timed_dequeue()

int guac_fifo_timed_dequeue	(	guac_fifo *	fifo,
		void *	item,
		int	msec_timeout )

Removes the oldest (first) item from the FIFO, storing a copy of that item within the provided buffer.

If the FIFO is currently empty, this function will block until at least one item has been added to the FIFO, until the given timeout has elapsed, or until the FIFO becomes invalid.

Parameters

fifo	The FIFO to remove an item from.
item	The buffer that should receive a copy of the removed item.
msec_timeout	The maximum number of milliseconds to wait for at least one item to be present within the FIFO (or for the FIFO to become invalid).

Returns: Non-zero if an item was successfully removed, zero if the timeout has elapsed or if items cannot be removed from the FIFO because the FIFO has been invalidated.

◆ guac_fifo_timed_dequeue_and_lock()

int guac_fifo_timed_dequeue_and_lock	(	guac_fifo *	fifo,
		void *	item,
		int	msec_timeout )

Atomically removes the oldest (first) item from the FIFO, storing a copy of that item within the provided buffer.

If this function successfully removes an item, the FIFO is left locked after this function returns. If the FIFO is currently empty, this function will block until at least one item has been added to the FIFO, until the given timeout has elapsed, or until the FIFO becomes invalid.

Parameters

fifo	The FIFO to remove an item from.
item	The buffer that should receive a copy of the removed item.
msec_timeout	The maximum number of milliseconds to wait for at least one item to be present within the FIFO (or for the FIFO to become invalid).

Returns: Non-zero if an item was successfully removed, zero if the timeout has elapsed or if items cannot be removed from the FIFO because the FIFO has been invalidated.

◆ guac_fifo_unlock()

void guac_fifo_unlock ( guac_fifo * fifo )

Relinquishes exclusive access to this guac_fifo.

This function may only be called by a thread that currently has exclusive access to the guac_fifo.

NOTE: It is intended that locking/unlocking a guac_fifo may be used in lieu of a mutex to guard concurrent access to any number of shared resources related to the FIFO.

Parameters

fifo	The guac_fifo to unlock.

Files

Data Structures

Macros

Functions

Detailed Description

Function Documentation

◆ guac_fifo_dequeue()

◆ guac_fifo_dequeue_and_lock()

◆ guac_fifo_destroy()

◆ guac_fifo_enqueue()

◆ guac_fifo_enqueue_and_lock()

◆ guac_fifo_init()

◆ guac_fifo_invalidate()

◆ guac_fifo_is_valid()

◆ guac_fifo_lock()

◆ guac_fifo_timed_dequeue()

◆ guac_fifo_timed_dequeue_and_lock()

◆ guac_fifo_unlock()