Message Queue. More...

#import <AEMessageQueue.h>

Inherits <NSObject>.

Instance Methods
(instancetype)	- init
	Default initializer.

(instancetype)	- initWithMessageBufferLength:
	Initialize with specified message buffer length.

(void)	- startPolling
	Start polling for messages from realtime thread to main thread.

(void)	- stopPolling
	Stop polling for messages from realtime thread to main thread.

(void)	- processMainThreadMessages
	Poll for main thread messages once.

(void)	- performAsynchronousMessageExchangeWithBlock:responseBlock:
	Send a message to the realtime thread asynchronously, optionally receiving a response via a block.

(BOOL)	- performSynchronousMessageExchangeWithBlock:
	Send a message to the realtime thread synchronously.

(void)	- AEMessageQueueSendMessageToMainThread
	Send a message to the main thread asynchronously.

(void)	- beginMessageExchangeBlock
	Begins a block of messages to be performed consecutively.

(void)	- endMessageExchangeBlock
	Ends a consecutive block of messages.

(void)	- AEMessageQueueProcessMessagesOnRealtimeThread
	Process pending messages on realtime thread.

Properties
NSTimeInterval	autoProcessTimeout
	Timeout for when realtime message blocks should be executed automatically.

Detailed Description

Message Queue.

This class manages a two-way message queue which is used to pass messages back and forth between the realtime thread and other threads in your app. This provides for an easy lock-free synchronization method, which is important when working with audio.

AEAudioController contains its own instance of this class, and it's best to simply use that. However, you can create your own instance and use it to perform actions at particular intervals, such as on beat boundaries.

Method Documentation

- (instancetype) init

Default initializer.

- (instancetype) initWithMessageBufferLength: (int32_t) numBytes

Initialize with specified message buffer length.

The true buffer length will be multiples of the device page size (e.g. 4096 bytes)

Parameters

numBytes The message buffer length in bytes.

- (void) startPolling

Start polling for messages from realtime thread to main thread.

Call this after or right before starting the realtime thread that calls AEMessageQueueProcessMessagesOnRealtimeThread periodically. The polling must be active for freeing up message resources, even if you don't explicitly use any responseBlocks or AEMessageQueueSendMessageToMainThread.

- (void) stopPolling

Stop polling for messages from realtime thread to main thread.

- (void) processMainThreadMessages

Poll for main thread messages once.

Use this method to poll the main thread message queue once. This can be useful when performing some synchronous/wait operation that is dependent on a message exchange to complete, similar to running an NSRunLoop manually.

Use startPolling/stopPolling to control message processing the rest of the time.

- (void) performAsynchronousMessageExchangeWithBlock:

Send a message to the realtime thread asynchronously, optionally receiving a response via a block.

This is a synchronization mechanism that allows you to schedule actions to be performed on the realtime thread without any locking mechanism required. Pass in a block, and the block will be performed on the realtime thread at the next call to AEMessageQueueProcessMessagesOnRealtimeThread.

Important: Do not interact with any Objective-C objects inside your block, or hold locks, allocate memory or interact with the BSD subsystem, as all of these may result in audio glitches due to priority inversion.

If provided, the response block will be called on the main thread after the message has been processed on the realtime thread. You may exchange information from the realtime thread to the main thread via a shared data structure (such as a struct, allocated on the heap in advance), or a __block variable.

Parameters

block	A block to be performed on the realtime thread.
responseBlock	A block to be performed on the main thread after the handler has been run, or nil.

- (BOOL) performSynchronousMessageExchangeWithBlock:

Send a message to the realtime thread synchronously.

This is a synchronization mechanism that allows you to schedule actions to be performed on the realtime thread without any locking mechanism required. Pass in a block, and the block will be performed on the realtime thread at the next call to AEMessageQueueProcessMessagesOnRealtimeThread.

Important: Do not interact with any Objective-C objects inside your block, or hold locks, allocate memory or interact with the BSD subsystem, as all of these may result in audio glitches due to priority inversion.

This method will block the current thread until the block has been processed on the realtime thread. You may pass information from the realtime thread to the calling thread via the use of __block variables.

If the block is not processed within a timeout interval, this method will return NO.

Parameters

block A block to be performed on the realtime thread.

Returns: YES if the block could be performed, NO otherwise.

- (void) AEMessageQueueSendMessageToMainThread	(AEMessageQueue *)	messageQueue
	(AEMessageQueueMessageHandler)	handler
	(void *)	userInfo
	(int)	userInfoLength

Send a message to the main thread asynchronously.

This is a synchronization mechanism that allows the realtime thread to schedule actions to be performed on the main thread, without any locking or memory allocation. Pass in a function pointer and optionally a pointer to data to be copied and passed to the handler, and the function will be called on the main thread at the next polling interval.

Tip: To pass a pointer (including pointers to __unsafe_unretained Objective-C objects) through the userInfo parameter, be sure to pass the address to the pointer, using the "&" prefix:

AEMessageQueueSendMessageToMainThread(queue, myMainThreadFunction, &pointer, sizeof(void*));

or

AEMessageQueueSendMessageToMainThread(queue, myMainThreadFunction, &object, sizeof(MyObject*));

You can then retrieve the pointer value via a void** dereference from your function:

void * myPointerValue = *(void**)userInfo;

To access an Objective-C object pointer, you also need to bridge the pointer value:

MyObject *object = (__bridge MyObject*)*(void**)userInfo;

Parameters

messageQueue	The message queue instance.
handler	A pointer to a function to call on the main thread.
userInfo	Pointer to user info data to pass to handler - this will be copied.
userInfoLength	Length of userInfo in bytes.

- (void) beginMessageExchangeBlock

Begins a block of messages to be performed consecutively.

Calling this method will cause message processing on the realtime thread to be suspended until endMessageExchangeBlock is called.

- (void) endMessageExchangeBlock

Ends a consecutive block of messages.

- (void) AEMessageQueueProcessMessagesOnRealtimeThread (__unsafe_unretained AEMessageQueue *) THIS

Process pending messages on realtime thread.

Call this periodically from the realtime thread to process pending message blocks.

Property Documentation

- (NSTimeInterval) autoProcessTimeout

readwritenonatomicassign

Timeout for when realtime message blocks should be executed automatically.

If greater than zero and AEMessageQueueProcessMessagesOnRealtimeThread hasn't been called in this many seconds, process the messages anyway on an internal thread.

Default is zero (disabled).

The documentation for this class was generated from the following file:

AEMessageQueue.h

Instance Methods

Properties

Detailed Description

Method Documentation

Property Documentation