Description

VuoHeap implementation.

Copyright: Copyright © 2012–2022 Kosada Incorporated. This code may be modified and distributed under the terms of the MIT License. For more information, see https://vuo.org/license.

Definition in file VuoHeap.cc.

Classes
struct	VuoHeapEntry
	An entry in the reference-counting table. More...

Functions
void	sendErrorWrapper (const char *message)
	Calls the vuoSendError() function defined in the runtime (without introducing a direct dependency on the runtime). More...

static bool	VuoHeap_isPointerValid (const void *pointer)
	Returns true if `pointer` looks like a valid pointer. 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...

static void	VuoHeap_makeSafePointerSummary (char summary, const void pointer)
	If `pointer` refers to allocated memory, copies its first 16 printable characters into `summary`, followed by char 0. More...

static char *	VuoHeap_makeDescription (VuoHeapEntry e)
	Returns a description of the specified heapPointer: the file, line, and function where VuoRegister() was called, and the variable name. More...

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	VuoRetainF (const void heapPointer, const char file, unsigned int linenumber, const char *func)
	Wrapper for VuoRetain. More...

int	VuoRetain (const void *heapPointer)
	Increments the reference count for heapPointer (unless heapPointer is not being reference-counted). More...

int	VuoReleaseF (const void heapPointer, const char file, unsigned int linenumber, const char *func)
	Wrapper for VuoRelease. More...

int	VuoRelease (const void *heapPointer)
	Decrements the reference count for heapPointer (unless heapPointer is not being reference-counted). More...

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

Variables
static set< const void * > *	VuoHeap_trace
	Heap pointers to trace. More...

static pthread_mutex_t	VuoHeap_mutex = PTHREAD_MUTEX_INITIALIZER
	Protects access to `referenceCounts`. More...

static map< const void , VuoHeapEntry >	referenceCounts
	The reference count for each pointer. More...

static set< const void * > *	singletons
	Known singleton pointers. More...

Class Documentation

◆ VuoHeapEntry

struct VuoHeapEntry

Class Members
DeallocateFunctionType	deallocateFunction
const char *	file
const char *	function
unsigned int	line
int	referenceCount
const char *	variable

Function Documentation

◆ sendErrorWrapper()

void sendErrorWrapper ( const char * message )

Calls the vuoSendError() function defined in the runtime (without introducing a direct dependency on the runtime).

Definition at line 29 of file VuoHeap.cc.

◆ 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 601 of file VuoHeap.cc.

◆ VuoHeap_getDescription()

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 578 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 127 of file VuoHeap.cc.

◆ VuoHeap_isPointerValid()

static bool VuoHeap_isPointerValid ( const void * pointer )

inlinestatic

Returns true if pointer looks like a valid pointer.

Changed in Vuo 2.0.0:: New.

Definition at line 91 of file VuoHeap.cc.

◆ VuoHeap_makeDescription()

static char * VuoHeap_makeDescription ( VuoHeapEntry e )

static

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 176 of file VuoHeap.cc.

◆ VuoHeap_makeSafePointerSummary()

static void VuoHeap_makeSafePointerSummary	(	char *	summary,
		const void *	pointer
	)

static

If pointer refers to allocated memory, copies its first 16 printable characters into summary, followed by char 0.

Definition at line 151 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 222 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

heapPointer	A pointer to allocated memory on the heap.
deallocate	The function to be used to deallocate the memory when the reference count gets back to its original value of 0.
file	The name of the file in which VuoRegister() is called.
linenumber	The line in the file in which VuoRegister() is called.
func	The function in which VuoRegister() is called.
pointerName	The 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 261 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 323 of file VuoHeap.cc.

◆ VuoReleaseF()

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

Wrapper for VuoRelease.

This used to be an instrumented function, but the instrumentation was removed in Vuo 1.2 to improve performance. It's still here so that plugins compiled with Vuo 0.9 through 1.1 have a better chance of linking successfully.

Deprecated:: Use VuoRelease instead.

Definition at line 464 of file VuoHeap.cc.

◆ VuoRetainF()

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

Wrapper for VuoRetain.

This used to be an instrumented function, but the instrumentation was removed in Vuo 1.2 to improve performance. It's still here so that plugins compiled with Vuo 0.9 through 1.1 have a better chance of linking successfully.

Deprecated:: Use VuoRetain instead.

Definition at line 388 of file VuoHeap.cc.

Variable Documentation

◆ referenceCounts

map<const void *, VuoHeapEntry>* referenceCounts

static

The reference count for each pointer.

Definition at line 83 of file VuoHeap.cc.

◆ singletons

set<const void *>* singletons

static

Known singleton pointers.

Definition at line 84 of file VuoHeap.cc.

◆ VuoHeap_mutex

pthread_mutex_t VuoHeap_mutex = PTHREAD_MUTEX_INITIALIZER

static

Protects access to referenceCounts.

Definition at line 24 of file VuoHeap.cc.

◆ VuoHeap_trace

set<const void *>* VuoHeap_trace

static

Heap pointers to trace.

Definition at line 23 of file VuoHeap.cc.

Description

Classes

Functions

Variables

Class Documentation

◆ VuoHeapEntry

Function Documentation

◆ sendErrorWrapper()

◆ VuoHeap_addTrace()

◆ VuoHeap_getDescription()

◆ VuoHeap_isPointerReadable()

◆ VuoHeap_isPointerValid()

◆ VuoHeap_makeDescription()

◆ VuoHeap_makeSafePointerSummary()

◆ VuoHeap_report()

◆ VuoRegisterF()

◆ VuoRegisterSingletonF()

◆ VuoReleaseF()

◆ VuoRetainF()

Variable Documentation

◆ referenceCounts

◆ singletons

◆ VuoHeap_mutex

◆ VuoHeap_trace