defs/si_std/ptrh.h File Reference

An implementation of pointer-handles for C style objects and structures. More...

#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)


Detailed Description

An implementation of pointer-handles for C style objects and structures.

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 Documentation

#define sm_ptrhDecl (  ) 

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)
Template style macros for apparent type-safety of pointer-handles.

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 (  ) 

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); }
A macro implementing a pointer-handle to objects of the given type T.

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,
 ) 

Value:

static const sc_rep_vtable n = { \
      sc_rep_addRef_default,         \
      sc_rep_addRef_default,         \
      (sc_rep_delete)T##_delete      \
    }
A macro declaring a default v-table for lifetime management.
Note:
This macro assumes you have defined a T_delete function for your type T.
See also:
sc_rep_vtable


Typedef Documentation

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.


Function Documentation

sc_status sc_ptrh_assign ( sc_ptrh pptrh,
sc_ptrh prhs 
)

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.

Parameters:
[in,out] pptrh The pointer-handle to assign to.
[in] prhs The pointer-handle whose reference is copied.

sc_status sc_ptrh_assignNewRep ( sc_ptrh pptrh,
sc_rep prep 
)

Changes pptrh to reference prep. If pptrh is currently referencing an object, that reference is released and pptrh is modified to refer to prep.

Parameters:
[in,out] pptrh The pointer-handle to assign to.
[in] prep The object to reference.
See also:
sc_ptrh_assign

sc_status sc_ptrh_construct ( sc_ptrh pptrh,
sc_rep prep 
)

Constructor for a generic pointer-handle.

Parameters:
[in,out] pptrh Pointer handle object to initialize.
[in] prep Object for the pointer-handle to reference. May be NULL.

sc_status sc_ptrh_constructCopy ( sc_ptrh pptrh,
sc_ptrh pother 
)

Constructor for a generic pointer-handle.

On exit, pptrh and pother point at the same object, whose reference count is incremented by 1.

Parameters:
[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.

Parameters:
[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).

Parameters:
[in,out] prep The pointer-handled object.
See also:
sc_rep_addRef

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.

Parameters:
[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.

Parameters:
[in,out] prep The pointer-handled object.
See also:
sc_rep_relRef


doxygen