Hazard Pointer garbage collector. More...

#include <cds/gc/hp.h>

Data Structures
struct	container_node
	Base for container node. More...

class	Guard
	Hazard Pointer guard. More...

class	GuardArray
	Array of Hazard Pointer guards. More...

class	thread_gc
	Wrapper for hzp::ThreadGC class. More...

Public Types
typedef gc::hzp::hazard_pointer	guarded_pointer
	Native guarded pointer type.

template<typename T >
using	atomic_ref = std::atomic< T * >
	Atomic reference.

template<typename MarkedPtr >
using	atomic_marked_ptr = std::atomic< MarkedPtr >
	Atomic marked pointer.

template<typename T >
using	atomic_type = std::atomic< T >
	Atomic type.

typedef hzp::ThreadGC	thread_gc_impl
	Thread GC implementation for internal usage.

Public Member Functions
	HP (size_t nHazardPtrCount=0, size_t nMaxThreadCount=0, size_t nMaxRetiredPtrCount=0, hzp::scan_type nScanType=hzp::inplace)
	Initializes hzp::GarbageCollector singleton. More...

	~HP ()
	Terminates GC singleton. More...

hzp::scan_type	getScanType () const
	Get current scan strategy. More...

void	setScanType (hzp::scan_type nScanType)
	Set current scan strategy. 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 Hazard Pointer GC is constructed and may be used.


static void	scan ()
	Forced GC cycle call for current thread. More...

static void	force_dispose ()

Detailed Description

Hazard Pointer garbage collector.

This class realizes a wrapper for Hazard Pointer garbage collector internal implementation.

Sources:

[2002] Maged M.Michael "Safe memory reclamation for dynamic lock-freeobjects using atomic reads and writes"
[2003] Maged M.Michael "Hazard Pointers: Safe memory reclamation for lock-free objects"
[2004] Andrei Alexandrescy, Maged Michael "Lock-free Data Structures with Hazard Pointers"

See How to use section for details of garbage collector applying.

Constructor & Destructor Documentation

cds::gc::HP::HP	(	size_t	nHazardPtrCount = `0`,
		size_t	nMaxThreadCount = `0`,
		size_t	nMaxRetiredPtrCount = `0`,
		hzp::scan_type	nScanType = `hzp::inplace`
	)

inline

Initializes hzp::GarbageCollector singleton.

The constructor initializes GC singleton with passed parameters. If GC instance is not exist then the function creates the instance. Otherwise it does nothing.

The Michael's HP reclamation schema depends of three parameters:

nHazardPtrCount - hazard pointer count per thread. Usually it is small number (up to 10) depending from the data structure algorithms. By default, if nHazardPtrCount = 0, the function uses maximum of the hazard pointer count for CDS library.
nMaxThreadCount - max count of thread with using Hazard Pointer GC in your application. Default is 100.
nMaxRetiredPtrCount - capacity of array of retired pointers for each thread. Must be greater than nHazardPtrCount * nMaxThreadCount . Default is 2 * nHazardPtrCount * nMaxThreadCount .

Parameters

nHazardPtrCount	Hazard pointer count per thread
nMaxThreadCount	Max count of simultaneous working thread in your application
nMaxRetiredPtrCount	Capacity of the array of retired objects for the thread
nScanType	Scan type (see hzp::scan_type enum)

cds::gc::HP::~HP ( )

inline

Terminates GC singleton.

The destructor calls

hzp::GarbageCollector::Destruct( true )

Member Function Documentation

static bool cds::gc::HP::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.

hzp::scan_type cds::gc::HP::getScanType ( ) const

inline

Get current scan strategy.

See hzp::GarbageCollector::Scan for scan algo description

template<typename T >

static void cds::gc::HP::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 hazard pointer points to it. Deleting the pointer is the function pFunc call.

template<class Disposer , typename T >

static void cds::gc::HP::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 hazard pointer points to it.

Deleting the pointer is an invocation of some object of type Disposer; the interface of Disposer is:

template <typename T>
struct disposer {
    void operator()( T * p )    ;   // disposing operator
};

Since the functor call can happen at any time after retire call, additional restrictions are imposed to Disposer type:

it should be stateless functor
it should be default-constructible
the result of functor call with argument p should not depend on where the functor will be called.

Examples:: Operator delete functor:
template <typename T>

struct disposer {

void operator ()( T * p ) {

delete p ;

}

};

// How to call GC::retire method

int * p = new int ;

// ... use p in lock-free manner

cds::gc::HP::retire<disposer>( p ) ; // place p to retired pointer array of HP GC

Functor based on std::allocator :

template <typename ALLOC = std::allocator<int> >
struct disposer {
    template <typename T>
    void operator()( T * p ) {
        typedef typename ALLOC::templare rebind<T>::other   alloc_t ;
        alloc_t a   ;
        a.destroy( p )  ;
        a.deallocate( p, 1 )    ;
    }
};

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

static

Forced GC cycle call for current thread.

Usually, this function should not be called directly.

void cds::gc::HP::setScanType ( hzp::scan_type nScanType )

inline

Set current scan strategy.

Scan strategy changing is allowed on the fly.

About scan strategy see getScanType

Parameters

nScanType new scan strategy

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

cds/gc/hp_decl.h

Data Structures

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation