In the past, Max has provided two separate APIs for memory management. More...

Defines
#define	MM_UNIFIED
	This macro being defined means that getbytes and sysmem APIs for memory management are unified.
Functions
char *	getbytes (t_getbytes_size size)
	Allocate small amounts of non-relocatable memory.
void	freebytes (void *b, t_getbytes_size size)
	Free memory allocated with getbytes().
char *	getbytes16 (t_getbytes_size size)
	Use getbytes16() to allocate small amounts of non-relocatable memory that is aligned on a 16-byte boundary for use with vector optimization.
void	freebytes16 (char *mem, t_getbytes_size size)
	Free memory allocated with getbytes16().
char **	newhandle (long size)
	Allocate relocatable memory.
short	growhandle (void *h, long size)
	Change the size of a handle.
void	disposhandle (char **h)
	Free the memory used by a handle you no longer need.
BEGIN_USING_C_LINKAGE t_ptr	sysmem_newptr (long size)
	Allocate memory.
t_ptr	sysmem_newptrclear (long size)
	Allocate memory and set it to zero.
t_ptr	sysmem_resizeptr (void *ptr, long newsize)
	Resize an existing pointer.
t_ptr	sysmem_resizeptrclear (void *ptr, long newsize)
	Resize an existing pointer and clear it.
long	sysmem_ptrsize (void *ptr)
	Find the size of a pointer.
void	sysmem_freeptr (void *ptr)
	Free memory allocated with sysmem_newptr().
void	sysmem_copyptr (const void src, void dst, long bytes)
	Copy memory the contents of one pointer to another pointer.
t_handle	sysmem_newhandle (long size)
	Allocate a handle (a pointer to a pointer).
t_handle	sysmem_newhandleclear (unsigned long size)
	Allocate a handle (a pointer to a pointer) whose memory is set to zero.
long	sysmem_resizehandle (t_handle handle, long newsize)
	Resize an existing handle.
long	sysmem_handlesize (t_handle handle)
	Find the size of a handle.
void	sysmem_freehandle (t_handle handle)
	Free memory allocated with sysmem_newhandle().
long	sysmem_lockhandle (t_handle handle, long lock)
	Set the locked/unlocked state of a handle.
long	sysmem_ptrandhand (void *p, t_handle h, long size)
	Add memory to an existing handle and copy memory to the resized portion from a pointer.
long	sysmem_ptrbeforehand (void *p, t_handle h, unsigned long size)
	Add memory to an existing handle and copy memory to the resized portion from a pointer.
long	sysmem_nullterminatehandle (t_handle h)
	Add a null terminator to a handle.

Detailed Description

In the past, Max has provided two separate APIs for memory management.

One for allocating memory on the stack so that it was interrupt safe, including the getbytes() and freebytes() functions. The other, the "sysmem" API, were for allocating memory on the heap where larger amounts of memory were needed and the code could be guaranteed to operate at non-interrupt level.

Many things have changed in the environment of recent operating systems (MacOS X and Windows XP/Vista), the memory routines function differently, and the scheduler is no longer directly triggered by a hardware interrupt. In Max 5, the sysmem and getbytes API's have been unified, and thus may be used interchangeably.

The memory management unification can be switched on and off in the header files if needed, to compile code for older versions of Max for example, by changing the use of MM_UNIFIED in the Max headers.

Sysmem API

The Sysmem API provides a number of utilities for allocating and managing memory. It is relatively similar to some of the Macintosh Memory Manager API, and not too different from Standard C library memory functions. It is not safe to mix these routines with other memory routines (e.g. don’t use malloc() to allocate a pointer, and sysmem_freeptr() to free it).

Define Documentation

#define MM_UNIFIED

This macro being defined means that getbytes and sysmem APIs for memory management are unified.

This is correct for Max 5, but should be commented out when compiling for old max targets.

Function Documentation

void disposhandle ( char ** h )

Free the memory used by a handle you no longer need.

Parameters:

h	The handle to dispose.

See also:: sysmem_freehandle()

void freebytes	(	void *	b,
		t_getbytes_size	size
	)

Free memory allocated with getbytes().

As of Max 5 it is unified with sysmem_newptr(), which is the preferred method for allocating memory.

Parameters:

b	A pointer to the block of memory previously allocated that you want to free.
size	The size the block specified (as parameter b) in bytes.

void freebytes16	(	char *	mem,
		t_getbytes_size	size
	)

Free memory allocated with getbytes16().

As of Max 5 it is unified with sysmem_newptr(), which is the preferred method for allocating memory.

Parameters:

mem	A pointer to the block of memory previously allocated that you want to free.
size	The size the block specified (as parameter b) in bytes.

Remarks:: Note that freebytes16() will cause memory corruption if you pass it memory that was allocated with getbytes(). Use it only with memory allocated with getbytes16().

char* getbytes ( t_getbytes_size size )

Allocate small amounts of non-relocatable memory.

As of Max 5 it is unified with sysmem_newptr(), which is the preferred method for allocating memory.

Parameters:

size	The size to allocate in bytes (up to 32767 bytes).

Returns:: A pointer to the allocated memory.

char* getbytes16 ( t_getbytes_size size )

Use getbytes16() to allocate small amounts of non-relocatable memory that is aligned on a 16-byte boundary for use with vector optimization.

Parameters:

size	The size to allocate in bytes (up to 32767 bytes).

Returns:: A pointer to the allocated memory.

Remarks:: getbytes16() is identical to getbytes except that it returns memory that is aligned to a 16-byte boundary. This allows you to allocate storage for vector-optimized memory at interrupt level. Note that any memory allocated with getbytes16() must be freed with freebytes16(), not freebytes().

short growhandle	(	void *	h,
		long	size
	)

Change the size of a handle.

Parameters:

h	The handle to resize.
size	The new size to allocate in bytes.

Returns:: Ignored.

See also:: sysmem_resizehandle()

char** newhandle ( long size )

Allocate relocatable memory.

Parameters:

size	The size to allocate in bytes.

Returns:: The allocated handle.

See also:: sysmem_newhandle()

void sysmem_copyptr	(	const void *	src,
		void *	dst,
		long	bytes
	)

Copy memory the contents of one pointer to another pointer.

This function is similar to BlockMove() or memcpy(). It copies the contents of the memory from the source to the destination pointer.

Parameters:

src	A pointer to the memory whose bytes will be copied.
dst	A pointer to the memory where the data will be copied.
bytes	The size in bytes of the data to be copied.

void sysmem_freehandle ( t_handle handle )

Free memory allocated with sysmem_newhandle().

Parameters:

handle The handle whose memory will be freed.

void sysmem_freeptr ( void * ptr )

Free memory allocated with sysmem_newptr().

This function is similar to DisposePtr or free. It frees the memory that had been allocated to the given pointer.

Parameters:

ptr	The pointer whose memory will be freed.

long sysmem_handlesize ( t_handle handle )

Find the size of a handle.

This function is similar to GetHandleSize().

Parameters:

handle The handle whose size will be queried.

Returns:: The number of bytes allocated to the specified handle.

long sysmem_lockhandle	(	t_handle	handle,
		long	lock
	)

Set the locked/unlocked state of a handle.

This function is similar to HLock or HUnlock. It sets the lock state of a handle, using a zero or non-zero number.

Parameters:

handle	The handle that will be locked.
lock	The new lock state of the handle.

Returns:: The previous lock state.

t_handle sysmem_newhandle ( long size )

Allocate a handle (a pointer to a pointer).

This function is similar to NewHandle(). It allocates a handle of a given number of bytes and returns a t_handle.

Parameters:

size	The size of the handle in bytes that will be allocated.

Returns:: A new t_handle.

t_handle sysmem_newhandleclear ( unsigned long size )

Allocate a handle (a pointer to a pointer) whose memory is set to zero.

Parameters:

size	The size of the handle in bytes that will be allocated.

Returns:: A new t_handle.

See also:: sysmem_newhandle()

BEGIN_USING_C_LINKAGE t_ptr sysmem_newptr ( long size )

Allocate memory.

This function is similar to NewPtr() or malloc(). It allocates a pointer of a given number of bytes and returns a pointer to the memory allocated.

Parameters:

size	The amount of memory to allocate.

Returns:: A pointer to the allocated memory, or NULL if the allocation fails.

t_ptr sysmem_newptrclear ( long size )

Allocate memory and set it to zero.

This function is similar to NewPtrClear() or calloc(). It allocates a pointer of a given number of bytes, zeroing all memory, and returns a pointer to the memory allocated.

Parameters:

size	The amount of memory to allocate.

Returns:: A pointer to the allocated memory, or NULL if the allocation fails.

long sysmem_nullterminatehandle ( t_handle h )

Add a null terminator to a handle.

Parameters:

h	A handle to null terminate.

Returns:: An error code.

long sysmem_ptrandhand	(	void *	p,
		t_handle	h,
		long	size
	)

Add memory to an existing handle and copy memory to the resized portion from a pointer.

This function is similar to PtrAndHand(). It resizes an existing handle by adding a given number of bytes to it and copies data from a pointer into those bytes.

Parameters:

p	The existing pointer whose data will be copied into the resized handle.
h	The handle which will be enlarged by the size of the pointer.
size	The size in bytes that will be added to the handle.

Returns:: The number of bytes allocated to the specified handle.

long sysmem_ptrbeforehand	(	void *	p,
		t_handle	h,
		unsigned long	size
	)

Add memory to an existing handle and copy memory to the resized portion from a pointer.

Unlike sysmem_ptrandhand(), however, this copies the ptr before the previously exising handle data.

Parameters:

p	The existing pointer whose data will be copied into the resized handle.
h	The handle which will be enlarged by the size of the pointer.
size	The size in bytes that will be added to the handle.

Returns:: An error code.

long sysmem_ptrsize ( void * ptr )

Find the size of a pointer.

This function is similar to _msize().

Parameters:

ptr	The pointer whose size will be queried

Returns:: The number of bytes allocated to the pointer specified.

long sysmem_resizehandle	(	t_handle	handle,
		long	newsize
	)

Resize an existing handle.

This function is similar to SetHandleSize(). It resizes an existing handle to the size specified.

Parameters:

handle	The handle that will be resized.
newsize	The new size of the handle in bytes.

Returns:: The number of bytes allocated to the specified handle.

t_ptr sysmem_resizeptr	(	void *	ptr,
		long	newsize
	)

Resize an existing pointer.

This function is similar to realloc(). It resizes an existing pointer and returns a new pointer to the resized memory.

Parameters:

ptr	The pointer to the memory that will be resized.
newsize	The new size of the pointer in bytes.

Returns:: A pointer to the resized memory, or NULL if the allocation fails.

t_ptr sysmem_resizeptrclear	(	void *	ptr,
		long	newsize
	)

Resize an existing pointer and clear it.

Parameters:

ptr	The pointer to the memory that will be resized.
newsize	The new size of the pointer in bytes.

Returns:: A pointer to the resized memory, or NULL if the allocation fails.

Defines

Functions

Detailed Description

Sysmem API

Define Documentation

Function Documentation