opi_malloc, opi_free, opi_realloc, opi_calloc
Allocates memory for an OPI.
C Usage
void *opi_malloc (unsigned int len);
void opi_free (void * buff);
void *opi_realloc (void * buff, unsigned int len );
void *opi_calloc (unsigned int l1, unsigned int l2 );
Input Parameters
Refer to the system functions: malloc, free, realloc, and calloc.
Returned value
Refer to the system functions: malloc, free, realloc, and calloc.
Discussion
On Windows dynamic memory allocation in an OPI that is built as a shared library uses a different address space than the memory allocation in the main executable, in this case the PV‑WAVE kernel. The consequence is that memory allocated from the OPI’s own malloc may only be freed by the same OPI’s free function. The same applies for the functions realloc and calloc.
note | The heap administration of the kernel is corrupted when the rule is violated; namely, by allocating memory in an OPI, passing a pointer to the kernel, and allowing the kernel to free this memory. |
The functions opi_malloc, opi_free, opi_realloc and opi_calloc give access to the kernel’s memory allocation routines. In order to avoid changing existing C-code, an include file is provided (opi_malloc.h). This include file has preprocessor directives which change functions calls to malloc, free, realloc and calloc into the corresponding OPI versions. You must reference the include file in an include directive (#include 'opi_malloc.h') after all system include files but before the first memory allocation function call.
C Language Error Handling
This section describes the methods an Option uses for handling C Language error conditions.
Whenever an Option’s C procedures or functions fail, the Option developer needs to be able to call the PV‑WAVE error handling mechanism. The variables that would have been returned by the Option will be undefined variables when an error occurs on the Option side.
When an OPI Call Fails
Most OPI calls return a status. It is up to the Option developer to handle the status codes appropriately. A status can have the following values:
Recovering from Errors Inside the Option Code
OPI provides access to the standard PV‑WAVE error handling functionality (see
wave_error). Currently, when an error occurs in PV‑WAVE, the interpreter recovers itself as best it can and then takes whatever action the user requested via the ON_ERROR and ON_IOERROR commands. To remain consistent with that model, an Option procedure or function needs to be able to tell the calling interpreter that the option procedure or function did not complete successfully. Then the interpreter will not continue interpreting any command that depends on the results of the Option procedure or function.
