mlfEnterNewContext (C Math Library Reference)

Establish a new memory context for the arrays passed to a function as input and output arguments

C Prototype

void mlfEnterNewContext(int nout, int nin, ...);

Arguments
int nout
Specifies the number of array (mxArray **) output arguments passed to the current function. Specify 0 if there are no output arguments or no array output arguments.

int nin
Specifies the number of array (mxArray *) input arguments. Specify 0 if there are no input arguments or no array input arguments.

optional mxArray** arguments
Pass each of the mxArray** output arguments that were passed to the current function.

optional mxArray* arguments
Pass each of the mxArray* input arguments that were passed to the current function.

You only need to list the mxArray** and mxArray* arguments. For example, if a function takes an argument of type char* or int, you do not need to include it in the count of output and input arguments or in the list of the arguments themselves.

You do not need to terminate the list with NULL; the function detects the end of the argument list from the values of nout and nin.

For more information on array input and output arguments, see the "Calling Conventions" section of the MATLAB C Math Library User's Guide.

Description

mlfEnterNewContext(), along with mlfRestorePreviousContext(), mlfReturnValue(), and mlfAssign(), implement automated memory management in the MATLAB C Math Library. Each function in the library includes calls to these functions. The functions that you write can also use automated memory management by calling these functions.

A call to mlfEnterNewContext() signals that MATLAB C Math Library automated memory management is in effect for the current function. It deletes any existing contents of the output arguments passed to it and sets the state of any temporary arrays, passed as input arguments, to bound.

mlfEnterNewContext() is paired with the function mlfRestorePreviousContext(). A call to mlfEnterNewContext() is typically the first line of code in a function, following the declaration of local variables. It must precede any calls to functions that take the array input and output parameters as arguments. A matching call to mlfRestorePreviousContext() is typically the last line of code immediately preceding the return statement.

mlfEnterNewContext() also recognizes when the current function was called from a function that does not use automated memory management. In that environment, it ensures that the input arguments, which are all temporary arrays, are handled correctly and not deleted by the automated memory management. Output arguments that do not point to NULL or to a valid array are also handled correctly.

Example

For a function defined as follows,

mxArray *ArrayMemory(mxArray **z_out, mxArray *x_in,
                    mxArray *y_in)

use the following call to mlfEnterNewContext() at the beginning of your function.

mlfEnterNewContext(1, 2, z_out, x_in, y_in);

Use the following call in your main() routine.

mlfEnterNewContext(0, 0);

mlfEnd mlfFevalLookup