AEMessageQueue Class Reference

Message Queue. More...

#import <AEMessageQueue.h>

Inherits NSObject.

Instance Methods

(instancetype _Nonnull) - init
 Default initializer.
 
(instancetype _Nullable) - initWithBufferCapacity:
 Initializer with custom buffer capacity.
 
(void) - performBlockOnAudioThread:
 Send a message to the realtime thread from the main thread.
 
(void) - performBlockOnAudioThread:completionBlock:
 Send a message to the realtime thread, with a completion block.
 
(BOOL) - AEMessageQueuePerformSelectorOnMainThread
 Perform a selector on the main thread asynchronously.
 
(void) - beginMessageGroup
 Begins a group of messages to be performed consecutively.
 
(void) - endMessageGroup
 Ends a consecutive group of messages.
 
(void) - AEMessageQueuePoll
 Poll for pending messages on realtime thread.
 

Detailed Description

Message Queue.

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

To use it, create an instance and then begin calling AEMessageQueuePoll from your render loop, in order to poll for incoming messages on the render thread.

Then, use AEMessageQueuePerformSelectorOnMainThread from the audio thread, or performBlockOnAudioThread: or performBlockOnAudioThread:completionBlock: from the main thread.

Method Documentation

- (instancetype _Nonnull) init

Default initializer.

- (instancetype _Nullable) initWithBufferCapacity: (size_t)  bufferCapacity

Initializer with custom buffer capacity.

Parameters
bufferCapacityThe buffer capacity, in bytes (default is 8192 bytes). Note that due to the underlying implementation, actual capacity may be larger.
- (void) performBlockOnAudioThread: (AEMessageQueueBlock _Nonnull)  block

Send a message to the realtime thread from the main thread.

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.

Parameters
blockA block to be performed on the realtime thread.
- (void) performBlockOnAudioThread: (AEMessageQueueBlock _Nonnull)  block
completionBlock: (AEMessageQueueBlock _Nullable)  completionBlock 

Send a message to the realtime thread, with a completion block.

If provided, the completion 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.

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.

Parameters
blockA block to be performed on the realtime thread.
completionBlockA block to be performed on the main thread after the handler has been run, or nil.
- (BOOL) AEMessageQueuePerformSelectorOnMainThread (__unsafe_unretained AEMessageQueue *_Nonnull)  messageQueue
(__unsafe_unretained id _Nonnull)  target
(SEL _Nonnull)  selector
(AEArgument arguments
  ... 

Perform a selector on the main thread asynchronously.

This method allows you to cause a method to be called on the main thread. You can provide any number of arguments to the method, as pointers to the argument data.

Parameters
messageQueueThe message queue instance
targetThe target object
selectorThe selector
argumentsList of arguments, terminated by AEArgumentNone
Returns
YES on success, or NO if out of buffer space or not polling
- (void) beginMessageGroup

Begins a group of messages to be performed consecutively.

Messages sent using sendBytes:length: between calls to this method and endMessageGroup will be performed consecutively on the main thread during a single poll interval.

- (void) endMessageGroup

Ends a consecutive group of messages.

- (void) AEMessageQueuePoll (__unsafe_unretained AEMessageQueue *_Nonnull)  THIS

Poll for pending messages on realtime thread.

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


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