Vuo  2.4.0
Macros | Typedefs | Functions

Description

Functions to manage memory for heap-allocated port and node instance data.

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...
 

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

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...
 

Macro Definition Documentation

◆ VuoLocal

#define VuoLocal (   heapPointer)

Immediately retains heapPointer, and automatically releases it at the end of the local scope.

When working with local reference-counted variables, typically you make the object, retain it, work with it, then release it:

VuoThing thing = VuoThing_make();
VuoRetain(thing);
// do stuff
VuoRelease(thing);
return;

But if this code has multiple exit points (for example, returning early upon encountering a runtime error), it can be tricky to remember to release at all the right times:

VuoThing thing = VuoThing_make();
VuoRetain(thing);
// do stuff
if (error)
return; // Bad: thing was leaked.
// do stuff
VuoRelease(thing);
return;

Instead, you can use this macro to simplify local reference-counting:

VuoThing thing = VuoThing_make();
VuoLocal(thing);
// do stuff
if (error)
return; // OK: VuoLocal automatically releases thing.
// do stuff
return; // OK: VuoLocal automatically releases thing.

Definition at line 106 of file VuoHeap.h.

◆ VuoRegister

#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).

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.
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 45 of file VuoHeap.h.

◆ VuoRegisterSingleton

#define VuoRegisterSingleton (   heapPointer)

Registers heapPointer as a singleton, meaning that VuoRetain and VuoRelease will have no effect on it (and will not issue warnings).

Parameters
heapPointerA pointer to allocated memory on the heap.
Returns
The updated reference count of heapPointer. This is 0 if heapPointer is not already being reference-counted, 1 if it is, or -1 if heapPointer is null.

Definition at line 58 of file VuoHeap.h.

Typedef Documentation

◆ DeallocateFunctionType

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.

Definition at line 30 of file VuoHeap.h.

Function Documentation

◆ VuoRelease()

int VuoRelease ( const void *  heapPointer)

Decrements the reference count for heapPointer (unless heapPointer is not being reference-counted).

If the reference count becomes 0, heapPointer is deallocated and is no longer reference-counted.

Parameters
heapPointerA pointer to allocated memory on the heap.
Returns
The updated reference count of heapPointer, or -1 if heapPointer is not being reference-counted, has never been retained, or is null.

Definition at line 527 of file VuoHeap.cc.

◆ VuoRetain()

int VuoRetain ( const void *  heapPointer)

Increments the reference count for heapPointer (unless heapPointer is not being reference-counted).

Parameters
heapPointerA pointer to allocated memory on the heap.
Returns
The updated reference count of heapPointer, or -1 if heapPointer is not being reference-counted or is null.

Definition at line 445 of file VuoHeap.cc.