Run Loops

Collaboration diagram for Run Loops:

Description

Run loop API.

Classes
struct	ar_runloop_t
	Run loop. More...
union	ar_runloop_result_t
	Run loop result. More...
class	Ar::RunLoop
	Run loop. More...

Runloop
ar_status_t	ar_runloop_create (ar_runloop_t *runloop, const char *name)
	Create a new runloop. More...
ar_status_t	ar_runloop_delete (ar_runloop_t *runloop)
	Destroy a runloop. More...
ar_status_t	ar_runloop_run (ar_runloop_t *runloop, uint32_t timeout, ar_runloop_result_t *object)
	Run a runloop for a period of time. More...
ar_status_t	ar_runloop_stop (ar_runloop_t *runloop)
	Stop a runloop. More...
ar_status_t	ar_runloop_perform (ar_runloop_t *runloop, ar_runloop_function_t function, void *param)
	Invoke a function on a runloop. More...
ar_status_t	ar_runloop_signal (ar_runloop_t *runloop, uint32_t signal)
	Send a signal to a runloop. More...
ar_status_t	ar_runloop_add_timer (ar_runloop_t *runloop, ar_timer_t *timer)
	Associate a timer with a runloop. More...
ar_status_t	ar_runloop_add_queue (ar_runloop_t *runloop, ar_queue_t *queue, ar_runloop_queue_handler_t callback, void *param)
	Add a queue to a runloop. More...
ar_runloop_t *	ar_runloop_get_current (void)
	Return the current runloop. More...
const char *	ar_runloop_get_name (ar_runloop_t *runloop)
	Return the runloop's name. More...

---

Class Documentation

ar_runloop_result_t

union ar_runloop_result_t

Class Members
ar_queue_t *	m_queue	Queue that received an item.
uint32_t	m_signal	Value of received signal.

Function Documentation

ar_runloop_add_queue()

ar_status_t ar_runloop_add_queue	(	ar_runloop_t *	runloop,
		ar_queue_t *	queue,
		ar_runloop_queue_handler_t	callback,
		void *	param
	)

Add a queue to a runloop.

If the queue is already associated with another runloop, the kArAlreadyAttachedError error is returned.

Parameters

runloop	Pointer to the runloop.
queue	The queue to associate with the runloop.
callback	Optional callback to handler an item received on the queue. May be NULL.
param	Arbitrary parameter passed to the callback when it is called.

Return values

kArSuccess	The queue was added to the runloop.
kArAlreadyAttachedError	A queue can only be added to one runloop at a time.
kArInvalidParameterError	The runloop or queue parameter was NULL.

ar_runloop_add_timer()

ar_status_t ar_runloop_add_timer	(	ar_runloop_t *	runloop,
		ar_timer_t *	timer
	)

Associate a timer with a runloop.

If the timer is already associated with another runloop, its association will be changed.

Parameters

runloop	Pointer to the runloop.
timer	The timer to associate with the runloop.

Return values

kArSuccess	The timer was added to the runloop.
kArInvalidParameterError	The runloop or timer parameter was NULL.

ar_runloop_create()

ar_status_t ar_runloop_create	(	ar_runloop_t *	runloop,
		const char *	name
	)

Create a new runloop.

A new runloop is not associated with any thread. This association will happen when the runloop is run.

Parameters

runloop	Pointer to storage for the new runloop.
name	The name of the runloop. May be NULL.

Return values

kArSuccess	The runloop was created successfully.
kArInvalidParameterError	The runloop parameter was NULL.
kArNotFromInterruptError	Cannot call this API from interrupt context.

ar_runloop_delete()

ar_status_t ar_runloop_delete

(

ar_runloop_t *

runloop

)

Destroy a runloop.

The runloop must be stopped prior to deleting it.

Parameters

runloop

Pointer to the runloop to delete.

Return values

kArSuccess	The runloop was deleted successfully.
kArInvalidStateError	Cannot delete a runloop while it is running.
kArInvalidParameterError	The runloop parameter was NULL.
kArNotFromInterruptError	Cannot call this API from interrupt context.

ar_runloop_get_current()

ar_runloop_t* ar_runloop_get_current

(

void

)

Return the current runloop.

Returns

The runloop currently running on the active thread. If no runloop is running, then NULL will be returned.

ar_runloop_get_name()

const char* ar_runloop_get_name

(

ar_runloop_t *

runloop

)

Return the runloop's name.

Parameters

runloop

Pointer to the runloop.

Returns

The name of the provided runloop, or NULL if no runloop was passed.

ar_runloop_perform()

ar_status_t ar_runloop_perform	(	ar_runloop_t *	runloop,
		ar_runloop_function_t	function,
		void *	param
	)

Invoke a function on a runloop.

The function will be called in FIFO order the next time the runloop runs. If the runloop is asleep, it will be woken and run immediately.

This API can be called from any execution context.

Parameters

runloop	Pointer to the runloop.
function	The function to invoke on the runloop.
param	Arbitrary parameter passed to the function when it is called.

Return values

kArSuccess	The runloop was stopped, or was already stopped.
kArInvalidParameterError	The runloop or function parameter was NULL.
kArQueueFullError	No room to enqueue the function.

ar_runloop_run()

ar_status_t ar_runloop_run	(	ar_runloop_t *	runloop,
		uint32_t	timeout,
		ar_runloop_result_t *	object
	)

Run a runloop for a period of time.

Starts the runloop running for a specified amount of time. It will sleep the thread until an associated timer or source is pending. If the timeout expires, the API will return. To force the runloop to exit, call ar_runloop_stop().

It's ok to nest runs of the runloop, but only on a single thread.

If a queue is associated with the runloop (via ar_runloop_add_queue()) and the queue receives an item, then the runloop will either invoke the queue handler callback or exit. If it exits, it will return kArRunLoopQueueReceived and the object parameter will be filled in with the queue object that received the item. If object is NULL, then the runloop will still exit but you cannot tell which queue received. This is acceptable if only one queue is associated with the runloop.

Parameters

	runloop	The runloop object.
	timeout	The maximum number of milliseconds to run the runloop. If this value is 0, or kArNoTimeout, then the call will exit after handling pending sources. Setting the timeout to kArInfiniteTimeout will cause the runloop to run until stopped or a queue receives an item.
[out]	object	Optional structure that will be filled in when the return value is kArRunLoopQueueReceived. May be NULL, in which case the receiving queue cannot be indicated.

Return values

kArRunLoopStopped	The runloop exited due to a timeout or explict call to ar_runloop_stop().
kArRunLoopQueueReceived	A queue associated with the runloop received an item.
kArTimeoutError	The runloop timed out.
kArInvalidParameterError	Invalid parameter was provided.
kArRunLoopAlreadyRunningError	The runloop is already running on another thread, or another runloop is already running on the current thread.
kArNotFromInterruptError	Cannot run a runloop from interrupt context.

ar_runloop_signal()

ar_status_t ar_runloop_signal	(	ar_runloop_t *	runloop,
		uint32_t	signal
	)

Send a signal to a runloop.

This API can be called from any execution context.

Parameters

runloop	Pointer to the runloop.
signal	The signal value.

Return values

kArSuccess	The signal was sent successfully.
kArInvalidParameterError	The runloop parameter was NULL.

ar_runloop_stop()

ar_status_t ar_runloop_stop

(

ar_runloop_t *

runloop

)

Stop a runloop.

Use this function to stop a running runloop. It may be called from any execution context, including from within the runloop itself, another thread, or interrupt context. When the runloop stops, it will return kArRunLoopStopped from the ar_runloop_run() API. If multiple runs of the runloop are nested, only the innermost will be stopped. If the runloop is calling out to a perform function or a handler callback, it will only be stopped when the callback returns.

Parameters

runloop

Pointer to the runloop.

Return values

kArSuccess	The runloop was stopped, or was already stopped.
kArInvalidParameterError	The runloop parameter was NULL.