Weak Pointers

Non-"owning" reference to a shared pointer. More...

Macros
#define	CSTL_WEAK_PTR_INITIALIZER(NAME)    CSTL_SHARED_PTR_INITIALIZER(NAME)
	Compile-time initialization of a weak pointer.
#define	DECLARE_CSTL_WEAK_PTR(NAME)    cstl_weak_ptr_t NAME = CSTL_WEAK_PTR_INITIALIZER(NAME)
	Compile-time declaration and initialization of a weak pointer.

Typedefs
typedef cstl_shared_ptr_t	cstl_weak_ptr_t
	The weak pointer object.

Functions
static void	cstl_weak_ptr_init (cstl_weak_ptr_t *const wp)
	Initialize a weak pointer object.
void	cstl_weak_ptr_from (cstl_weak_ptr_t *wp, const cstl_shared_ptr_t *sp)
	Create a weak pointer from a shared pointer.
void	cstl_weak_ptr_lock (const cstl_weak_ptr_t *wp, cstl_shared_ptr_t *sp)
	Convert a weak pointer to a shared pointer.
static void	cstl_weak_ptr_swap (cstl_weak_ptr_t *const wp1, cstl_weak_ptr_t *const wp2)
	Swap the memory managed by the two weak pointer objects.
void	cstl_weak_ptr_reset (cstl_weak_ptr_t *)
	Drop the reference to the underlying managed memory.

Detailed Description

Non-"owning" reference to a shared pointer.

Weak pointers point to memory managed by one or more shared pointer objects, but do not "own" it. This means that a weak pointer may be converted to a shared pointer while there is at least one other valid shared pointer still managing the memory. If there are no other shared pointer objects still managing the underlying memory, then any attempt to convert a weak pointer to a shared pointer will fail.

Macro Definition Documentation

CSTL_WEAK_PTR_INITIALIZER

#define CSTL_WEAK_PTR_INITIALIZER

(

NAME

)

CSTL_SHARED_PTR_INITIALIZER(NAME)

Compile-time initialization of a weak pointer.

Parameters

[in]

NAME

The name of the variable being initialized

Definition at line 512 of file memory.h.

DECLARE_CSTL_WEAK_PTR

#define DECLARE_CSTL_WEAK_PTR

(

NAME

)

cstl_weak_ptr_t NAME = CSTL_WEAK_PTR_INITIALIZER(NAME)

Compile-time declaration and initialization of a weak pointer.

Parameters

[in]

NAME

The name of the variable being initialized

Definition at line 519 of file memory.h.

Typedef Documentation

cstl_weak_ptr_t

typedef cstl_shared_ptr_t cstl_weak_ptr_t

The weak pointer object.

Definition at line 525 of file memory.h.

Function Documentation

cstl_weak_ptr_from()

void cstl_weak_ptr_from	(	cstl_weak_ptr_t *	wp,
		const cstl_shared_ptr_t *	sp
	)

Create a weak pointer from a shared pointer.

The weak pointer must have already been initialized, and it will be reset prior to becoming a reference to the shared memory.

Parameters

[in,out]	wp	A pointer to a weak pointer object
[in]	sp	A pointer to a shared pointer object

Definition at line 146 of file memory.c.

cstl_weak_ptr_init()

static void cstl_weak_ptr_init ( cstl_weak_ptr_t *const  wp )

inlinestatic

Initialize a weak pointer object.

Parameters

[out]

wp

A pointer to an uninitialized weak pointer object

Definition at line 532 of file memory.h.

cstl_weak_ptr_lock()

void cstl_weak_ptr_lock	(	const cstl_weak_ptr_t *	wp,
		cstl_shared_ptr_t *	sp
	)

Convert a weak pointer to a shared pointer.

The weak pointer is not modified, but if the underlying memory is still "live", the shared pointer will become an owning reference to that memory.

Parameters

[in]	wp	A pointer to a weak pointer object
[in,out]	sp	A pointer to a shared pointer object

Definition at line 160 of file memory.c.

cstl_weak_ptr_reset()

void cstl_weak_ptr_reset

(

cstl_weak_ptr_t *

wp

)

Drop the reference to the underlying managed memory.

The weak pointer does not "own" the managed memory, so if that memory is still live, this function will not cause it to be freed.

Parameters

[in,out]

wp

A pointer to a weak pointer object

Definition at line 215 of file memory.c.

cstl_weak_ptr_swap()

static void cstl_weak_ptr_swap ( cstl_weak_ptr_t *const  wp1, cstl_weak_ptr_t *const  wp2  )

inlinestatic

Swap the memory managed by the two weak pointer objects.

Parameters

[in,out]	wp1	A pointer to a weak pointer object
[in,out]	wp2	A pointer to a(nother) weak pointer object

Definition at line 565 of file memory.h.