cds::gc::HP::Guard Class Reference

Hazard Pointer guard. More...

#include <cds/gc/hp.h>

Public Member Functions
	Guard ()
	Default ctor allocates a guard (hazard pointer) from thread-private storage. More...
	Guard (std::nullptr_t) noexcept
	Initilalizes an unlinked guard i.e. the guard contains no hazard pointer. Used for move semantics support.
	Guard (Guard &&src) noexcept
	Move ctor - src guard becomes unlinked (transfer internal guard ownership)
Guard &	operator= (Guard &&src) noexcept
	Move assignment: the internal guards are swapped between src and this. More...
	Guard (Guard const &)=delete
	Copy ctor is prohibited - the guard is not copyable.
Guard &	operator= (Guard const &)=delete
	Copy assignment is prohibited.
	~Guard ()
	Frees the internal hazard pointer if the guard is in linked state.
bool	is_linked () const
	Checks if the guard object linked with any internal hazard pointer.
void	link ()
	Links the guard with internal hazard pointer if the guard is in unlinked state. More...
void	unlink ()
	Unlinks the guard from internal hazard pointer; the guard becomes in unlinked state.
template<typename T >
T	protect (atomics::atomic< T > const &toGuard)
	Protects a pointer of type atomic<T*> More...
template<typename T , class Func >
T	protect (atomics::atomic< T > const &toGuard, Func f)
	Protects a converted pointer of type atomic<T*> More...
template<typename T >
T *	assign (T *p)
	Store p to the guard. More...
void	copy (Guard const &src)
	Copy a value guarded from src guard to this guard (valid only in linked state)
template<typename T , int BITMASK>
T *	assign (cds::details::marked_ptr< T, BITMASK > p)
	Store marked pointer p to the guard. More...
void	clear ()
	Clear value of the guard (valid only in linked state)
template<typename T >
T *	get () const
	Get the value currently protected (valid only in linked state)
guarded_pointer	get_native () const
	Get native hazard pointer stored (valid only in linked state)

Detailed Description

Hazard Pointer guard.

A guard is a hazard pointer. Additionally, the Guard class manages allocation and deallocation of the hazard pointer.

Guard object is movable but not copyable.

The guard object can be in two states:

• unlinked - the guard is not linked with any internal hazard pointer. In this state no operation except link() and move assignment is supported.
• linked (default) - the guard allocates an internal hazard pointer and completely operable.

Due to performance reason the implementation does not check state of the guard in runtime.

Warning

Move assignment transfers the guard in unlinked state, use with care.

Constructor & Destructor Documentation

Guard()

cds::gc::HP::Guard::Guard ( )

inline

Default ctor allocates a guard (hazard pointer) from thread-private storage.

Warning

Can throw too_many_hazard_ptr_exception if internal hazard pointer objects are exhausted.

Member Function Documentation

assign() [1/2]

template<typename T >

T* cds::gc::HP::Guard::assign ( T *  p )

inline

Store p to the guard.

The function equals to a simple assignment the value p to guard, no loop is performed. Can be used for a pointer that cannot be changed concurrently or if the pointer is already guarded by another guard.

Warning

The guad object should be in linked state, otherwise the result is undefined

assign() [2/2]

template<typename T , int BITMASK>

T* cds::gc::HP::Guard::assign ( cds::details::marked_ptr< T, BITMASK >  p )

inline

Store marked pointer p to the guard.

The function equals to a simple assignment of p.ptr(), no loop is performed. Can be used for a marked pointer that cannot be changed concurrently or if the marked pointer is already guarded by another guard.

Warning

The guard object should be in linked state, otherwise the result is undefined

link()

void cds::gc::HP::Guard::link ( )

inline

Links the guard with internal hazard pointer if the guard is in unlinked state.

Warning

Can throw not_enought_hazard_ptr_exception if internal hazard pointer array is exhausted.

operator=()

Guard& cds::gc::HP::Guard::operator= ( Guard &&  src )

inlinenoexcept

Move assignment: the internal guards are swapped between src and this.

Warning

src will become in unlinked state if this was unlinked on entry.

protect() [1/2]

template<typename T >

T cds::gc::HP::Guard::protect ( atomics::atomic< T > const &  toGuard )

inline

Protects a pointer of type atomic<T*>

Return the value of toGuard

The function tries to load toGuard and to store it to the HP slot repeatedly until the guard's value equals toGuard

Warning

The guad object should be in linked state, otherwise the result is undefined

protect() [2/2]

template<typename T , class Func >

T cds::gc::HP::Guard::protect ( atomics::atomic< T > const &  toGuard, Func  f  )

inline

Protects a converted pointer of type atomic<T*>

Return the value of toGuard

The function tries to load toGuard and to store result of f functor to the HP slot repeatedly until the guard's value equals toGuard.

The function is useful for intrusive containers when toGuard is a node pointer that should be converted to a pointer to the value before protecting. The parameter f of type Func is a functor that makes this conversion:

struct functor {
    value_type * operator()( T * p );
};

Actually, the result of f( toGuard.load()) is assigned to the hazard pointer.

Warning

The guad object should be in linked state, otherwise the result is undefined

---

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

• cds/gc/hp.h