Used to hold diverse child handles and ensure orderly destruction. More...

#include <oxr/common/oxr_handle_base.h>

Inheritance diagram for oxr_handle_parent_base:

Collaboration diagram for oxr_handle_parent_base:

[legend]

Public Member Functions
XrResult	oxr_handle_parent_destroy (struct oxr_logger log, struct oxr_handle_parent_base hpb)
	Destroy the handle's object, as well as all child handles recursively.

Public Member Functions inherited from oxr_handle_base
XrResult	oxr_handle_destroy (struct oxr_logger log, struct oxr_handle_base hb)
	Destroy the handle's object.

Data Fields
struct oxr_handle_base	base

struct oxr_handle_array	children
	Array of children, if any.

Data Fields inherited from oxr_handle_base
uint64_t	debug
	Magic (per-handle-type) value for debugging.

struct oxr_handle_parent_base *	parent
	Pointer to this object's parent handle holder, if any.

enum oxr_handle_state	state
	Current handle state.

oxr_handle_destroyer	destroy
	Destroy the object this handle refers to.

Protected Member Functions
XrResult	oxr_handle_parent_init (struct oxr_logger log, struct oxr_handle_parent_base hpb, uint64_t debug, oxr_handle_destroyer destroy, struct oxr_handle_parent_base *parent)
	Initialize a handle holder, and if a parent is specified, update its child list to include this handle.

XrResult	oxr_handle_parent_destroy_internal (struct oxr_logger log, struct oxr_handle_parent_base hpb, int level)
	Recursively destroys a handle and all of its children, removing it from its parent if it has one.

Protected Member Functions inherited from oxr_handle_base
XrResult	oxr_handle_init (struct oxr_logger log, struct oxr_handle_base hb, uint64_t debug, oxr_handle_destroyer destroy, struct oxr_handle_parent_base *parent)
	Initialize a handle, and if a parent is specified, update its child list to include this handle.

XrResult	oxr_handle_destroy_internal (struct oxr_logger log, struct oxr_handle_base hb, int level)
	Destroys a single handle, removing it from its parent if it has one.

Related Symbols
(Note that these are not member symbols.)
XrResult	oxr_handle_parent_allocate_and_init (struct oxr_logger log, size_t size, uint64_t debug, oxr_handle_destroyer destroy, struct oxr_handle_parent_base parent, void **out)
	Allocate some memory for use as a handle holder, and initialize it as a handle holder.

#define	OXR_ALLOCATE_HANDLE_PARENT(LOG, OUT, DEBUG, DESTROY, PARENT) oxr_handle_parent_allocate_and_init(LOG, sizeof(OUT), DEBUG, DESTROY, PARENT, (void *)&OUT)
	Allocates memory for a handle holder and evaluates to an XrResult.

#define	OXR_ALLOCATE_HANDLE_PARENT_OR_RETURN(LOG, OUT, DEBUG, DESTROY, PARENT)
	Allocate memory for a handle holder, returning in case of failure.

Related Symbols inherited from oxr_handle_base
typedef XrResult(*	oxr_handle_destroyer) (struct oxr_logger log, struct oxr_handle_base hb)
	Function pointer type for a handle destruction function.

XrResult	oxr_handle_allocate_and_init (struct oxr_logger log, size_t size, uint64_t debug, oxr_handle_destroyer destroy, struct oxr_handle_parent_base parent, void **out)
	Allocate some memory for use as a handle, and initialize it as a handle.

const char *	oxr_handle_state_to_string (enum oxr_handle_state state)
	Returns a human-readable label for a handle state.

#define	OXR_ALLOCATE_HANDLE(LOG, OUT, DEBUG, DESTROY, PARENT) oxr_handle_allocate_and_init(LOG, sizeof(OUT), DEBUG, DESTROY, PARENT, (void *)&OUT)
	Allocates memory for a handle and evaluates to an XrResult.

#define	OXR_ALLOCATE_HANDLE_OR_RETURN(LOG, OUT, DEBUG, DESTROY, PARENT)
	Allocate memory for a handle, returning in case of failure.

Detailed Description

Used to hold diverse child handles and ensure orderly destruction.

Member Function Documentation

◆ oxr_handle_parent_destroy()

XrResult oxr_handle_parent_destroy	(	struct oxr_logger *	log,
		struct oxr_handle_parent_base *	hpb
	)

Destroy the handle's object, as well as all child handles recursively.

This should be how all handle-associated objects are destroyed.

References oxr_handle_parent_destroy_internal().

◆ oxr_handle_parent_destroy_internal()

XrResult oxr_handle_parent_destroy_internal	(	struct oxr_logger *	log,
		struct oxr_handle_parent_base *	hpb,
		int	level
	)

protected

Recursively destroys a handle and all of its children, removing it from its parent if it has one.

oxr_handle_parent_destroy wraps this to provide some extra output and start level at 0. level, which is reported in debug output, is the current depth of recursion.

References children, oxr_handle_array_destroy(), and oxr_handle_base::oxr_handle_destroy_internal().

Referenced by oxr_handle_parent_destroy().

◆ oxr_handle_parent_init()

XrResult oxr_handle_parent_init	(	struct oxr_logger *	log,
		struct oxr_handle_parent_base *	hpb,
		uint64_t	debug,
		oxr_handle_destroyer	destroy,
		struct oxr_handle_parent_base *	parent
	)

protected

Initialize a handle holder, and if a parent is specified, update its child list to include this handle.

Friends And Related Symbol Documentation

◆ OXR_ALLOCATE_HANDLE_PARENT

#define OXR_ALLOCATE_HANDLE_PARENT	(	LOG,
		OUT,
		DEBUG,
		DESTROY,
		PARENT
	)	oxr_handle_parent_allocate_and_init(LOG, sizeof(OUT), DEBUG, DESTROY, PARENT, (void *)&OUT)

Parameters

LOG	pointer to struct oxr_logger
OUT	the pointer to handle struct type you already created.
DEBUG	Magic per-type debugging constant
DESTROY	Handle destructor function
PARENT	a parent handle, if any

Use when you want to do something other than immediately returning in case of failure. If returning immediately is OK, see OXR_ALLOCATE_HANDLE_PARENT_OR_RETURN().

◆ OXR_ALLOCATE_HANDLE_PARENT_OR_RETURN

#define OXR_ALLOCATE_HANDLE_PARENT_OR_RETURN	(	LOG,
		OUT,
		DEBUG,
		DESTROY,
		PARENT
	)

        do {                                                                                                           \
                /* static assert that out has field 'handle' of type struct oxr_handle_parent_base */                  \
                ASSERT_HANDLE_TYPE(OUT, typeof(*OUT), struct oxr_handle_parent_base);                                  \
                XrResult allocResult = OXR_ALLOCATE_HANDLE_PARENT(LOG, OUT, DEBUG, DESTROY, PARENT);                   \
                if (allocResult != XR_SUCCESS) {                                                                       \
                        return allocResult;                                                                            \
                }                                                                                                      \
        } while (0)

Allocate memory for a handle holder, returning in case of failure.

Parameters

LOG	pointer to struct oxr_logger
OUT	the pointer to handle struct type you already created.
DEBUG	Magic per-type debugging constant
DESTROY	Handle destructor function
PARENT	a parent handle, if any

Will return an XrResult from the current function if something fails. If that's not OK, see OXR_ALLOCATE_HANDLE_PARENT().

◆ oxr_handle_parent_allocate_and_init()

XrResult oxr_handle_parent_allocate_and_init	(	struct oxr_logger *	log,
		size_t	size,
		uint64_t	debug,
		oxr_handle_destroyer	destroy,
		struct oxr_handle_parent_base *	parent,
		void **	out
	)

Mainly for internal use - use OXR_ALLOCATE_HANDLE_PARENT instead which wraps this.

Field Documentation

◆ children

struct oxr_handle_array oxr_handle_parent_base::children

Array of children, if any.

Referenced by oxr_handle_base::oxr_handle_destroy_internal(), oxr_handle_parent_destroy_internal(), and oxr_session::oxr_session_attach_action_sets().

The documentation for this struct was generated from the following file:

state_trackers/oxr/common/oxr_handle_base.h

Public Member Functions

Data Fields

Protected Member Functions

Related Symbols