#include <ar_classes.h>

Inheritance diagram for Ar::RunLoop:

Description

Run loop.

Collaboration diagram for Ar::RunLoop:

Public Member Functions
	RunLoop ()
	Default constructor.

	RunLoop (const char *name)
	Constructor to init the runloop. More...

	~RunLoop ()
	Runloop destructor.

ar_status_t	addQueue (ar_queue_t queue, ar_runloop_queue_handler_t callback=NULL, void param=NULL)
	Add a queue to a runloop. More...

ar_status_t	addTimer (ar_timer_t *timer)
	Associate a timer with a runloop. More...

const char *	getName () const
	Get the run loop's name.

ar_status_t	init (const char *name)
	Create a new runloop. More...

ar_status_t	perform (ar_runloop_function_t function, void *param=0)
	Invoke a function on a runloop. More...

ar_status_t	run (uint32_t timeout=kArInfiniteTimeout, ar_runloop_result_t *object=0)
	Run a runloop for a period of time. More...

ar_status_t	signal (uint32_t signal=0)
	Send a signal to a runloop. More...

ar_status_t	stop ()
	Stop a runloop. More...

Static Public Member Functions
static ar_runloop_t *	getCurrent (void)
	Return the current runloop. More...

Additional Inherited Members
Public Attributes inherited from ar_runloop_t
volatile int32_t	m_functionCount
	Number of functions in the queue.

volatile int32_t	m_functionHead
	Function queue head.

struct _ar_runloop::_ar_runloop_function_info	m_functions [AR_RUNLOOP_FUNCTION_QUEUE_SIZE]
	Function queue.

volatile int32_t	m_functionTail
	Function queue tail.

bool	m_isRunning
	Whether the runloop is currently running.

const char *	m_name
	Name of the runloop.

ar_list_t	m_queues
	Queues associated with the runloop.

volatile bool	m_stop
	Flag to force the runloop to stop.

ar_thread_t *	m_thread
	Thread the runloop is running on. NULL when the runloop is not running.

ar_list_t	m_timers
	Timers associated with the runloop.

Constructor & Destructor Documentation

◆ RunLoop()

Ar::RunLoop::RunLoop ( const char * name )

inline

Constructor to init the runloop.

Parameters

The	runloop's name. May be NULL.

Member Function Documentation

◆ addQueue()

ar_status_t Ar::RunLoop::addQueue	(	ar_queue_t *	queue,
		ar_runloop_queue_handler_t	callback = `NULL`,
		void *	param = `NULL`
	)

inline

Add a queue to a runloop.

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

Parameters

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 timer was added to the runloop.
kArAlreadyAttachedError	A queue can only be added to one runloop at a time.
kArInvalidParameterError	The queue parameter was NULL.

◆ addTimer()

ar_status_t Ar::RunLoop::addTimer ( ar_timer_t * timer )

inline

Associate a timer with a runloop.

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

Parameters

timer The timer to associate with the runloop.

Return values

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

◆ getCurrent()

static ar_runloop_t* Ar::RunLoop::getCurrent ( void )

inlinestatic

Return the current runloop.

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

◆ init()

ar_status_t Ar::RunLoop::init ( const char * name )

inline

Create a new runloop.

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

Parameters

name	The name of the runloop. May be NULL.

Return values

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

◆ perform()

ar_status_t Ar::RunLoop::perform	(	ar_runloop_function_t	function,
		void *	param = `0`
	)

inline

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

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 function parameter was NULL.
kArQueueFullError	No room to enqueue the function.

◆ run()

ar_status_t Ar::RunLoop::run	(	uint32_t	timeout = `kArInfiniteTimeout`,
		ar_runloop_result_t *	object = `0`
	)

inline

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

	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.
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.

◆ signal()

ar_status_t Ar::RunLoop::signal ( uint32_t signal = 0 )

inline

Send a signal to a runloop.

This API can be called from any execution context.

Parameters

signal The signal value.

Return values

kArSuccess The signal was sent successfully.

◆ stop()

ar_status_t Ar::RunLoop::stop ( )

inline

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 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.

Return values

kArSuccess The runloop was stopped, or was already stopped.

Description

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

◆ RunLoop()

Member Function Documentation

◆ addQueue()

◆ addTimer()

◆ getCurrent()

◆ init()

◆ perform()

◆ run()

◆ signal()

◆ stop()