Object responsible for coordinating the execution of media processing flow graphs. More...

#include <MpMediaTask.h>

Inheritance diagram for MpMediaTask:

Collaboration diagram for MpMediaTask:

Public Types
enum	{ DEF_TIME_LIMIT_USECS = 6000, DEF_SEM_WAIT_MSECS = 500, MEDIA_TASK_PRIORITY = 0 }

Protected Member Functions
	MpMediaTask (int maxFlowGraph, UtlBoolean enableLocalAudio)
	Default constructor. More...

Private Member Functions
int	run (void *pArg)

UtlBoolean	handleMessage (OsMsg &rMsg)
	Handle an incoming message. More...

UtlBoolean	handleManage (MpFlowGraphBase *pFlowGraph)
	Handles the MANAGE message. More...

UtlBoolean	handleSetFocus (MpFlowGraphBase *pFlowGraph)
	Handles the SET_FOCUS message. More...

UtlBoolean	handleStart (MpFlowGraphBase *pFlowGraph)
	Handles the START message. More...

UtlBoolean	handleStop (MpFlowGraphBase *pFlowGraph)
	Handles the STOP message. More...

UtlBoolean	handleUnmanage (MpFlowGraphBase *pFlowGraph)
	Handles the UNMANAGE message. More...

UtlBoolean	handleWaitForSignal (MpMediaTaskMsg *)
	Handles the WAIT_FOR_SIGNAL message. More...

	MpMediaTask (const MpMediaTask &rMpMediaTask)
	Copy constructor (not implemented for this task) More...

MpMediaTask &	operator= (const MpMediaTask &rhs)
	Assignment operator (not implemented for this task) More...

Static Private Member Functions
static void	flowgraphTickerCallback (const intptr_t userData, const intptr_t eventData)
	Callback for flowgraph ticker. More...

Private Attributes
OsMutex	mMutex
	lock for synchronization More...

UtlBoolean	mDebugEnabled
	TRUE if debug mode is enabled, FALSE otherwise. More...

int	mTimeLimitCnt
	Number of frames where time limit was exceeded. More...

unsigned	mProcessedCnt
	Number of frames that have been processed. More...

int	mManagedCnt
	Number of flow graphs presently managed. More...

int	mStartedCnt
	Number of flow graphs presently started. More...

OsTime	mSemTimeout
	Timeout value for acquiring the start semaphore. More...

int	mSemTimeoutCnt
	Number of times the mSemTimeOut was exceeded. More...

UtlBoolean	mWaitForSignal
	If TRUE, then don't handle any incoming msgs until a FrameStart signal has been received. More...

MpFlowGraphBase *	mpFocus
	FlowGraph that has the focus (may be NULL) More...

MpFlowGraphBase **	mManagedFGs
	The set of flow graphs presently managed. More...

int	mLimitUsecs
	Frame processing time limit (in usecs) More...

int	mHandleMsgErrs
	Number of message handling problems during the last frame processing interval. More...

OsMsgPool *	mpBufferMsgPool
	Pool of reusable buffer messages. More...

OsMsgPool *	mpSignalMsgPool
	Pool of reusable frame signal messages. More...

OsCallback	mFlowgraphTicker
	OsNotification to call flowgraphTickerCallback() More...

UtlBoolean	mIsLocalAudioEnabled
	Affects setFocus(). More...

Static Private Attributes
static int	mMaxFlowGraph = 0

static const OsTime	smOperationQueueTimeout = OsTime::OS_INFINITY
	to the flowgraph queue. More...

static UtlBoolean	mIsBlockingReported = FALSE
	for too long already reported? More...

static MpMediaTask *volatile	spInstance = NULL
	pointer to the single instance More...

static OsBSem	sLock
	semaphore used to ensure that there is only one instance of this class More...

Creators
static MpMediaTask *	createMediaTask (int maxFlowGraph, UtlBoolean enableLocalAudio=true)
	Create the media processing task. More...

static MpMediaTask *	getMediaTask ()
	Return a pointer to the media processing task if exists. More...

virtual	~MpMediaTask ()
	Destructor. More...

Manipulators
static OsStatus	signalFrameStart (const OsTime &timeout=OsTime::OS_INFINITY)
	Signal the media processing task that it should begin processing the next frame. More...

OsStatus	manageFlowGraph (MpFlowGraphBase &rFlowGraph)
	Directs the media processing task to add the flow graph to its set of managed flow graphs. More...

OsStatus	unmanageFlowGraph (MpFlowGraphBase &rFlowGraph)
	Directs the media processing task to remove the flow graph from its set of managed flow graphs. More...

OsStatus	setDebug (UtlBoolean enableFlag)
	When "debug" mode is enabled, the "time limit" checking is disabled and the wait for "frame start" timeout is set to "INFINITY". More...

OsStatus	setFocus (MpFlowGraphBase *pFlowGraph)
	Changes the focus to the indicated flow graph. More...

OsStatus	setTimeLimit (int usecs)
	Sets the amount of time (in microseconds) allotted to the media processing task for processing a frame's worth of media. More...

OsStatus	setWaitTimeout (int msecs)
	Sets the maximum time (in milliseconds) that the media processing task will wait for a "frame start" signal. More...

OsStatus	startFlowGraph (MpFlowGraphBase &rFlowGraph)
	Directs the media processing task to start the specified flow graph. More...

OsStatus	stopFlowGraph (MpFlowGraphBase &rFlowGraph)
	Directs the media processing task to stop the specified flow graph. More...

OsStatus	sendToAllFlowgraphs (OsMsgQ &queuedMessages)
	Queue the given messages to each of the managed flowgraphs. More...

Accessors
static MpFlowGraphBase *	mediaInfo (void)
	Displays information on the console about the media processing task. More...

static int	maxNumManagedFlowGraphs (void)
	Returns the maximum number of flow graphs that can be managed by the media processing task. More...

int	numHandledMsgErrs ()
	Debug aid for tracking state. See MpMediaTaskTest. More...

UtlBoolean	getDebugMode (void) const
	Returns TRUE if debug mode is enabled, FALSE otherwise. More...

MpFlowGraphBase *	getFocus (void) const
	Returns the flow graph that currently has focus (access to the audio apparatus) or NULL if there is no flow graph with focus. More...

int	getLimitExceededCnt (void) const
	Returns the number of times that the frame processing time limit has been exceeded. More...

OsStatus	getManagedFlowGraphs (MpFlowGraphBase *flowGraphs[], const int size, int &numItems)
	Returns an array of MpFlowGraphBase pointers that are presently managed by the media processing task. More...

int	getTimeLimit (void) const
	Returns the amount of time (in microseconds) allotted to the media processing task for processing a frame's worth of media. More...

int	getWaitTimeout (void) const
	Returns the maximum time (in milliseconds) that the media processing task will wait for the "frame start" signal. More...

int	getWaitTimeoutCnt (void) const
	Returns the number of times that the wait timeout associated with "frame start" signal has been exceeded. More...

int	numManagedFlowGraphs (void) const
	Returns the number of flow graphs currently being managed by the media processing task. More...

int	numProcessedFrames (void) const
	Returns the number of frames that the media processing task has processed. This count is maintained as an unsigned, 32-bit value. More...

int	numStartedFlowGraphs (void) const
	Returns the number of flow graphs that have been started by the media processing task. More...

OsMsgPool *	getBufferMsgPool (void) const
	Returns pointer to pool of reusable buffer messages. More...

OsNotification *	getTickerNotification ()
	Get OsNotification to signal for the next frame processing interval start. More...

Inquiry
UtlBoolean	isManagedFlowGraph (MpFlowGraphBase *pFlowGraph)
	Is flow graph managed by the media processing task? More...

void	getQueueUsage (int &numMsgs, int &softLimit, int &hardLimit)
	Return usage information on the Media Task's message queue. More...

Detailed Description

Object responsible for coordinating the execution of media processing flow graphs.

Key Concepts

Flow graphs are created outside of this class and are initially in the STOPPED state. Once a flow graph has been created and while it is still in the stopped state, the media processing task is informed of the new flow graph via the manageFlowGraph() method.

A flow graph must be in the STARTED state before it will process media streams. The startFlowGraph() and stopFlowGraph() methods are used to start and stop flow graphs, respectively.

The unmanageFlowGraph() method informs the media processing task that it should no longer execute the indicated flow graph. If the flow graph is not in the STOPPED state, the media processing task stops the flow graph before unmanaging it.

Changes to the flow graphs startFlowGraph(), stopFlowGraph(), manageFlowGraph(), unmanageFlowGraph() and setFocus() all take effect at frame processing boundaries.

The media processing task expects to receive a notification every frame interval indicating that it is time to process the next frame's worth of media. This signal is conveyed by calling the static signalFrameStart() method.

Locking

For the most part, this class relies on the atomicity of reads and writes to appropriately aligned 32-bit data to avoid the need for locks. However, a single-writer/multiple-reader lock is used to protect the data structure that maintains the set of flow graphs currently being managed by the media processing task. The media processing task takes the write lock while modifying the data structure. The getManagedFlowGraphs() method acquires the read lock as part of getting the array of flow graphs.

Messaging

Several of the methods in this class post MpMediaTask messages to the media processing task. These messages are processed at the beginning of the next frame processing interval. The methods that cause messages to be sent are: manageFlowGraph(), unmanageFlowGraph(), startFlowGraph(), stopFlowGraph() and setFocus().

At the beginning of the frame processing interval, the media processing task sends itself a WAIT_FOR_SIGNAL message. When the task receives that message, it knows that it is time to finish the frame processing for the current interval and then wait for the "start" signal for the next frame before processing any more messages.

Member Enumeration Documentation

anonymous enum

Enumerator
DEF_TIME_LIMIT_USECS	processing limit = 6 msecs
DEF_SEM_WAIT_MSECS	semaphore timeout = 0.5 secs
MEDIA_TASK_PRIORITY	media task execution priority

Constructor & Destructor Documentation

~MpMediaTask ( )

virtual

Destructor.

MpMediaTask	(	int	maxFlowGraph,
		UtlBoolean	enableLocalAudio
	)

protected

Default constructor.

MpMediaTask ( const MpMediaTask & rMpMediaTask )

private

Copy constructor (not implemented for this task)

Member Function Documentation

MpMediaTask * createMediaTask	(	int	maxFlowGraph,
		UtlBoolean	enableLocalAudio = `true`
	)

static

Create the media processing task.

MpMediaTask * getMediaTask ( )

static

Return a pointer to the media processing task if exists.

OsStatus manageFlowGraph ( MpFlowGraphBase & rFlowGraph )

Directs the media processing task to add the flow graph to its set of managed flow graphs.

The flow graph must be in the STOPPED state when this method is invoked.

Returns: OS_SUCCESS - the flow graph will be added at the start of the next frame processing interval.; OS_INVALID_ARGUMENT - flow graph is not in the STOPPED state

OsStatus unmanageFlowGraph ( MpFlowGraphBase & rFlowGraph )

Directs the media processing task to remove the flow graph from its set of managed flow graphs.

If the flow graph is not already in the STOPPED state, then the flow graph will be stopped before it is removed from the set of managed flow graphs.

Returns: OS_SUCCESS - indicates that the media task will stop managing the indicated flow graph

OsStatus setDebug ( UtlBoolean enableFlag )

When "debug" mode is enabled, the "time limit" checking is disabled and the wait for "frame start" timeout is set to "INFINITY".

For now, this method always returns OS_SUCCESS.

OsStatus setFocus ( MpFlowGraphBase * pFlowGraph )

Changes the focus to the indicated flow graph.

At most one flow graph at a time can have focus. Only the flow graph that has focus is allowed to access the audio resources (speaker and microphone) of the phone. The affected flow graphs will be modified to reflect the change of focus at the beginning of the next frame interval. For now, this method always returns OS_SUCCESS.

OsStatus setTimeLimit ( int usecs )

Sets the amount of time (in microseconds) allotted to the media processing task for processing a frame's worth of media.

If this time limit is exceeded, the media processing task increments an internal statistic. The value of this statistic can be retrieved by calling the getLimitExceededCnt() method. For now, this method always returns OS_SUCCESS.

OsStatus setWaitTimeout ( int msecs )

Sets the maximum time (in milliseconds) that the media processing task will wait for a "frame start" signal.

A value of -1 indicates that the task should wait "forever".

The new timeout will take effect at the beginning of the next frame interval. For now, this method always returns OS_SUCCESS.

OsStatus startFlowGraph ( MpFlowGraphBase & rFlowGraph )

Directs the media processing task to start the specified flow graph.

A flow graph must be started in order for it to process the media stream.

The flow graph state change will take effect at the beginning of the next frame interval. For now, this method always returns OS_SUCCESS.

OsStatus stopFlowGraph ( MpFlowGraphBase & rFlowGraph )

Directs the media processing task to stop the specified flow graph.

When a flow graph is stopped it no longer processes the media stream.

The flow graph state change will take effect at the beginning of the next frame interval. For now, this method always returns OS_SUCCESS.

OsStatus signalFrameStart ( const OsTime & timeout = OsTime::OS_INFINITY )

static

Signal the media processing task that it should begin processing the next frame.

See also: getTickerNotification() for an alternative method of signaling frame start.

OsStatus sendToAllFlowgraphs ( OsMsgQ & queuedMessages )

Queue the given messages to each of the managed flowgraphs.

Parameters

queuedMessagees - message queue containing one or more messages that are to be queued to all of the managed flowgraphs

int numHandledMsgErrs ( )

Debug aid for tracking state. See MpMediaTaskTest.

UtlBoolean getDebugMode ( void ) const

Returns TRUE if debug mode is enabled, FALSE otherwise.

MpFlowGraphBase * getFocus ( void ) const

Returns the flow graph that currently has focus (access to the audio apparatus) or NULL if there is no flow graph with focus.

int getLimitExceededCnt ( void ) const

Returns the number of times that the frame processing time limit has been exceeded.

OsStatus getManagedFlowGraphs	(	MpFlowGraphBase *	flowGraphs[],
		const int	size,
		int &	numItems
	)

Returns an array of MpFlowGraphBase pointers that are presently managed by the media processing task.

The caller is responsible for allocating the flowGraphs array containing room for size pointers. The number of items actually filled in is passed back via the nItems argument.

int getTimeLimit ( void ) const

Returns the amount of time (in microseconds) allotted to the media processing task for processing a frame's worth of media.

int getWaitTimeout ( void ) const

Returns the maximum time (in milliseconds) that the media processing task will wait for the "frame start" signal.

A value of -1 indicates that the task will wait "forever".

int getWaitTimeoutCnt ( void ) const

Returns the number of times that the wait timeout associated with "frame start" signal has been exceeded.

int numManagedFlowGraphs ( void ) const

Returns the number of flow graphs currently being managed by the media processing task.

int numProcessedFrames ( void ) const

Returns the number of frames that the media processing task has processed. This count is maintained as an unsigned, 32-bit value.

Note: If the frame period is 10 msecs, then it will take 2^32 / (100 * 3600 * 24 * 365) = 1.36 years before this count wraps.

int numStartedFlowGraphs ( void ) const

Returns the number of flow graphs that have been started by the media processing task.

This value should always be <= the number of managed flow graphs.

OsMsgPool * getBufferMsgPool ( void ) const

Returns pointer to pool of reusable buffer messages.

OsNotification * getTickerNotification ( )

inline

Get OsNotification to signal for the next frame processing interval start.

Returned notification is owned by MediaTask and should not be freed by a caller.

See also: signalFrameStart() for an alternative method of signaling frame start.

MpFlowGraphBase * mediaInfo ( void )

static

Displays information on the console about the media processing task.

int maxNumManagedFlowGraphs ( void )

static

Returns the maximum number of flow graphs that can be managed by the media processing task.

UtlBoolean isManagedFlowGraph ( MpFlowGraphBase * pFlowGraph )

Is flow graph managed by the media processing task?

Returns: TRUE - if the indicated flow graph is presently being managed by the media processing task,; FALSE - otherwise.

void getQueueUsage	(	int &	numMsgs,
		int &	softLimit,
		int &	hardLimit
	)

Return usage information on the Media Task's message queue.

int run ( void * pArg )

private

UtlBoolean handleMessage ( OsMsg & rMsg )

private

Handle an incoming message.

Returns: TRUE - if the message was handled,; FALSE - otherwise.

UtlBoolean handleManage ( MpFlowGraphBase * pFlowGraph )

private

Handles the MANAGE message.

Returns: TRUE - if the message was handled,; FALSE - otherwise.

UtlBoolean handleSetFocus ( MpFlowGraphBase * pFlowGraph )

private

Handles the SET_FOCUS message.

Returns: TRUE - if the message was handled,; FALSE - otherwise.

UtlBoolean handleStart ( MpFlowGraphBase * pFlowGraph )

private

Handles the START message.

Returns: TRUE - if the message was handled,; FALSE - otherwise.

UtlBoolean handleStop ( MpFlowGraphBase * pFlowGraph )

private

Handles the STOP message.

Returns: TRUE - if the message was handled,; FALSE - otherwise.

UtlBoolean handleUnmanage ( MpFlowGraphBase * pFlowGraph )

private

Handles the UNMANAGE message.

Returns: TRUE - if the message was handled,; FALSE - otherwise.

UtlBoolean handleWaitForSignal ( MpMediaTaskMsg * pMsg )

private

Handles the WAIT_FOR_SIGNAL message.

Returns: TRUE - if the message was handled,; FALSE - otherwise.

void flowgraphTickerCallback	(	const intptr_t	userData,
		const intptr_t	eventData
	)

staticprivate

Callback for flowgraph ticker.

Parameters

[in]	userData	- contains 0 for now.
[in]	eventData	- contains 0 for now.

MpMediaTask& operator= ( const MpMediaTask & rhs )

private

Assignment operator (not implemented for this task)

Member Data Documentation

OsMutex mMutex

private

lock for synchronization

UtlBoolean mDebugEnabled

private

TRUE if debug mode is enabled, FALSE otherwise.

int mTimeLimitCnt

private

Number of frames where time limit was exceeded.

unsigned mProcessedCnt

private

Number of frames that have been processed.

int mManagedCnt

private

Number of flow graphs presently managed.

int mStartedCnt

private

Number of flow graphs presently started.

OsTime mSemTimeout

private

Timeout value for acquiring the start semaphore.

int mSemTimeoutCnt

private

Number of times the mSemTimeOut was exceeded.

UtlBoolean mWaitForSignal

private

If TRUE, then don't handle any incoming msgs until a FrameStart signal has been received.

MpFlowGraphBase* mpFocus

private

FlowGraph that has the focus (may be NULL)

MpFlowGraphBase** mManagedFGs

private

The set of flow graphs presently managed.

int mMaxFlowGraph = 0

staticprivate

int mLimitUsecs

private

Frame processing time limit (in usecs)

int mHandleMsgErrs

private

Number of message handling problems during the last frame processing interval.

OsMsgPool* mpBufferMsgPool

private

Pool of reusable buffer messages.

OsMsgPool* mpSignalMsgPool

private

Pool of reusable frame signal messages.

const OsTime smOperationQueueTimeout = OsTime::OS_INFINITY

staticprivate

to the flowgraph queue.

Timeout for posting messages

OsCallback mFlowgraphTicker

private

OsNotification to call flowgraphTickerCallback()

UtlBoolean mIsLocalAudioEnabled

private

Affects setFocus().

UtlBoolean mIsBlockingReported = FALSE

staticprivate

for too long already reported?

Is message about MediaTask being blocked

MpMediaTask *volatile spInstance = NULL

staticprivate

pointer to the single instance

of the MpMediaTask class

OsBSem sLock

staticprivate

semaphore used to ensure that there is only one instance of this class

Public Types

Protected Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Creators

Manipulators

Accessors

Inquiry

Detailed Description

Key Concepts

Locking

Messaging

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation