Using the C Math Library

Automated Memory Management

With automated memory management, you let the library manage array memory between the initialization of arrays and the deletion of array. To use automated memory management, you must:

1. Declare and initialize local array variables at the beginning of your function.
2. Use the local array variables to perform the work of your function, assigning values to them, and passing them as input or output arguments to other functions.
3. Destroy local array variables at the end of your function.

Temporary and Bound Arrays

Automated memory management distinguishes between two types of arrays:

• Temporary arrays
• Bound arrays

Understanding the definition of the temporary and bound states for an array will help you understand:

• Why you can nest calls to library functions
• Why you need to call mlfAssign() rather than use the assignment operator (=) for assignments
• Why you need to follow the rules for writing functions presented in Using Automated Memory Management

This diagram illustrates how library functions return temporary arrays and how arrays become bound if they are assigned to an array variable (mxArray *).

Definition of a Temporary Array.   MATLAB C Math Library functions return pointers to newly allocated mxArrays as their return values. The library marks these arrays as temporary arrays.

Key Behavior for a Temporary Array.   When you pass a temporary array as an input argument to another library function, that function deletes the temporary array before it returns. You do not have to delete it yourself. This behavior allows you to embed calls to library functions as arguments to other library functions without leaking memory.

Definition of a Bound Array.   To make an array persist, you must assign it to a variable by using the function mlfAssign() or pass an array variable as an output array argument to a library function. The MATLAB C Math Library marks the array as a bound array.

Key Behavior for a Bound array.   When you pass a bound array as an input argument to another library function, the array still exists when the function completes. Bound arrays are not automatically deleted; you must explicitly delete the array by calling mxDestroyArray().

Comparison of Memory Management Schemes

To see the benefits of automated memory management, compare a sample MATLAB code and the equivalent C code under both memory management schemes.

MATLAB code:

z = sin(x) + cos(y)

C code with explicit memory management:

mxArray *temp_x, *temp_y;

temp_x = mlfSin(x);
temp_y = mlfCos(y);
z = mlfPlus(tempx, temp_y);
mxDestroyArray(temp_x);
mxDestroyArray(temp_y);

C code using automated memory management.

mlfAssign(&z, mlfPlus(mlfSin(x), mlfCos(y)));

Benefits of Automated Memory Management

Using automated memory management makes your code more like MATLAB. The code is easier to write, easier to read, and far less likely to leak memory. Because you can embed calls to library functions as function arguments (also called nested functions calls), code that requires many lines in explicit memory management can be written as a single line of code under automated memory management. Using automated memory management, you don't need to declare mxArray* variables to store temporary values, or explicitly delete those temporary arrays.

Compatibility Between Memory Management Schemes

In versions of the MATLAB C Math Library prior to Version 2.0, explicit memory management was the only memory management technique. It is still available, and existing code is compatible with the routines that use automated memory management. See Restrictions to learn about the compatibility between the two styles of managing memory.

Note    You must choose either automated memory management or explicit memory management to manage array memory in your application.

Explicit Memory Management

Avoiding Memory Leaks in Your Functions