Vuo  2.3.2
Macros | Typedefs | Functions
VuoHeap.h File Reference

Description

VuoHeap interface.

Definition in file VuoHeap.h.

Go to the source code of this file.

Macros

#define VuoRegister(heapPointer, deallocate)
 Registers heapPointer to be reference-counted and stores its deallocate function (unless heapPointer is null or is already being reference-counted). More...
 
#define VuoRegisterSingleton(heapPointer)
 Registers heapPointer as a singleton, meaning that VuoRetain and VuoRelease will have no effect on it (and will not issue warnings). More...
 
#define VuoLocal(heapPointer)
 Immediately retains heapPointer, and automatically releases it at the end of the local scope. More...
 
#define VuoWarnUnusedResult   __attribute__((warn_unused_result))
 Append this to function declarations to ensure that the caller uses/checks the return value. More...
 
#define VuoIgnoreResult(a)   (void)a
 Wrap function invocations with this to indicate that the return value is intentionally ignored. More...
 

Typedefs

typedef void(* DeallocateFunctionType) (void *)
 A type for destructor functions, such as free(void *), which are used to deallocate reference-counted memory when it's no longer in use. More...
 

Functions

void VuoHeap_report (void)
 Sends a telemetry error with information about any objects remaining in the reference counting table. More...
 
int VuoRegisterF (const void *heapPointer, DeallocateFunctionType deallocate, const char *file, unsigned int linenumber, const char *func, const char *pointerName)
 Instead of this function, you probably want to use VuoRegister(). More...
 
int VuoRegisterSingletonF (const void *heapPointer, const char *file, unsigned int linenumber, const char *func, const char *pointerName)
 Instead of this function, you probably want to use VuoRegisterSingleton(). More...
 
int VuoRetain (const void *heapPointer)
 Increments the reference count for heapPointer (unless heapPointer is not being reference-counted). More...
 
int VuoRelease (const void *heapPointer)
 Decrements the reference count for heapPointer (unless heapPointer is not being reference-counted). More...
 
bool VuoHeap_isPointerReadable (const void *pointer)
 Returns true if pointer points to a memory page that's been allocated (and therefore might be a valid pointer to 1 or more bytes of data). More...
 
const char * VuoHeap_getDescription (const void *heapPointer)
 Returns a description of the specified heapPointer: the file, line, and function where VuoRegister() was called, and the variable name. More...
 
void VuoHeap_addTrace (const void *heapPointer)
 Pass a pointer to this function to log all its subsequent retains and releases. More...
 

Macro Definition Documentation

◆ VuoIgnoreResult

#define VuoIgnoreResult (   a)    (void)a

Wrap function invocations with this to indicate that the return value is intentionally ignored.

See also
VuoIgnoreResult
Changed in Vuo 2.0.0:
New.

Definition at line 126 of file VuoHeap.h.

◆ VuoWarnUnusedResult

#define VuoWarnUnusedResult   __attribute__((warn_unused_result))

Append this to function declarations to ensure that the caller uses/checks the return value.

See also
VuoIgnoreResult
Changed in Vuo 2.0.0:
New.

Definition at line 118 of file VuoHeap.h.

Function Documentation

◆ VuoHeap_addTrace()

void VuoHeap_addTrace ( const void *  heapPointer)

Pass a pointer to this function to log all its subsequent retains and releases.

This only has an effect when CMake option VUO_HEAP_TRACE is enabled.

Definition at line 650 of file VuoHeap.cc.

◆ VuoHeap_getDescription()

const char* VuoHeap_getDescription ( const void *  heapPointer)

Returns a description of the specified heapPointer: the file, line, and function where VuoRegister() was called, and the variable name.

The caller is responsible for freeing the returned string.

Definition at line 636 of file VuoHeap.cc.

◆ VuoHeap_isPointerReadable()

bool VuoHeap_isPointerReadable ( const void *  pointer)

Returns true if pointer points to a memory page that's been allocated (and therefore might be a valid pointer to 1 or more bytes of data).

Changed in Vuo 2.0.0:
New.

Definition at line 154 of file VuoHeap.cc.

◆ VuoHeap_report()

void VuoHeap_report ( void  )

Sends a telemetry error with information about any objects remaining in the reference counting table.

Definition at line 255 of file VuoHeap.cc.

◆ VuoRegisterF()

int VuoRegisterF ( const void *  heapPointer,
DeallocateFunctionType  deallocate,
const char *  file,
unsigned int  linenumber,
const char *  func,
const char *  pointerName 
)

Instead of this function, you probably want to use VuoRegister().

This function is used to implement the VuoRegister() macro.

Registers heapPointer to be reference-counted and stores its deallocate function (unless heapPointer is null or is already being reference-counted).

Parameters
heapPointerA pointer to allocated memory on the heap.
deallocateThe function to be used to deallocate the memory when the reference count gets back to its original value of 0.
fileThe name of the file in which VuoRegister() is called.
linenumberThe line in the file in which VuoRegister() is called.
funcThe function in which VuoRegister() is called.
pointerNameThe stringified pointer variable name.
Returns
The updated reference count of heapPointer. This is 0 if heapPointer is not already being reference-counted, greater than 0 if it is, or -1 if heapPointer is null.

Definition at line 298 of file VuoHeap.cc.

◆ VuoRegisterSingletonF()

int VuoRegisterSingletonF ( const void *  heapPointer,
const char *  file,
unsigned int  linenumber,
const char *  func,
const char *  pointerName 
)

Instead of this function, you probably want to use VuoRegisterSingleton().

This function is used to implement the VuoRegisterSingleton() macro.

Definition at line 365 of file VuoHeap.cc.