33 Concurrency support library [thread]

33.11 Safe reclamation [saferecl]

33.11.3 Hazard pointers [saferecl.hp]

33.11.3.4 Class hazard_pointer [saferecl.hp.holder]

33.11.3.4.1 General [saferecl.hp.holder.general]

namespace std { class hazard_pointer { public: hazard_pointer() noexcept; hazard_pointer(hazard_pointer&&) noexcept; hazard_pointer& operator=(hazard_pointer&&) noexcept; ~hazard_pointer(); [[nodiscard]] bool empty() const noexcept; template<class T> T* protect(const atomic<T*>& src) noexcept; template<class T> bool try_protect(T*& ptr, const atomic<T*>& src) noexcept; template<class T> void reset_protection(const T* ptr) noexcept; void reset_protection(nullptr_t = nullptr) noexcept; void swap(hazard_pointer&) noexcept; }; }
1
#
An object of type hazard_pointer is either empty or owns a hazard pointer.
Each hazard pointer is owned by exactly one object of type hazard_pointer.
[Note 1: 
An empty hazard_pointer object is different from a hazard_pointer object that owns an unassociated hazard pointer.
An empty hazard_pointer object does not own any hazard pointers.
— end note]

33.11.3.4.2 Constructors, destructor, and assignment [saferecl.hp.holder.ctor]

🔗
hazard_pointer() noexcept;
1
#
Postconditions: *this is empty.
🔗
hazard_pointer(hazard_pointer&& other) noexcept;
2
#
Postconditions: If other is empty, *this is empty.
Otherwise, *this owns the hazard pointer originally owned by other; other is empty.
🔗
~hazard_pointer();
3
#
Effects: If *this is not empty, destroys the hazard pointer owned by *this, thereby ending its current protection epoch.
🔗
hazard_pointer& operator=(hazard_pointer&& other) noexcept;
4
#
Effects: If this == &other is true, no effect.
Otherwise, if *this is not empty, destroys the hazard pointer owned by *this, thereby ending its current protection epoch.
5
#
Postconditions: If other was empty, *this is empty.
Otherwise, *this owns the hazard pointer originally owned by other.
If this != &other is true, other is empty.
6
#
Returns: *this.

33.11.3.4.3 Member functions [saferecl.hp.holder.mem]

🔗
[[nodiscard]] bool empty() const noexcept;
1
#
Returns: true if and only if *this is empty.
🔗
template<class T> T* protect(const atomic<T*>& src) noexcept;
2
#
Effects: Equivalent to: T* ptr = src.load(memory_order::relaxed); while (!try_protect(ptr, src)) {} return ptr;
🔗
template<class T> bool try_protect(T*& ptr, const atomic<T*>& src) noexcept;
3
#
Mandates: T is a hazard-protectable type.
4
#
Preconditions: *this is not empty.
5
#
Effects: Performs the following steps in order:
  • (5.1)
    Initializes a variable old of type T* with the value of ptr.
  • (5.2)
    Evaluates reset_protection(old).
  • (5.3)
    Assigns the value of src.load(memory_order​::​acquire) to ptr.
  • (5.4)
    If old == ptr is false, evaluates reset_protection().
6
#
Returns: old == ptr.
🔗
template<class T> void reset_protection(const T* ptr) noexcept;
7
#
Mandates: T is a hazard-protectable type.
8
#
Preconditions: *this is not empty.
9
#
Effects: If ptr is a null pointer value, invokes reset_protection().
Otherwise, associates the hazard pointer owned by *this with *ptr, thereby ending the current protection epoch.
10
#
Complexity: Constant.
🔗
void reset_protection(nullptr_t = nullptr) noexcept;
11
#
Preconditions: *this is not empty.
12
#
Postconditions: The hazard pointer owned by *this is unassociated.
13
#
Complexity: Constant.
🔗
void swap(hazard_pointer& other) noexcept;
14
#
Effects: Swaps the hazard pointer ownership of this object with that of other.
[Note 1: 
The owned hazard pointers, if any, remain unchanged during the swap and continue to be associated with the respective objects that they were protecting before the swap, if any.
No protection epochs are ended or initiated.
— end note]
15
#
Complexity: Constant.

33.11.3.4.4 Non-member functions [saferecl.hp.holder.nonmem]

🔗
hazard_pointer make_hazard_pointer();
1
#
Effects: Constructs a hazard pointer.
2
#
Returns: A hazard_pointer object that owns the newly-constructed hazard pointer.
3
#
Throws: May throw bad_alloc if memory for the hazard pointer could not be allocated.
🔗
void swap(hazard_pointer& a, hazard_pointer& b) noexcept;
4
#
Effects: Equivalent to a.swap(b).