typedef ompd_rc_t (*ompd_callback_memory_alloc_fn_t) (
ompd_size_t nbytes,
void **ptr
);
The OMPD library must not access the heap manager directly. Instead, if it needs heap memory it must use the memory allocation and deallocation callback functions that are described in this section, ompd_callback_memory_alloc_fn_t (see Section 5.4.1.1) and ompd_callback_memory_free_fn_t (see Section 5.4.1.2), which are provided by the third-party tool to obtain and to release heap memory. This mechanism ensures that the library does not interfere with any custom memory management scheme that the third-party tool may use.
If the OMPD library is implemented in C++ then memory management operators, like new and delete and their variants, must all be overloaded and implemented in terms of the callbacks that the third-party tool provides. The OMPD library must be implemented in a manner such that any of its definitions of new or delete do not interfere with any that the third-party tool defines.
In some cases, the OMPD library must allocate memory to return results to the third-party tool. The third-party tool then owns this memory and has the responsibility to release it. Thus, the OMPD library and the third-party tool must use the same memory manager.
The OMPD library creates OMPD handles, which are opaque to the third-party tool and may have a complex internal structure. The third-party tool cannot determine if the handle pointers that the API returns correspond to discrete heap allocations. Thus, the third-party tool must not simply deallocate a handle by passing an address that it receives from the OMPD library to its own memory manager. Instead, the OMPD API includes functions that the third-party tool must use when it no longer needs a handle.
A third-party tool creates contexts and passes them to the OMPD library. The OMPD library does not release contexts; instead the third-party tool releases them after it releases any handles that may reference the contexts.
Summary The ompd_callback_memory_alloc_fn_t type is the type signature of the callback routine that the third-party tool provides to the OMPD library to allocate memory.
Description The ompd_callback_memory_alloc_fn_t type is the type signature of the memory allocation callback routine that the third-party tool provides. The OMPD library may call the ompd_callback_memory_alloc_fn_t callback function to allocate memory.
Description of Arguments The nbytes argument is the size in bytes of the block of memory to allocate.
The address of the newly allocated block of memory is returned in the location to which the ptr argument points. The newly allocated block is suitably aligned for any type of variable and is not guaranteed to be set to zero.
Description of Return Codes Routines that use the ompd_callback_memory_alloc_fn_t type may return the general return codes listed at the beginning of Section 5.4.
Summary The ompd_callback_memory_free_fn_t type is the type signature of the callback routine that the third-party tool provides to the OMPD library to deallocate memory.
Description The ompd_callback_memory_free_fn_t type is the type signature of the memory deallocation callback routine that the third-party tool provides. The OMPD library may call the ompd_callback_memory_free_fn_t callback function to deallocate memory that was obtained from a prior call to the ompd_callback_memory_alloc_fn_t callback function.
Description of Arguments The ptr argument is the address of the block to be deallocated.
Description of Return Codes Routines that use the ompd_callback_memory_free_fn_t type may return the general return codes listed at the beginning of Section 5.4.