Array Lifecycle

Functions for creating, sharing, and destroying arrays. More...

Functions
DA_DEF da_array	da_new (int element_size)
	Creates a new dynamic array (simple version for general use)
DA_DEF da_array	da_create (int element_size, int initial_capacity, void(*retain_fn)(void *), void(*release_fn)(void *))
	Creates a new dynamic array with full configuration.
DA_DEF void	da_release (da_array *arr)
	Releases a reference to an array, potentially freeing it.
DA_DEF da_array	da_retain (da_array arr)
	Increments reference count for sharing an array.

Detailed Description

Functions for creating, sharing, and destroying arrays.

Function Documentation

da_create()

DA_DEF da_array da_create	(	int	element_size,
		int	initial_capacity,
		void(*)(void *)	retain_fn,
		void(*)(void *)	release_fn
	)

Creates a new dynamic array with full configuration.

Parameters

element_size	Size in bytes of each element (must be > 0)
initial_capacity	Initial capacity (0 is valid for deferred allocation)
retain_fn	Optional retain function called when elements are added (NULL if not needed)
release_fn	Optional release function called when elements are removed (NULL if not needed)

Returns

New array with ref_count = 1

Note

Asserts on allocation failure or invalid parameters

Uses configured growth strategy (DA_GROWTH) for expansions

Atomic reference counting if DA_ATOMIC_REFCOUNT=1

retain_fn is called during da_push(), da_insert(), da_set(), etc.

release_fn is called during da_release(), da_pop(), da_remove(), da_clear(), etc.

// Reference-counted types (like Metal's cell_t)
da_array cells = da_create(sizeof(cell_t), 100, 
                          (void(*)(void*))retain,   // retain on add
                          (void(*)(void*))release); // release on remove

da_new()

DA_DEF da_array da_new

(

int

element_size

)

Creates a new dynamic array (simple version for general use)

Parameters

element_size

Size in bytes of each element (must be > 0)

Returns

New array with ref_count = 1, capacity = 0 (deferred allocation)

Note

Asserts on allocation failure or invalid parameters

Uses configured growth strategy (DA_GROWTH) for expansions

Atomic reference counting if DA_ATOMIC_REFCOUNT=1

No retain/release functions - suitable for simple types

da_array arr = da_new(sizeof(int));
DA_PUSH(arr, 42);
da_release(&arr);

da_release()

DA_DEF void da_release

(

da_array *

arr

)

Releases a reference to an array, potentially freeing it.

Parameters

arr	Pointer to array pointer (will be set to NULL)

Note

Always sets *arr to NULL for safety, regardless of ref count

Only frees memory when ref_count reaches 0

Thread-safe if DA_ATOMIC_REFCOUNT=1

Asserts if arr or *arr is NULL

da_array arr = da_new(sizeof(int), 5, NULL);
da_release(&arr);  // arr becomes NULL, memory freed

da_retain()

DA_DEF da_array da_retain

(

da_array

arr

)

Increments reference count for sharing an array.

Parameters

arr	Array to retain (must not be NULL)

Returns

The same array pointer (for convenience)

Note

Thread-safe if DA_ATOMIC_REFCOUNT=1

Use da_release() to decrement reference count

da_array shared = da_retain(original_array);
pass_to_worker_thread(shared);
da_release(&shared);  // Decrements count, shared becomes NULL