Media Queue. More...

#include "openavb_types_pub.h"
#include "openavb_avtp_time_pub.h"

Data Structures
struct	media_q_item_t
	Media Queue Item structure. More...

struct	media_q_t
	Media Queue structure. More...

Functions
media_q_t *	openavbMediaQCreate ()
	Create a media queue. More...

void	openavbMediaQThreadSafeOn (media_q_t *pMediaQ)
	Enable thread safe access for this media queue. More...

bool	openavbMediaQSetSize (media_q_t *pMediaQ, int itemCount, int itemSize)
	Set size of media queue. More...

bool	openavbMediaQAllocItemMapData (media_q_t *pMediaQ, int itemPubMapSize, int itemPvtMapSize)
	Alloc item map data. More...

bool	openavbMediaQAllocItemIntfData (media_q_t *pMediaQ, int itemIntfSize)
	Alloc item interface data. More...

bool	openavbMediaQDelete (media_q_t *pMediaQ)
	Destroy the queue. More...

void	openavbMediaQSetMaxLatency (media_q_t *pMediaQ, U32 maxLatencyUsec)
	Sets the maximum latency expected. More...

void	openavbMediaQSetMaxStaleTail (media_q_t *pMediaQ, U32 maxStaleTailUsec)
	Sets the maximum stale tail. More...

media_q_item_t *	openavbMediaQHeadLock (media_q_t *pMediaQ)
	Get pointer to the head item and lock it. More...

void	openavbMediaQHeadUnlock (media_q_t *pMediaQ)
	Unlock the head item. More...

bool	openavbMediaQHeadPush (media_q_t *pMediaQ)
	Unlock the head item and make it available. More...

media_q_item_t *	openavbMediaQTailLock (media_q_t *pMediaQ, bool ignoreTimestamp)
	Get pointer to the tail item and lock it. More...

void	openavbMediaQTailUnlock (media_q_t *pMediaQ)
	Unlock the tail item without removing it from the queue. More...

bool	openavbMediaQTailPull (media_q_t *pMediaQ)
	Unlock the tail item and remove it from the queue. More...

bool	openavbMediaQTailItemTake (media_q_t pMediaQ, media_q_item_t pItem)
	Take ownership from the MediaQ of an item. More...

bool	openavbMediaQTailItemGive (media_q_t pMediaQ, media_q_item_t pItem)
	Give itme ownership back to the MediaQ. More...

bool	openavbMediaQUsecTillTail (media_q_t pMediaQ, U32 pUsecTill)
	Get microseconds until tail is ready. More...

bool	openavbMediaQIsAvailableBytes (media_q_t *pMediaQ, U32 bytes, bool ignoreTimestamp)
	Check if the number of bytes are available. More...

U32	openavbMediaQCountItems (media_q_t *pMediaQ, bool ignoreTimestamp)
	Count number of available MediaQ items. More...

bool	openavbMediaQAnyReadyItems (media_q_t *pMediaQ, bool ignoreTimestamp)
	Check if there are any ready MediaQ items. More...

Detailed Description

Media Queue.

Circular queue for passing data between interfaces and mappers.

Function Documentation

media_q_t* openavbMediaQCreate ( )

Create a media queue.

Allocate a media queue structure. Only mapping modules will use this call.

Returns: A pointer to a media queue structure. NULL if the creation fails

void openavbMediaQThreadSafeOn ( media_q_t * pMediaQ )

Enable thread safe access for this media queue.

In the default case a media queue is only accessed from a single thread and therefore multi-threaded synchronication isn't needed. In situations where a media queue can be accessed from multiple threads calling this function will enable mutex protection on the head and tail related functions. Once enabled for a media queue it can not be disabled.

Parameters

pMediaQ A pointer to the media_q_t structure

bool openavbMediaQSetSize	(	media_q_t *	pMediaQ,
		int	itemCount,
		int	itemSize
	)

Set size of media queue.

Pre-allocate all the items for the media queue. Once allocated the item storage will be reused as items are added and removed from the queue. Only mapping modules will use this call. This must be called before using the MediaQ.

Parameters

pMediaQ	A pointer to the media_q_t structure
itemCount	Maximum number of items that the queue will hold. These are pre-allocated
itemSize	The pre-allocated size of a media queue item

Returns: TRUE on success or FALSE on failure

Warning: This must be called before using the MediaQ

bool openavbMediaQAllocItemMapData	(	media_q_t *	pMediaQ,
		int	itemPubMapSize,
		int	itemPvtMapSize
	)

Alloc item map data.

Items in the media queue may also have per-item data that is managed by the mapping modules. This function allows mapping modules to specify this storage. Only mapping modules will use this call. This must be called before using the media queue.

Parameters

pMediaQ	A pointer to the media_q_t structure
itemPubMapSize	The size of the public (shared) per-items data that will be allocated. Typically this is the size of a structure that is declared in a public header file associated with the mapping module.
itemPvtMapSize	The size of the private per-items data that will be allocated. The structure of this area will not be shared outside of the mapping module

Returns: TRUE on success or FALSE on failure

Warning: This must be called before using the MediaQ

bool openavbMediaQAllocItemIntfData	(	media_q_t *	pMediaQ,
		int	itemIntfSize
	)

Alloc item interface data.

Items in the media queue may also have per-item data that is managed by the interface modules. This function allows interface modules to specify this storage. This must be called before using the media queue.

Parameters

pMediaQ	A pointer to the media_q_t structure
itemIntfSize	The size of the per-items data to allocate for use by the interface module

Returns: TRUE on success or FALSE on failure

Warning: This must be called before using the MediaQ

bool openavbMediaQDelete ( media_q_t * pMediaQ )

Destroy the queue.

The media queue passed in will be deleted. This includes all allocated memory both for mapping modules and interface modules. Only mapping modules will use this call.

Parameters

pMediaQ A pointer to the media_q_t structure

Returns: TRUE on success or FALSE on failure

void openavbMediaQSetMaxLatency	(	media_q_t *	pMediaQ,
		U32	maxLatencyUsec
	)

Sets the maximum latency expected.

The maximum latency will be set. This value is used by the media queue to help determine if a media queue item is ready to be released to the listener interface module for presentation. Typically the mapping module will call this function with a max latency value derived from the max_latency configuration value.

Parameters

pMediaQ	A pointer to the media_q_t structure
maxLatencyUsec	The maximum latency.

void openavbMediaQSetMaxStaleTail	(	media_q_t *	pMediaQ,
		U32	maxStaleTailUsec
	)

Sets the maximum stale tail.

Used to purge media queue items that are too old.

Parameters

pMediaQ	A pointer to the media_q_t structure
maxStaleTailUsec	tail element purge threshold in microseconds

media_q_item_t* openavbMediaQHeadLock ( media_q_t * pMediaQ )

Get pointer to the head item and lock it.

Get the storage location for the next item that can be added to the circle queue. Once the function is called the item will remained locked until unlocked or pushed. The lock remains valid across callbacks. An interface module will use this function when running as a talker to add a new media element to the queue thereby making it available to the mapping module.

Parameters

pMediaQ A pointer to the media_q_t structure.

Returns: A pointer to a media queue item. Returns NULL if head item storage isn't available.

Examples:: openavb_intf_echo.c.

void openavbMediaQHeadUnlock ( media_q_t * pMediaQ )

Unlock the head item.

Unlock a locked media queue item from the head of the queue. The item will not become available for use in the queue and the data will not be cleared. Subsequent calls to openavbMediaQHeadLock will return the same item storage with the same data values. An interface module will use this function when running as a talker when it must release a previously locked media queue head item.

Parameters

pMediaQ A pointer to the media_q_t structure.

bool openavbMediaQHeadPush ( media_q_t * pMediaQ )

Unlock the head item and make it available.

Unlock a locked media queue item from the head of the queue and make it available for use in the queue to be accessed with the tail function calls. An interface module will use this function when running as a talker after it has locked the head item and added data to the item storage area.

Parameters

pMediaQ A pointer to the media_q_t structure.

Returns: Returns TRUE on success or FALSE on failure.

Examples:: openavb_intf_echo.c.

media_q_item_t* openavbMediaQTailLock	(	media_q_t *	pMediaQ,
		bool	ignoreTimestamp
	)

Get pointer to the tail item and lock it.

Lock the next available tail item in the media queue. Available is based on the timestamp that is associated with the item when it was a placed into the media queue. The interface module running on a listener uses this function to access the data items place into the media queue by the mapping module. At some point after this function call the item must be unlocked with either openavbMediaQTailUnlockor openavbMediaQTailPull on the same callback or a subsequent callback.

Parameters

pMediaQ	A pointer to the media_q_t structure.
ignoreTimestamp	If TRUE ignore the tail item timestamp making the tail item immediately available.

Returns: A pointer to a media queue item. Returns NULL if a tail item isn't available.

Examples:: openavb_intf_echo.c.

void openavbMediaQTailUnlock ( media_q_t * pMediaQ )

Unlock the tail item without removing it from the queue.

Unlock a media queue item that was previously locked with openavbMediaQTailLock. The item will not be removed from the tail of the media queue.

Parameters

pMediaQ A pointer to the media_q_t structure.

bool openavbMediaQTailPull ( media_q_t * pMediaQ )

Unlock the tail item and remove it from the queue.

Unlock a media queue item that was previously locked with openavbMediaQTailLock and remove it from the media queue.

Parameters

pMediaQ A pointer to the media_q_t structure.

Returns: Returns TRUE on success or FALSE on failure.

Examples:: openavb_intf_echo.c.

bool openavbMediaQTailItemTake	(	media_q_t *	pMediaQ,
		media_q_item_t *	pItem
	)

Take ownership from the MediaQ of an item.

Take ownership from the MediaQ of an item previously locked with openavbMediaQTailLock. Will advance the tail. Used in place of openavbMediaQTailPull()

Parameters

pMediaQ	A pointer to the media_q_t structure.
pItem	MediaQ item to take ownership of.

Returns: Returns TRUE on success or FALSE on failure.

bool openavbMediaQTailItemGive	(	media_q_t *	pMediaQ,
		media_q_item_t *	pItem
	)

Give itme ownership back to the MediaQ.

Give ownership back to the MediaQ of an item previously taken with openavbMediaQTailItemTake()

Parameters

pMediaQ	A pointer to the media_q_t structure.
pItem	MediaQ item to give back tot he MediaA.

Returns: Returns TRUE on success or FALSE on failure.

bool openavbMediaQUsecTillTail	(	media_q_t *	pMediaQ,
		U32 *	pUsecTill
	)

Get microseconds until tail is ready.

Parameters

pMediaQ	A pointer to the media_q_t structure.
pUsecTill	An output parameter that is set with the number of microseconds until the tail item will be available.

Returns: Return FALSE if greater than 5 seconds otherwise TRUE.

bool openavbMediaQIsAvailableBytes	(	media_q_t *	pMediaQ,
		U32	bytes,
		bool	ignoreTimestamp
	)

Check if the number of bytes are available.

Checks were the given media queue contains bytes, returns true if it does false otherwise.

Parameters

pMediaQ	A pointer to the media_q_t structure.
bytes	Number of bytes expected in media queue
ignoreTimestamp	Ignore timestamp for byte accumulation.

Returns: TRUE if bytes are available in pMediaQ; FALSE if bytes not available in pMediaQ.

U32 openavbMediaQCountItems	(	media_q_t *	pMediaQ,
		bool	ignoreTimestamp
	)

Count number of available MediaQ items.

Count the number of available MediaQ items.

Parameters

pMediaQ	A pointer to the media_q_t structure.
ignoreTimestamp	Ignore timestamp for byte accumulation.

Returns: The number of available MediaA items.

bool openavbMediaQAnyReadyItems	(	media_q_t *	pMediaQ,
		bool	ignoreTimestamp
	)

Check if there are any ready MediaQ items.

Parameters

pMediaQ	A pointer to the media_q_t structure.
ignoreTimestamp	Ignore timestamp for checking

Returns: TRUE if there is at least 1 MediaQ item available otherwise FALSE.

Data Structures

Functions

Detailed Description

Function Documentation