cds::gc::HRC Class Reference

Gidenstam's garbage collector. More...

#include <cds/gc/hrc.h>

Data Structures
class	atomic_marked_ptr
	Atomic marked pointer. More...
class	atomic_ref
	Atomic reference. More...
class	Guard
	HRC guard. More...
class	GuardArray
	Array of guards. More...
class	thread_gc
	Wrapper for hrc::ThreadGC class. More...

Public Types
typedef hrc::ThreadGC	thread_gc_impl
	Thread GC implementation for internal usage.
typedef hrc::ContainerNode	container_node
	Base for container node.
typedef container_node *	guarded_pointer
	Native hazard pointer type.

Public Member Functions
	HRC (size_t nHazardPtrCount=0, size_t nMaxThreadCount=0, size_t nMaxNodeLinkCount=0, size_t nMaxTransientLinks=0)
	Initializes hrc::GarbageCollector singleton. More...
	~HRC ()
	Terminates hrc::GarbageCollector singleton. More...

Static Public Member Functions
static bool	check_available_guards (size_t nCountNeeded, bool bRaiseException=true)
	Checks if count of hazard pointer is no less than nCountNeeded. More...
template<typename T >
static void	retire (T *p, void(*pFunc)(T *))
	Retire pointer p with function pFunc. More...
template<class Disposer , typename T >
static void	retire (T *p)
	Retire pointer p with functor of type Disposer. More...
static bool	isUsed ()
	Checks if HRC GC is constructed and may be used.
static void	scan ()
	Forced GC cycle call for current thread. More...
static void	force_dispose ()

Detailed Description

Gidenstam's garbage collector.

This class is a wrapper for Gidenstam's memory reclamation schema (HRC - Hazard pointer + Reference Counting) internal implementation.

Sources:

• [2006] A.Gidenstam "Algorithms for synchronization and consistency in concurrent system services", Chapter 5 "Lock-Free Memory Reclamation" Thesis for the degree of Doctor of Philosophy
• [2005] Anders Gidenstam, Marina Papatriantafilou and Philippas Tsigas "Allocating memory in a lock-free manner", Proceedings of the 13th Annual European Symposium on Algorithms (ESA 2005), Lecture Notes in Computer Science Vol. 3669, pages 229 – 242, Springer-Verlag, 2005

Note that HRC schema does not support cyclic references that significantly limits the applicability of this GC.

Usage

In your main function you declare a object of class cds::gc::HRC. This declaration initializes internal hrc::GarbageCollector singleton.

#include <cds/init.h>       // for cds::Initialize and cds::Terminate
#include <cds/gc/hrc.h>

int main(int argc, char** argv)
{
    // Initialize libcds
    cds::Initialize() ;

    {
        // Initialize HRC singleton
        cds::gc::HRC hpGC() ;

        // Some useful work
        ...
    }

    // Terminate libcds
    cds::Terminate()    ;
}

Each thread that uses cds::gc::HRC -based containers must be attached to HRC singleton. To make attachment you should declare a object of class HRC::thread_gc:

#include <cds/gc/hrc.h>

int myThreadEntryPoint()
{
    // Attach the thread to HRC singleton
    cds::gc::HRC::thread_gc myThreadGC()    ;

    // Do some work
    ...

    // The destructor of myThreadGC object detaches the thread from HRC singleton
}

In some cases, you should work in a external thread. For example, your application is a plug-in for a server that calls your code in the threads that has been created by server. In this case, you may use persistent mode of HRC::thread_gc. In this mode, the thread attaches to the HRC singleton only if it is not yet attached and never call detaching:

#include <cds/gc/hrc.h>

int myThreadEntryPoint()
{
// Attach the thread in persistent mode
cds::gc::HRC::thread_gc myThreadGC( true )    ;

// Do some work
...

// The destructor of myThreadGC object does NOT detach the thread from HRC singleton
}

Constructor & Destructor Documentation

cds::gc::HRC::HRC ( size_t  nHazardPtrCount = 0, size_t  nMaxThreadCount = 0, size_t  nMaxNodeLinkCount = 0, size_t  nMaxTransientLinks = 0  )

inline

Initializes hrc::GarbageCollector singleton.

The constructor calls hrc::GarbageCollector::Construct with passed parameters. See hrc::GarbageCollector::Construct for explanation of parameters meaning.

Parameters

nHazardPtrCount	number of hazard pointers
nMaxThreadCount	max threads count
nMaxNodeLinkCount	max number of links a hrc::ContainerNode can contain
nMaxTransientLinks	max number of links in live nodes that may transiently point to a deleted node

cds::gc::HRC::~HRC ( )

inline

Terminates hrc::GarbageCollector singleton.

The destructor calls

hrc::GarbageCollector::Destruct() 

Member Function Documentation

static bool cds::gc::HRC::check_available_guards ( size_t  nCountNeeded, bool  bRaiseException = true  )

inlinestatic

Checks if count of hazard pointer is no less than nCountNeeded.

If bRaiseException is true (that is the default), the function raises an exception gc::too_little_hazard_pointers if nCountNeeded is more than the count of hazard pointer per thread.

template<typename T >

static void cds::gc::HRC::retire ( T *  p, void(*)(T *)  pFunc  )

static

Retire pointer p with function pFunc.

The function places pointer p to array of pointers ready for removing. (so called retired pointer array). The pointer can be safely removed when no guarded pointer points to it. Deleting the pointer is the function pFunc call.

template<class Disposer , typename T >

static void cds::gc::HRC::retire ( T *  p )

static

Retire pointer p with functor of type Disposer.

The function places pointer p to array of pointers ready for removing. (so called retired pointer array). The pointer can be safely removed when no guard points to it.

See gc::HP::retire for Disposer requirements.

static void cds::gc::HRC::scan ( )

static

Forced GC cycle call for current thread.

Usually, this function should not be called directly.

---

The documentation for this class was generated from the following file:

• cds/gc/hrc_decl.h