AEManagedValue Class Reference

Managed value. More...

#import <AEManagedValue.h>

Inherits NSObject.

Instance Methods

(void *_Nullable) - AEManagedValueGetValue
 Get access to the value on the realtime audio thread.
 
(void) - AEManagedValueCommitPendingUpdates
 Commit pending updates on the realtime thread.
 

Class Methods

(void) + performAtomicBatchUpdate:
 Update multiple AEManagedValue instances atomically.
 

Properties

id _Nullable objectValue
 An object.
 
void *_Nullable pointerValue
 A pointer to an allocated memory buffer.
 
AEManagedValueReleaseBlock
_Nullable 
releaseBlock
 Block to perform when deleting old items, on main thread.
 
AEManagedValueReleaseNotificationBlock
_Nullable 
releaseNotificationBlock
 Block for release notifications.
 

Detailed Description

Managed value.

This class manages a mutable reference to a memory buffer or Objective-C object which is both thread-safe and realtime safe. It manages the life-cycle of the buffer/object so that it can not be deallocated while being accessed on the main thread, and does so without locking the realtime thread.

You can use this utility to manage a single module instance, which can be swapped out for another at any time, for instance.

Remember to use the __unsafe_unretained directive to avoid ARC-triggered retains on the audio thread if using this class to manage an Objective-C object, and only interact with such objects via C functions they provide, not via Objective-C methods.

Method Documentation

+ (void) performAtomicBatchUpdate: (AEManagedValueUpdateBlock _Nonnull)  block

Update multiple AEManagedValue instances atomically.

Any changes made within the block will be applied atomically with respect to the audio thread. Any value accesses made from the realtime thread while the block is executing will return the prior value, until the block has completed.

These may be nested safely.

If you are not using AEAudioUnitOutput, then you must call the AEManagedValueCommitPendingUpdates function at the beginning of your main render loop, particularly if you use this method. This ensures batched updates are all committed in sync with your render loop. Until this function is called, AEManagedValueGetValue returns old values, prior to those set in the given block.

Parameters
blockAtomic update block
- (void* _Nullable) AEManagedValueGetValue (__unsafe_unretained AEManagedValue *_Nonnull)  managedValue

Get access to the value on the realtime audio thread.

The object or buffer returned is guaranteed to remain valid until the next call to this function.

Can also be called safely on the main thread (although the objectValue and pointerValue properties are easier).

Parameters
managedValueThe instance
Returns
The value
- (void) AEManagedValueCommitPendingUpdates

Commit pending updates on the realtime thread.

If you are not using AEAudioUnitOutput, then you should call this function at the start of your top-level render loop in order to apply updates in sync. If you are using AEAudioUnitOutput, then this function is already called for you within that class, so you don't need to do so yourself.

After this function is called, any updates made within the block passed to performAtomicBatchUpdate: become available on the render thread, and any old values are scheduled for release on the main thread.

Important: Only call this function on the audio thread. If you call this on the main thread, you will see sporadic crashes on the audio thread.

Property Documentation

- (id _Nullable) objectValue
readwritenonatomicstrong

An object.

You can set this property from the main thread. Note that you can use this property, or pointerValue, but not both.

- (void* _Nullable) pointerValue
readwritenonatomicassign

A pointer to an allocated memory buffer.

Old values will be automatically freed when the value changes. You can set this property from the main thread. Note that you can use this property, or objectValue, but not both.

- (AEManagedValueReleaseBlock _Nullable) releaseBlock
readwritenonatomiccopy

Block to perform when deleting old items, on main thread.

If not specified, will simply use free() to dispose values set via pointerValue, or CFBridgingRelease() to dispose values set via objectValue.

- (AEManagedValueReleaseNotificationBlock _Nullable) releaseNotificationBlock
readwritenonatomiccopy

Block for release notifications.

Use this to be informed when an old value has been released.


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