#include <si_sys/defs.h>
Go to the source code of this file.
Classes | |
struct | sc_rep_vtable |
Structure of lifetime management functions. More... | |
struct | sc_rep |
A 'rep', or pointer-handled object. More... | |
struct | sc_ptrh |
A pointer-handle object. More... | |
Defines | |
#define | sm_repDefaultVtableDecl(n, T) |
#define | sc_ptrh_get(ph) ( (ph->priv_.rep_) ? ph->priv_.rep_->pobj : NULL) |
#define | sm_ptrhDecl(T) |
Template style macros for apparent type-safety of pointer-handles. | |
#define | sm_ptrhImpl(T) |
A macro implementing a pointer-handle to objects of the given type T. | |
Typedefs | |
typedef struct sc_rep | sc_rep |
typedef sc_status(* | sc_rep_addRef )(sc_rep *prep) |
typedef sc_status(* | sc_rep_relRef )(sc_rep *prep) |
typedef sc_status(* | sc_rep_delete )(void *pObj, void *pOwner) |
Functions | |
sc_status | sc_rep_construct (sc_rep *rep, void *pobj, void *pown, const sc_rep_vtable *vtbl) |
sc_status | sc_rep_addRef_default (sc_rep *prep) |
sc_status | sc_rep_relRef_default (sc_rep *prep) |
sc_status | sc_ptrh_construct (sc_ptrh *pptrh, sc_rep *prep) |
sc_status | sc_ptrh_constructCopy (sc_ptrh *pptrh, sc_ptrh *pother) |
sc_status | sc_ptrh_assign (sc_ptrh *pptrh, sc_ptrh *prhs) |
sc_status | sc_ptrh_assignNewRep (sc_ptrh *pptrh, sc_rep *prep) |
sc_status | sc_ptrh_destruct (sc_ptrh *pptrh) |
In many languages, notably C++, objects are sometimes "pointer-handled" meaning that their lifetime is controlled by a reference count rather than either via scope (for objects declared on the stack) or explicitly (as with the new/delete operators). Such objects contain a reference count that is incremented and decremented by pointer-handles, which represent references to the object. As long as a pointer-handle refers to the object, it remains alive. When the last pointer handle referring to the object is destructed, the object is deleted. In some circles, pointer-handles were called 'smart pointers'.
In this implementation, the underlying object being referred to is called the 'rep', and contains an sc_rep struct in its storage. Pointer-handles, which do the referring, are given as sc_ptrh structs.
#define sm_ptrhDecl | ( | T | ) |
Value:
typedef sc_ptrh T##Ptrh; \ sc_status T##Ptrh_construct(T##Ptrh* pptrh, sc_rep* prep); \ sc_status T##Ptrh_constructCopy(T##Ptrh* pptrh, T##Ptrh* pother); \ sc_status T##Ptrh_assign(T##Ptrh* pptrh, T##Ptrh* prhs); \ sc_status T##Ptrh_assignNewRep(T##Ptrh* pptrh, sc_rep* prep); \ sc_status T##Ptrh_destruct(T##Ptrh* pptrh); \ T* T##Ptrh_get(T##Ptrh* pptrh)
A macro declaring a pointer-handle to objects of the given type T. This macro declares apparently strongly typed versions of all the pointer-handle member functions. C does not always insist on the type safety, but they still serve as improvements to code readability and documentation. Note: This declaration assumes the ptrh type will be used in a statically linked fashion.
#define sm_ptrhImpl | ( | T | ) |
Value:
sc_status T##Ptrh_construct(T##Ptrh* pptrh, sc_rep* prep) \ { return sc_ptrh_construct(pptrh, prep); } \ sc_status T##Ptrh_constructCopy(T##Ptrh* pptrh, T##Ptrh* pother) \ { return sc_ptrh_constructCopy(pptrh, pother); } \ sc_status T##Ptrh_assign(T##Ptrh* pptrh, T##Ptrh* prhs) \ { return sc_ptrh_assign(pptrh, prhs); } \ sc_status T##Ptrh_assignNewRep(T##Ptrh* pptrh, sc_rep* prep) \ { return sc_ptrh_assignNewRep(pptrh, prep); } \ sc_status T##Ptrh_destruct(T##Ptrh* pptrh) \ { return sc_ptrh_destruct(pptrh); } \ T* T##Ptrh_get(T##Ptrh* pptrh) \ { return (T*) sc_ptrh_get(pptrh); }
This would typically be used in the implemenation file for the type T.
Note: This declaration assumes the ptrh type will be used in a statically linked fashion.
#define sm_repDefaultVtableDecl | ( | n, | |||
T | ) |
Value:
static const sc_rep_vtable n = { \ sc_rep_addRef_default, \ sc_rep_addRef_default, \ (sc_rep_delete)T##_delete \ }
typedef sc_status(* sc_rep_addRef)(sc_rep *prep) |
Signature for a function that adds a reference.
typedef sc_status(* sc_rep_delete)(void *pObj, void *pOwner) |
Signature for a function that deletes the underlying object when all references to it have been released.
typedef sc_status(* sc_rep_relRef)(sc_rep *prep) |
Signature for a function that releases an object reference.
Changes pptrh to reference the same object as prhs.
If pptrh is currently referencing an object, that reference is released and pptrh is modified to refer to the same object as prhs.
[in,out] | pptrh | The pointer-handle to assign to. |
[in] | prhs | The pointer-handle whose reference is copied. |
Changes pptrh to reference prep. If pptrh is currently referencing an object, that reference is released and pptrh is modified to refer to prep.
[in,out] | pptrh | The pointer-handle to assign to. |
[in] | prep | The object to reference. |
Constructor for a generic pointer-handle.
[in,out] | pptrh | Pointer handle object to initialize. |
[in] | prep | Object for the pointer-handle to reference. May be NULL. |
Constructor for a generic pointer-handle.
On exit, pptrh and pother point at the same object, whose reference count is incremented by 1.
[in,out] | pptrh | Pointer handle object to initialize. |
[in] | pother | Other pointer-handle whose reference is copied. |
sc_status sc_ptrh_destruct | ( | sc_ptrh * | pptrh | ) |
Destruct the pointer-handle, releasing the reference to its pointed-at object.
[in,out] | pptrh | The pointer-handle to destruct. |
sc_status sc_rep_addRef_default | ( | sc_rep * | prep | ) |
Default function for adding a reference to a rep object.
This effectively just does an atomic increment of the reference count of prep (the represented object, a.k.a. the pointer-handled object).
[in,out] | prep | The pointer-handled object. |
sc_status sc_rep_construct | ( | sc_rep * | rep, | |
void * | pobj, | |||
void * | pown, | |||
const sc_rep_vtable * | vtbl | |||
) |
Constructor for the sc_rep member of a pointer-handled object.
Initializes the sc_rep member of a pointer-handled object with the given values.
[in,out] | rep | The rep part of the pointer-handled, outer object. |
[in] | pobj | The pointer to the 'outer' object that is represented. |
[in] | pown | An object (usually some form of allocator) that 'owns' the storage for pobj. May be NULL. |
[in] | vtbl | A table of functions for lifetime control. |
sc_status sc_rep_relRef_default | ( | sc_rep * | prep | ) |
Default function for releasing a reference to a rep object.
This atomically decrements of the reference count, checks if all references have been released, and if so, calls delete through the v-table.
[in,out] | prep | The pointer-handled object. |