Macros | Functions
Memory Allocation API

Memory allocation and deallocation. More...

Macros

#define AiMalloc(_size)   AiMalloc_func(_size, __AI_FILE__, __AI_LINE__, __AI_FUNCTION__)
 
#define AiRealloc(_addr, _size)   AiRealloc_func(_addr, _size, __AI_FILE__, __AI_LINE__, __AI_FUNCTION__)
 
#define AiFree(_addr)   AiFree_func(_addr, __AI_FILE__, __AI_LINE__, __AI_FUNCTION__)
 

Functions

AI_API void * AiMalloc_func (size_t size, const char *file, int line, const char *func)
 Arnold malloc() wrapper. More...
 
AI_API void * AiRealloc_func (void *addr, size_t size, const char *file, int line, const char *func)
 Arnold realloc() wrapper. More...
 
AI_API void AiFree_func (void *addr, const char *file, int line, const char *func)
 Arnold free() wrapper. More...
 
AI_API void AiAddMemUsage (int64_t size, const AtString category)
 Track allocated memory by named category. More...
 

Detailed Description

Memory allocation and deallocation.

Function Documentation

AI_API void* AiMalloc_func ( size_t  size,
const char *  file,
int  line,
const char *  func 
)

Arnold malloc() wrapper.

Use this function just as you would use malloc() to request a block of memory. If the size requested is 0, then return NULL. If the internal call to malloc() returns NULL, which means there is not enough available memory for a block of that size, this function logs a warning message with the source code location (file and line number) of the failed call. This is a very useful debugging tip that wouldn't be possible with a regular call to malloc().

To save some typing, Arnold provides a handy AiMalloc() macro. The following two lines of code are equivalent:

1 ptr = AiMalloc_func(1024, __FILE__, __LINE__, __FUNCTION__);
2 ptr = AiMalloc(1024);
Parameters
sizenumber of bytes to allocate
filefilename of the compilation unit calling AiMalloc_func()
lineline-number of the compilation unit calling AiMalloc_func()
funcfunction the compilation unit calling AiMalloc_func()
Returns
if succesful, pointer to a newly allocated memory block, NULL otherwise
See also
AiMalloc, AiFree, AiShaderGlobalsQuickAlloc
AI_API void* AiRealloc_func ( void *  addr,
size_t  size,
const char *  file,
int  line,
const char *  func 
)

Arnold realloc() wrapper.

Checks for NULL and logs a warning message. If the requested size is 0, then the address is freed instead. In practice, you will want to use the associated shortcut macro AiRealloc().

Parameters
addrthe address of the memory block to resize
sizenumber of bytes to allocate
filefilename of the compilation unit calling AiRealloc_func()
lineline-number of the compilation unit calling AiRealloc_func()
funcfunction of the compilation unit calling AiRealloc_func()
Returns
pointer to a newly allocated memory block or NULL
See also
AiRealloc
AI_API void AiFree_func ( void *  addr,
const char *  file,
int  line,
const char *  func 
)

Arnold free() wrapper.

Releases allocated memory from AiMalloc() and AiRealloc(). Works just like free(). In practice, you will want to use the associated shortcut macro AiFree().

Parameters
addrthe address of the memory block to release
filefilename of the compilation unit calling AiFree_func()
lineline-number of the compilation unit calling AiFree_func()
funcfunction of the compilation unit calling AiFree_func()
See also
AiFree
AI_API void AiAddMemUsage ( int64_t  size,
const AtString  category 
)

Track allocated memory by named category.

You can track amounts of memory in your code you allocate (with positive values) and deallocate (with negative values). The totals will be displayed at the end of each AiRender() call in the logged memory stats. This is only valid to call in between AiBegin() and AiEnd(), but it can and should be used inside of any plugins as well as in session API usage.

Warning
If you call this from threads your own code spawns, this memory tracking will be slower than if it is called from within Arnold threads.
Parameters
sizeThe size of the allocation (if positive) or deallocation (if negative)
categoryName of the category for the allocation/deallocation

© 2020 Autodesk, Inc. · All rights reserved · www.arnoldrenderer.com