AEArray Class Reference

Real-time safe array. More...

#import <AEArray.h>

Inherits NSObject, and <NSFastEnumeration>.

Instance Methods
(instancetype _Nonnull)	- init
	Default initializer.
(instancetype _Nullable)	- initWithCustomMapping:
	Custom initializer.
(void)	- updateWithContentsOfArray:
	Update the array by copying the contents of the given NSArray.
(void)	- updateWithContentsOfArray:customMapping:
	Update the array, with custom mapping.
(void *_Nullable)	- pointerValueAtIndex:
	Get the pointer value at the given index of the C array, as seen by the audio thread.
(void *_Nullable)	- pointerValueForObject:
	Get the pointer value associated with the given object, if any.
(void)	- updatePointerValue:forObject:
	Update the pointer value associated with the given object.
(id _Nullable)	- objectAtIndexedSubscript:
	Access objects using subscript syntax.
(AEArrayToken _Nonnull)	- AEArrayGetToken
	Get the array token, for use on realtime audio thread.
(int)	- AEArrayGetCount
	Get the number of items in the array.
(void *_Nullable)	- AEArrayGetItem
	Get the item at a given index.

Properties
int	count
	Number of values in array.
NSArray *_Nonnull	allValues
	Current object values.
AEArrayReleaseBlock _Nullable	releaseBlock

Detailed Description

Real-time safe array.

Use this class to manage access to an array of items from the audio thread. Accesses are both thread-safe and realtime-safe.

Using the default initializer results in an instance that manages an array of object references. You can cast the items returned directly to an __unsafe_unretained Objective-C type.

Alternatively, you can use the custom initializer to provide a block that maps between objects and any collection of bytes, such as a C structure.

When accessing the array on the realtime audio thread, you must first obtain a token to access the array using AEArrayGetToken. This token remains valid until the next time AEArrayGetToken is called. Pass the token to AEArrayGetCount and AEArrayGetItem to access array items.

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

Method Documentation

- (instancetype _Nonnull) init

Default initializer.

This configures the instance to manage an array of object references. You can cast the items returned directly to an __unsafe_unretained Objective-C type.

- (instancetype _Nullable) initWithCustomMapping:

(AEArrayCustomMappingBlock _Nullable)

block

Custom initializer.

This allows you to provide a block that maps between the given object and a C structure, or any other collection of bytes. The block will be invoked on the main thread whenever a new item is added to the array during an update. You should allocate the memory you need, set the contents, and return a pointer to this memory. It will be freed automatically once the item is removed from the array, unless you provide a custom releaseBlock.

Parameters

block

The block mapping between objects and stored information, or nil to get the same behaviour as the default initializer.

- (void) updateWithContentsOfArray:

(NSArray *_Nonnull)

array

Update the array by copying the contents of the given NSArray.

New values will be retained, and old values will be released in a thread-safe manner. If you have provided a custom mapping when initializing the instance, the custom mapping block will be called for all new values. Values in the new array that are also present in the prior array value will be maintained, and old values not present in the new array are released.

Using this method within an AEManagedValue performAtomicBatchUpdate block will cause the update to occur atomically along with any other value updates.

Parameters

array

Array of values

- (void) updateWithContentsOfArray:		(NSArray *_Nonnull)	array
customMapping:		(AEArrayIndexedCustomMappingBlock _Nullable)	block

Update the array, with custom mapping.

If you provide a custom mapping using this method, it will be used instead of the one provided when initializing this instance (if any), for all new values not present in the previous array value. This allows you to capture state particular to an individual update at the time of calling this method.

New values will be retained, and old values will be released in a thread-safe manner.

Using this method within an AEManagedValue performAtomicBatchUpdate block will cause the update to occur atomically along with any other value updates.

Parameters

array	Array of values
block	The block mapping between objects and stored information

- (void * _Nullable) pointerValueAtIndex:

(int)

index

Get the pointer value at the given index of the C array, as seen by the audio thread.

This method allows you to access the same values as the audio thread; if you are using a mapping block to create structures that correspond to objects in the original array, for instance, then you may access these structures using this method.

Note: Take care if modifying these values, as they may also be accessed from the audio thread. If you wish to make changes atomically with respect to the audio thread, use updatePointerValue:forObject:.

Parameters

index

Index of the item to retrieve

Returns

Pointer to the item at the given index

- (void * _Nullable) pointerValueForObject:

(id _Nonnull)

object

Get the pointer value associated with the given object, if any.

This method allows you to access the same values as the audio thread; if you are using a mapping block to create structures that correspond to objects in the original array, for instance, then you may access these structures using this method.

Note: Take care if modifying these values, as they may also be accessed from the audio thread. If you wish to make changes atomically with respect to the audio thread, use updatePointerValue:forObject:.

Parameters

object

The object

Returns

Pointer to the item corresponding to the object

- (void) updatePointerValue:		(void *_Nullable)	value
forObject:		(id _Nonnull)	object

Update the pointer value associated with the given object.

If you are using a mapping block to create structures that correspond to objects in the original array, you may use this method to update those structures atomically, with respect to the audio thread.

The prior value associated with this object will be released, possibly calling your releaseBlock, if one is provided.

Parameters

value	The new pointer value
object	The associated object

- (id _Nullable) objectAtIndexedSubscript:

(NSUInteger)

idx

Access objects using subscript syntax.

- (AEArrayToken _Nonnull) AEArrayGetToken

(__unsafe_unretained AEArray *_Nonnull)

array

Get the array token, for use on realtime audio thread.

In order to access this class on the audio thread, you should first use AEArrayGetToken to obtain a token for accessing the object. Then, pass that token to AEArrayGetCount or AEArrayGetItem. The token remains valid until the next time AEArrayGetToken is called, after which the array values may differ. Consequently, it is advised that AEArrayGetToken is called only once per render loop.

Note: Do not use this function on the main thread

Parameters

array

The array

Returns

The token, for use with other accessors

- (int) AEArrayGetCount

(AEArrayToken _Nonnull)

token

Get the number of items in the array.

Parameters

token

The array token, as returned from AEArrayGetToken

Returns

Item count

- (void* _Nullable) AEArrayGetItem		(AEArrayToken _Nonnull)	token
		(int)	index

Get the item at a given index.

Parameters

token	The array token, as returned from AEArrayGetToken
index	The item index

Returns

Item at the given index

Property Documentation

- (int) count

readnonatomicassign

Number of values in array.

- (NSArray* _Nonnull) allValues

readnonatomicstrong

Current object values.

- (AEArrayReleaseBlock _Nullable) releaseBlock

readwritenonatomiccopy

Block to perform when deleting old items, on main thread. If not specified, will simply use free() to dispose bytes, if pointer differs from original Objective-C pointer.

---

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

• AEArray.h