Dynamically-allocated memory with a single owner. More...

Data Structures
struct	cstl_unique_ptr_t
	A pointer that has a single "owner". More...

Macros
#define	CSTL_UNIQUE_PTR_INITIALIZER(NAME)
	Initialize (at compile time) a unique pointer.

#define	DECLARE_CSTL_UNIQUE_PTR(NAME)
	Declare and initialize a unique pointer.

Functions
static void	cstl_unique_ptr_init (cstl_unique_ptr_t *const up)
	Initialize a unique pointer.

void	cstl_unique_ptr_alloc (cstl_unique_ptr_t up, size_t len, cstl_xtor_func_t clr, void *priv)
	Dynamically allocate memory to be managed by the unique pointer.

static const void *	cstl_unique_ptr_get_const (const cstl_unique_ptr_t *const up)
	Get the pointer managed by the unique pointer object.

static void *	cstl_unique_ptr_get (cstl_unique_ptr_t *const up)
	Get the pointer managed by the unique pointer object.

static void *	cstl_unique_ptr_release (cstl_unique_ptr_t const up, cstl_xtor_func_t const clr, void *priv)
	Stop a unique pointer object from managing a pointer.

static void	cstl_unique_ptr_swap (cstl_unique_ptr_t const up1, cstl_unique_ptr_t const up2)
	Swap the objects pointed to by the parameters.

void	cstl_unique_ptr_reset (cstl_unique_ptr_t *up)
	Free the memory managed by a unique pointer.

Detailed Description

Dynamically-allocated memory with a single owner.

The unique pointer is meant to have a single owner. It may be shared, but that sharing is temporary, i.e. the sharing must end when the callee returns/goes out of scope. Alternatively, the callee may take ownership of the pointer by transferring it out of the caller's unique pointer object and into its own.

The unique pointer object manages the dynamically allocated memory via the cstl_guarded_ptr object, and some functions may abort() if they detect that that objects rules have been violated.

Macro Definition Documentation

◆ CSTL_UNIQUE_PTR_INITIALIZER

#define CSTL_UNIQUE_PTR_INITIALIZER ( NAME )

Value:

    {                                                   \
        .gp = CSTL_GUARDED_PTR_INITIALIZER(NAME.gp),    \
        .clr = {                                        \
            .func = NULL,                               \
            .priv = NULL,                               \
        },                                              \
    }

Initialize (at compile time) a unique pointer.

Parameters

[in] NAME The name of the object being initialized

Definition at line 213 of file memory.h.

◆ DECLARE_CSTL_UNIQUE_PTR

#define DECLARE_CSTL_UNIQUE_PTR ( NAME )

Value:

cstl_unique_ptr_t NAME = \

CSTL_UNIQUE_PTR_INITIALIZER(NAME)

cstl_unique_ptr_t

A pointer that has a single "owner".

Definition memory.h:234

Declare and initialize a unique pointer.

Parameters

[in] NAME The name of the variable being declared

Definition at line 226 of file memory.h.

Function Documentation

◆ cstl_unique_ptr_alloc()

void cstl_unique_ptr_alloc	(	cstl_unique_ptr_t *	up,
		size_t	len,
		cstl_xtor_func_t *	clr,
		void *	priv
	)

Dynamically allocate memory to be managed by the unique pointer.

The function allocates the requested number of bytes via malloc(), and stores the resulting pointer within the unique pointer object. The caller may provide a "clear" function that will be called prior to the memory being freed whin the unique pointer is reset.

Parameters

[in]	up	A pointer to a unique pointer object
[in]	len	The number of bytes to allocate
[in]	clr	A pointer to a function to call when the memory is freed. This pointer may be NULL
[in]	priv	A pointer to be passed to the `clr` function

Definition at line 41 of file memory.c.

◆ cstl_unique_ptr_get()

static void * cstl_unique_ptr_get ( cstl_unique_ptr_t *const up )

inlinestatic

Get the pointer managed by the unique pointer object.

Parameters

[in] up A pointer to a unique pointer object

Returns: The pointer managed by the unique pointer object

Return values

NULL	No pointer is managed by the unique pointer object

Definition at line 288 of file memory.h.

◆ cstl_unique_ptr_get_const()

static const void * cstl_unique_ptr_get_const ( const cstl_unique_ptr_t *const up )

inlinestatic

Get the pointer managed by the unique pointer object.

Parameters

[in] up A pointer to a unique pointer object

Returns: The pointer managed by the unique pointer object

Return values

NULL	No pointer is managed by the unique pointer object

Definition at line 281 of file memory.h.

◆ cstl_unique_ptr_init()

static void cstl_unique_ptr_init ( cstl_unique_ptr_t *const up )

inlinestatic

Initialize a unique pointer.

Parameters

[out] up A pointer to a unique pointer object

Definition at line 249 of file memory.h.

◆ cstl_unique_ptr_release()

static void * cstl_unique_ptr_release	(	cstl_unique_ptr_t *const	up,
		cstl_xtor_func_t **const	clr,
		void **	priv
	)

inlinestatic

Stop a unique pointer object from managing a pointer.

The managed pointer is returned, and the clear function is also returned via the parameter, if non-NULL. Upon return, the object does not manage any pointer and the caller is responsible for calling the associated clear function and freeing the memory.

Parameters

[in]	up	A pointer to a unique pointer object
[out]	clr	A pointer to a function pointer to receive a pointer to the associated clear function. This parameter may be NULL
[out]	priv	A pointer that would have been passed to the `clr` function

Returns: The formerly managed pointer

Return values

NULL	The object was not managing a pointer

Definition at line 311 of file memory.h.

◆ cstl_unique_ptr_reset()

void cstl_unique_ptr_reset ( cstl_unique_ptr_t * up )

Free the memory managed by a unique pointer.

The managed pointer's clear function, if any, is called, and the memory managed by the unique pointer is freed. Upon return, the object no longer manages any memory and is in a newly initialized state

Parameters

[in,out] up A pointer to the unique pointer object

Definition at line 55 of file memory.c.

◆ cstl_unique_ptr_swap()

static void cstl_unique_ptr_swap	(	cstl_unique_ptr_t *const	up1,
		cstl_unique_ptr_t *const	up2
	)

inlinestatic

Swap the objects pointed to by the parameters.

Parameters

[in,out]	up1	A pointer to a unique pointer object
[in,out]	up2	A pointer to a(nother) unique pointer object

Definition at line 332 of file memory.h.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ CSTL_UNIQUE_PTR_INITIALIZER

◆ DECLARE_CSTL_UNIQUE_PTR

Function Documentation

◆ cstl_unique_ptr_alloc()

◆ cstl_unique_ptr_get()

◆ cstl_unique_ptr_get_const()

◆ cstl_unique_ptr_init()

◆ cstl_unique_ptr_release()

◆ cstl_unique_ptr_reset()

◆ cstl_unique_ptr_swap()