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.
Issues When Building With Visual Studio 2005 or Later
As of Visual Studio 2005, the VC++ compiler adds a manifest header to libraries and executable output. This manifest specifies the exact version of the system libraries that were in place when the output was linked. At load time, the library or application loads only those same versions of the system libraries as specified in the manifest. If you build using makefiles, you need to manually add the manifest instructions to your files. (See the sample makefiles in wave/demo/interapp/win32)
Mismatched system libraries can cause memory problems if a library built with the debug system libraries is linked with PV-WAVE. Any memory accessed by both can cause crashes since the debug libraries assume that all allocated blocks of memory contain extra bytes to store debugging information.
You may even be building your application in debug mode without knowing it. The files win32.mak or nt_win32.mak, often 'included' by Makefiles, assume a debug build unless NODEBUG is explicitly set to 1 before they are invoked.
