Shared Pointers

Reference-counted, dynamically-allocated memory. More...

Data Structures
struct	cstl_shared_ptr_t
	The shared pointer object. More...

Macros
#define	CSTL_SHARED_PTR_INITIALIZER(NAME)
	Compile-time initialization of a declared shared pointer.
#define	DECLARE_CSTL_SHARED_PTR(NAME)    cstl_shared_ptr_t NAME = CSTL_SHARED_PTR_INITIALIZER(NAME)
	Compile-time declaration and initialization of a shared pointer.

Functions
static void	cstl_shared_ptr_init (cstl_shared_ptr_t *const sp)
	Initialize a shared pointer object.
void	cstl_shared_ptr_alloc (cstl_shared_ptr_t *sp, size_t sz, cstl_xtor_func_t *clr)
	Dynamically allocated memory to be shared via the object.
bool	cstl_shared_ptr_unique (const cstl_shared_ptr_t *sp)
	Determine if a shared pointer uniquely owns the underlying memory.
const void *	cstl_shared_ptr_get_const (const cstl_shared_ptr_t *)
	Get a pointer to the memory managed by the object.
static void *	cstl_shared_ptr_get (cstl_shared_ptr_t *const sp)
	Get a pointer to the memory managed by the object.
void	cstl_shared_ptr_share (const cstl_shared_ptr_t *ex, cstl_shared_ptr_t *n)
	Create a new shared pointer object to manage the underlying memory.
static void	cstl_shared_ptr_swap (cstl_shared_ptr_t *const sp1, cstl_shared_ptr_t *const sp2)
	Swap the memory managed by the two objects.
void	cstl_shared_ptr_reset (cstl_shared_ptr_t *sp)
	Stop managing the underlying memory via this object.

Detailed Description

Reference-counted, dynamically-allocated memory.

The shared pointer object manages dynamically-allocated memory by allowing it to be shared through the use of reference counting. Multiple shared pointer objects may point to the same dynamically allocated memory. The caller is responsible for mediating access to the allocated memory, but the shared pointer object(s) will manage the lifetime of that memory.

See also

Weak Pointers

Macro Definition Documentation

CSTL_SHARED_PTR_INITIALIZER

#define CSTL_SHARED_PTR_INITIALIZER

(

NAME

)

Value:

    {                                                           \
        .data = CSTL_GUARDED_PTR_INITIALIZER(NAME.data),        \
    }

Compile-time initialization of a declared shared pointer.

Parameters

[in]

NAME

The name of the variable being initialized

Definition at line 380 of file memory.h.

DECLARE_CSTL_SHARED_PTR

#define DECLARE_CSTL_SHARED_PTR

(

NAME

)

cstl_shared_ptr_t NAME = CSTL_SHARED_PTR_INITIALIZER(NAME)

Compile-time declaration and initialization of a shared pointer.

Parameters

[in]

NAME

The name of the variable being declared

Definition at line 389 of file memory.h.

Function Documentation

cstl_shared_ptr_alloc()

void cstl_shared_ptr_alloc	(	cstl_shared_ptr_t *	sp,
		size_t	sz,
		cstl_xtor_func_t *	clr
	)

Dynamically allocated memory to be shared via the object.

The supplied shared pointer object must have already been initialized and will be reset an preparation for the new allocation.

Parameters

[in,out]	sp	A pointer to the shared pointer object
[in]	sz	The number of bytes to allocate
[in]	clr	A function to be called when the allocated memory is freed. This pointer may be NULL

Definition at line 65 of file memory.c.

cstl_shared_ptr_get()

static void * cstl_shared_ptr_get ( cstl_shared_ptr_t *const  sp )

inlinestatic

Get a pointer to the memory managed by the object.

Returns

A pointer to the managed memory

Return values

NULL	No memory is managed by the object

Definition at line 450 of file memory.h.

cstl_shared_ptr_get_const()

const void * cstl_shared_ptr_get_const

(

const cstl_shared_ptr_t *

sp

)

Get a pointer to the memory managed by the object.

Returns

A pointer to the managed memory

Return values

NULL	No memory is managed by the object

Definition at line 103 of file memory.c.

cstl_shared_ptr_init()

static void cstl_shared_ptr_init ( cstl_shared_ptr_t *const  sp )

inlinestatic

Initialize a shared pointer object.

Upon return, the shared pointer manages no memory.

Parameters

[out]

sp

A pointer to a shared pointer object

Definition at line 408 of file memory.h.

cstl_shared_ptr_reset()

void cstl_shared_ptr_reset

(

cstl_shared_ptr_t *

sp

)

Stop managing the underlying memory via this object.

If this object is the last object managing the underlying memory, the underlying memory will be free with its clear function, if present, being called just prior to that.

Parameters

[in,out]

sp

A pointer to the shared object

Definition at line 128 of file memory.c.

cstl_shared_ptr_share()

void cstl_shared_ptr_share	(	const cstl_shared_ptr_t *	ex,
		cstl_shared_ptr_t *	n
	)

Create a new shared pointer object to manage the underlying memory.

Parameters

[in]	ex	A pointer to the existing shared pointer
[in,out]	n	A pointer to a object with which to shared the existing memory

Definition at line 113 of file memory.c.

cstl_shared_ptr_swap()

static void cstl_shared_ptr_swap ( cstl_shared_ptr_t *const  sp1, cstl_shared_ptr_t *const  sp2  )

inlinestatic

Swap the memory managed by the two objects.

Parameters

[in,out]	sp1	A pointer to a shared pointer object
[in,out]	sp2	A pointer to a(nother) shared pointer object

Definition at line 470 of file memory.h.

cstl_shared_ptr_unique()

bool cstl_shared_ptr_unique

(

const cstl_shared_ptr_t *

sp

)

Determine if a shared pointer uniquely owns the underlying memory.

If this function returns true, there are no other pointers to the underlying memory, weak or shared.

Parameters

[in]

sp

A shared pointer object

Return values

true	The shared pointer manages no memory or is the only owner of the memory it manages
false	The underlying memory has more than one owner

Definition at line 92 of file memory.c.