void *mi_mem_allocate(
const int size)
Accepts one argument specifying the size of the memory to allocate. A pointer to the allocated memory is returned. If the allocation fails, an error is reported automatically, and the program is aborted. This call is guaranteed to return a valid pointer (or as valid as the operating system can make it, see below), or not to return at all. The allocated memory is zeroed.
void *mi_mem_reallocate(
void * const mem,
const int size)
Change the size of an allocated block of memory. There are two arguments: a pointer to the old block of memory, and the requested new size of that block. A pointer to the new block is returned, which may be different from the pointer to the old block. If the old pointer was a null pointer, mi_mem_reallocate behaves like mi_mem_allocate. If the new size is zero, mi_mem_reallocate behaves like mi_mem_release, and returns a null pointer. If there is an allocation error, an error is reported and the program is aborted. Like mi_mem_allocate, mi_mem_reallocate never returns if the re-allocation fails. If the block grows, the extra bytes are zeroed.
void *mi_mem_test_allocate(
const int size)
Accepts one argument specifying the size of the memory to allocate. A pointer to the allocated memory is returned. The allocated memory is zeroed. If the allocation fails, a null pointer is returned. This call is used when it is acceptable for an allocation to fail.
void *mi_mem_test_reallocate(
void * const mem,
const int size)
Change the size of an allocated block of memory. There are two arguments: a pointer to the old block of memory, and the requested new size of that block. A pointer to the new block is returned, which may be different from the pointer to the old block. If the old pointer was a null pointer, mi_mem_test_reallocate behaves like mi_mem_test_allocate. If the new size is zero, mi_mem_test_reallocate behaves like mi_mem_release, and returns a null pointer. If the block grows, the extra bytes are zeroed. If there is an allocation error, a null pointer is returned. This call is used when it is acceptable for an allocation to fail.
char *mi_mem_strdup(
const char * const text)
Allocates memory like mi_mem_allocate that holds enough bytes to hold the string text including the trailing null byte, copy text into it, and return a pointer to the copied string. This pointer can be freed with mi_mem_release. If text is a null pointer, nothing is allocated and a null pointer is returned; in all other cases the returned pointer is valid and need not be checked for allocation failures. This call is faster than explicit calls to mi_mem_allocate and strcpy.
void mi_mem_release(
void * const mem)
Frees a block of memory. There is one argument: the address of the block. If a null pointer is passed, nothing is done. There is no return value.
typedef void *(*miMem_alloc) (size_t size);
typedef void *(*miMem_realloc)(void *mem, size_t size);
typedef void (*miMem_free) (void *mem);
miBoolean mi_mem_set_allocator(
miMem_alloc allocfn,
miMem_realloc reallocfn,
miMem_free freefn)
This call allows applications to perform unified memory management. If used, this function must be called as part of the initialization process of the MEM module, immediately before mi_mem_init. All three parameters must be non-null. A boolean is returned, indicating whether the functions were installed. The default allocators are restored as part of the automatic shutdown of the MEM module.
typedef size_t (*miMem_flush_cb)(size_t amount);
miBoolean mi_mem_set_flush_cb(
miMem_flush_cb flushcb)
The flushcb argument is a callback which mental ray calls when it needs to free up memory. The callback takes a single parameter indicating the number of megabytes to flush, and returns the number of megabytes freed.
void mi_mem_init(void)
This function must be called as part of the initialization process of the MEM module. No MEM calls other than mi_mem_allocator and mi_mem_error_handler may be performed before MEM is initialized. It is not part of the mi_raylib_init call because it is necessary for mental ray to allocate memory earlier, for example to parse a command line or to evaluate licensing.
void mi_mem_release_all(void)
Frees all memory that is allocated at this time. This is intended for error recovery, see below. There are no arguments and no return value. After this call returns, raylib will no longer function; this should be used only if raylib is about to be unloaded.
size_t mi_mem_flush(size_t amount)
When called, mental ray will attempt to free up the amount (in megabytes) asked for. No guarantees are made, and the space may be freed up asynchronously, ie. at some time after the call itself. The number of megabytes freed up synchronously is returned.
Note that if the host application calls mental ray to flush, then it may immediately get called back through the flush callback installed with mi_mem_set_flush_cb. The host application is responsible for avoiding infinite recursion.
int mi_mem_getsize(void)
Return the total number of bytes allocated by users of the MEM module, including MEM and malloc overhead. The latter is estimated to be 8 bytes per allocation. On multithreaded systems the number may be slightly inaccurate, in rare cases even negative, because thread statistics are merged periodically, not continuously, to improve performance.
void mi_mem_summary(void)
The number of blocks and number of bytes allocated by each module, as well as a total, is printed using mi_vdebug, with information about size, address, and source file name and line number from which mi_mem_allocate and/or the last mi_mem_reallocate was called. The results may be slightly inaccurate as well.
void mi_mem_dump(
const miModule module)
A list of allocated blocks of memory is printed using mi_vdebug, with information about size, address, and source file name and line number from which mi_mem_allocate and/or the last mi_mem_reallocate was called. If memory debugging is not enabled, file and line information is omitted. If module is miM_NULL, all modules are included; otherwise, only the named module is listed. This call will typically result in an enormously large printout. The verbosity level should be 7 (see mi_set_verbosity and miERR_VDEBUG).
void mi_mem_error_handler(
(* const handler)(void))
If an error occurs, the allocation functions such as mi_mem_allocate execute the handler function. The error handler then has the option to clean up and exit, or return to retry the allocation. There is a retry limit of 1000 for a single allocation or reallocation; if the handler returns and the retry fails 999 times in a row mi_fatal is called. GUI-based client applications can use this to show a warning dialog that tells the user to make more room on the machine and then press OK to resume.
void mi_mem_check(void)
If memory debugging is compiled in, this call checks the memory arena for inconsistencies. If corruption is detected, detailed reports are printed to stdout.
void mi_memcheck_add(
miModule from,
miModule to)
void mi_memcheck_delete(
miModule from,
miModule to)
These calls are available only in debugging versions of the raylib. They arrange for calls to mi_mem_check to be done automatically whenever an internal module (such as MEM or API) is called, and when that call returns. Obviously, this can be a slow process. The from and to arguments specify that calls from module from to module to should be traced. Either or both can be miM_NULL, which is a wildcard that means ``any''. Multiple calls accumulate.
void mi_notify_add(
miModule from,
miModule to)
void mi_notify_delete(
miModule from,
miModule to)
These functions are also intended for debugging, and are available only in debugging versions of the raylib. They work like the preceding two functions, except that they print an informative message when one internal library module calls another, or returns. The verbosity level should be at least 6 (see mi_set_verbosity and miERR_DEBUG). These calls are unrelated to mi_api_notify_callback.
Copyright © 1986, 2015 NVIDIA ARC GmbH. All rights reserved.