Memory Management

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

Macros
#define	MM_UNIFIED
	This macro being defined means that getbytes and sysmem APIs for memory management are unified. More...

Functions
char *	getbytes (t_getbytes_size size)
	Allocate small amounts of non-relocatable memory. More...
void	freebytes (void *b, t_getbytes_size size)
	Free memory allocated with getbytes(). More...
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. More...
void	freebytes16 (char *mem, t_getbytes_size size)
	Free memory allocated with getbytes16(). More...
char **	newhandle (long size)
	Allocate relocatable memory. More...
short	growhandle (void *h, long size)
	Change the size of a handle. More...
void	disposhandle (char **h)
	Free the memory used by a handle you no longer need. More...
BEGIN_USING_C_LINKAGE t_ptr	sysmem_newptr (long size)
	Allocate memory. More...
t_ptr	sysmem_newptrclear (long size)
	Allocate memory and set it to zero. More...
t_ptr	sysmem_resizeptr (void *ptr, long newsize)
	Resize an existing pointer. More...
t_ptr	sysmem_resizeptrclear (void *ptr, long newsize)
	Resize an existing pointer and clear it. More...
long	sysmem_ptrsize (void *ptr)
	Find the size of a pointer. More...
void	sysmem_freeptr (void *ptr)
	Free memory allocated with sysmem_newptr(). More...
void	sysmem_copyptr (const void *src, void *dst, long bytes)
	Copy memory the contents of one pointer to another pointer. More...
t_handle	sysmem_newhandle (long size)
	Allocate a handle (a pointer to a pointer). More...
t_handle	sysmem_newhandleclear (unsigned long size)
	Allocate a handle (a pointer to a pointer) whose memory is set to zero. More...
long	sysmem_resizehandle (t_handle handle, long newsize)
	Resize an existing handle. More...
long	sysmem_handlesize (t_handle handle)
	Find the size of a handle. More...
void	sysmem_freehandle (t_handle handle)
	Free memory allocated with sysmem_newhandle(). More...
long	sysmem_lockhandle (t_handle handle, long lock)
	Set the locked/unlocked state of a handle. More...
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. More...
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. More...
long	sysmem_nullterminatehandle (t_handle h)
	Add a null terminator to a handle. More...

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).

Macro Definition 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 older 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.

Referenced by jit_object_exportattrs(), jit_object_importattrs(), max_jit_attr_getdump(), max_jit_obex_gimmeback(), and max_jit_obex_gimmeback_dumpout().

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.

Referenced by jit_copy_bytes().

void sysmem_freehandle

(

t_handle

handle

)

Free memory allocated with sysmem_newhandle().

Parameters

handle

The handle whose memory will be freed.

Referenced by jit_handle_free().

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.

Referenced by jit_disposeptr(), jit_freebytes(), and jit_gl_begincapture().

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.

Referenced by jit_handle_size_get().

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.

Referenced by jit_handle_lock().

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.

Referenced by jit_handle_new().

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.

Referenced by jit_getbytes(), jit_gl_begincapture(), and jit_newptr().

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.

Referenced by jit_handle_size_set().

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.