/* 
 * memory.h
 *
 * Memory management.
 *
 */

#import <stdlib.h>

typedef void (*dealloc_function)(void *);

// Allocates a block of memory.  Returns a pointer to the beginning of the block.
void *alloc(size_t s);

// Does the same thing as alloc(), but will call the function referenced by a non-NULL d when the block is deallocated.
void *alloc_with_dealloc(size_t s, dealloc_function d);

// Deallocates a block of memory.  Usually you use release() instead, in case there are more references to the memory.
void dealloc(void *mem);


// Allocates an array which can be accessed using normal C array syntax.  Arguments are the size of a value and the number of initial values.
void *alloc_array(size_t cell_size, unsigned int initial_count);

// Returns the number of values store in an array.
unsigned int array_count(void *array);

// Makes an array smaller or larger.  This may or may not reallocate the array.  Returns the new pointer (which may or may not be the same as the old pointer).
void *resize_array(void *array, unsigned int new_count);


// Returns the number of references to mem.
unsigned int retain_count(void *mem);

// Increments the retain count of a block of memory by one.  Returns mem.
void *retain(void *mem);

// Decrements the retain count of a block of memory by one.  If the retain count is zero or less, it calls dealloc() on mem.
void release(void *mem);


// Adds a new autorelease pool to the autorelease stack.  Always match a push_autorelease() call with a pop_autorelease() call.
void push_autorelease();

// Removes the top autorelease pool from the stack and releases its associated objects.
void pop_autorelease();

// Adds mem to the current autorelease pool.  When pop_autorelease() is called, the retain count of the memory area will be decremented.
void *autorelease(void *mem);