cds  2.2.0
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)
 
Guardoperator= (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.
 
Guardoperator= (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 >
protect (atomics::atomic< T > const &toGuard)
 Protects a pointer of type atomic<T*> More...
 
template<typename T , class Func >
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 fully operable.

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

Warning
Move assignment can transfer the guard in unlinked state, use with care.

Constructor & Destructor Documentation

§ Guard()

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

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)

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

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.

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

§ link()

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

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

Warning
Can throw too_many_hazard_ptr_exception if internal hazard pointer objects are 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 2.2.0 Developed by Maxim Khizhinsky aka khizmax 2007 - 2017
Autogenerated Wed Jan 4 2017 08:49:49 by Doxygen 1.8.12