pmem::obj::condition_variable Class Reference

Persistent memory resident condition variable. More...

`#include <libpmemobj++/condition_variable.hpp>`

## Public Types

typedef PMEMcond * | native_handle_type
| The handle typedef to the underlying basic type. More...

## Public Member Functions

| condition_variable ()
| Default constructor. More...
| ~condition_variable ()=default
| Defaulted destructor.
void | notify_one ()
| Notify and unblock one thread waiting on `*this` condition. More...
void | notify_all ()
| Notify and unblock all threads waiting on `*this` condition. More...
void | wait (mutex &lock)
| Makes the current thread block until the condition variable is notified or it is woken up by some other measure. More...
template<typename Lock >
void | wait (Lock &lock)
| Makes the current thread block until the condition variable is notified or it is woken up by some other measure. More...
template<typename Predicate >
void | wait (mutex &lock, Predicate pred)
| Makes the current thread block until the condition variable is notified. More...
template<typename Lock , typename Predicate >
void | wait (Lock &lock, Predicate pred)
| Makes the current thread block until the condition variable is notified. More...
template<typename Clock , typename Duration >
std::cv_status | wait_until (mutex &lock, const std::chrono::time_point< Clock, Duration > &timeout)
| Makes the current thread block until the condition variable is notified, a specific time is reached or it is woken up by some other measure. More...
template<typename Lock , typename Clock , typename Duration >
std::cv_status | wait_until (Lock &lock, const std::chrono::time_point< Clock, Duration > &timeout)
| Makes the current thread block until the condition variable is notified, a specific time is reached or it is woken up by some other measure. More...
template<typename Clock , typename Duration , typename Predicate >
bool | wait_until (mutex &lock, const std::chrono::time_point< Clock, Duration > &timeout, Predicate pred)
| Makes the current thread block until the condition variable is notified or a specific time is reached. More...
template<typename Lock , typename Clock , typename Duration , typename Predicate >
bool | wait_until (Lock &lock, const std::chrono::time_point< Clock, Duration > &timeout, Predicate pred)
| Makes the current thread block until the condition variable is notified or a specific time is reached. More...
template<typename Lock , typename Rep , typename Period >
std::cv_status | wait_for (Lock &lock, const std::chrono::duration< Rep, Period > &rel_time)
| Makes the current thread block until the condition variable is notified, the specified amount of time passes or it is woken up by some other measure. More...
template<typename Lock , typename Rep , typename Period , typename Predicate >
bool | wait_for (Lock &lock, const std::chrono::duration< Rep, Period > &rel_time, Predicate pred)
| Makes the current thread block until the condition variable is notified or the specified amount of time passes. More...
template<typename Rep , typename Period >
std::cv_status | wait_for (mutex &lock, const std::chrono::duration< Rep, Period > &rel_time)
| Makes the current thread block until the condition variable is notified, the specified amount of time passes or it is woken up by some other measure. More...
template<typename Rep , typename Period , typename Predicate >
bool | wait_for (mutex &lock, const std::chrono::duration< Rep, Period > &rel_time, Predicate pred)
| Makes the current thread block until the condition variable is notified or the specified amount of time passes. More...
native_handle_type | native_handle () noexcept
| Access a native handle to this condition variable. More...
condition_variable & | operator= (const condition_variable &)=delete
| Deleted assignment operator.
| condition_variable (const condition_variable &)=delete
| Deleted copy constructor.

## Private Member Functions

void | wait_impl (mutex &lock)
| Internal implementation of the wait call.
template<typename Predicate >
void | wait_impl (mutex &lock, Predicate pred)
| Internal implementation of the wait call.
template<typename Clock , typename Duration >
std::cv_status | wait_until_impl (mutex &lock, const std::chrono::time_point< Clock, Duration > &abs_timeout)
| Internal implementation of the wait_until call.
template<typename Clock , typename Duration , typename Predicate >
bool | wait_until_impl (mutex &lock, const std::chrono::time_point< Clock, Duration > &abs_timeout, Predicate pred)
| Internal implementation of the wait_until call.

## Private Attributes

PMEMcond | pcond
| A POSIX style PMEM-resident condition variable. More...

## Detailed Description

Persistent memory resident condition variable.

This class is an implementation of a PMEM-resident condition variable which mimics in behavior the C++11 std::condition_variable. The typical usage example would be:

#include <libpmemobj++/condition_variable.hpp>
#include <libpmemobj++/mutex.hpp>
#include <libpmemobj++/persistent_ptr.hpp>
#include <libpmemobj++/pool.hpp>
#include <mutex>
#include <thread>
namespace nvobj = pmem::obj;
void
cond_var_example()
{
// pool root structure
struct root {
nvobj::mutex pmutex;
nvobj::condition_variable cond;
int counter;
};
// create a pmemobj pool
auto pop = nvobj::pool<root>::create("poolfile", "layout",
PMEMOBJ_MIN_POOL);
auto proot = pop.get_root();
// run worker to bump up the counter
std::thread worker([&] {
std::unique_lock<nvobj::mutex> lock(proot->pmutex);
while (proot->counter < 1000)
++proot->counter;
// unlock before notifying to avoid blocking on waiting thread
lock.unlock();
// notify the waiting thread
proot->cond.notify_one();
});
std::unique_lock<nvobj::mutex> lock(proot->pmutex);
// wait on condition variable
proot->cond.wait(lock, [&] { return proot->counter >= 1000; });
worker.join();
}

## Member Typedef Documentation

## native_handle_type

typedef PMEMcond* pmem::obj::condition_variable::native_handle_type

The handle typedef to the underlying basic type.

## Constructor & Destructor Documentation

## condition_variable()

pmem::obj::condition_variable::condition_variable | ( |  | ) |

inline

Default constructor.

Exceptions

  lock_error | when the condition_variable is not from persistent memory.

## Member Function Documentation

## native_handle()

native_handle_type pmem::obj::condition_variable::native_handle | ( |  | ) |

inline noexcept

Access a native handle to this condition variable.

Returns
  a pointer to PMEMcond.

## notify_all()

void pmem::obj::condition_variable::notify_all | ( |  | ) |

inline

Notify and unblock all threads waiting on `*this` condition.

Does nothing when no threads are waiting.

## notify_one()

void pmem::obj::condition_variable::notify_one | ( |  | ) |

inline

Notify and unblock one thread waiting on `*this` condition.

Does nothing when no threads are waiting. It is unspecified which thread is selected for unblocking.

Exceptions

  lock_error | when the signal fails on the pcond.

## wait() [1/4]

void pmem::obj::condition_variable::wait | ( | mutex & | lock | ) |

inline

Makes the current thread block until the condition variable is notified or it is woken up by some other measure.

This releases the lock, blocks the current thread and adds it to the list of threads waiting on `*this` condition variable. The lock needs to be acquired and owned by the calling thread. The lock is automatically reacquired after the call to wait.

Parameters

  [in,out] | lock | a PMEM-resident obj::mutex.

Exceptions

  lock_error | when unlocking the lock or waiting on pcond fails.

## wait() [2/4]

template<typename Lock >

void pmem::obj::condition_variable::wait | ( | Lock & | lock | ) |

inline

Makes the current thread block until the condition variable is notified or it is woken up by some other measure.

This releases the lock, blocks the current thread and adds it to the list of threads waiting on `*this` condition variable. The lock needs to be acquired and owned by the calling thread. The lock is automatically reacquired after the call to wait.

Parameters

  [in,out] | lock | a Lock object which meets the BasicLockableConcept. Needs to be based on a PMEM-resident obj::mutex.

Exceptions

  lock_error | when unlocking the lock or waiting on pcond fails.

## wait() [3/4]

template<typename Predicate >

void pmem::obj::condition_variable::wait | ( | mutex & | lock,
|  | Predicate | pred
| ) |  |

inline

Makes the current thread block until the condition variable is notified.

This releases the lock, blocks the current thread and adds it to the list of threads waiting on `*this` condition variable. The lock needs to be acquired and owned by the calling thread. The lock is automatically reacquired after the call to wait. This version is immune to spurious wake ups due to the provided predicate.

Parameters

  [in,out] | lock | a PMEM-resident obj::mutex.
  [in] | pred | predicate which returns `false` if waiting is to be continued.

Exceptions

  lock_error | when unlocking the lock or waiting on pcond fails.

## wait() [4/4]

template<typename Lock , typename Predicate >

void pmem::obj::condition_variable::wait | ( | Lock & | lock,
|  | Predicate | pred
| ) |  |

inline

Makes the current thread block until the condition variable is notified.

This releases the lock, blocks the current thread and adds it to the list of threads waiting on `*this` condition variable. The lock needs to be acquired and owned by the calling thread. The lock is automatically reacquired after the call to wait. This version is immune to spurious wake ups due to the provided predicate.

Parameters

  [in,out] | lock | a Lock object which meets the BasicLockableConcept. Needs to be based on a PMEM-resident obj::mutex.
  [in] | pred | predicate which returns `false` if waiting is to be continued.

Exceptions

  lock_error | when unlocking the lock or waiting on pcond fails.

## wait_for() [1/4]

template<typename Lock , typename Rep , typename Period >

std::cv_status pmem::obj::condition_variable::wait_for | ( | Lock & | lock,
|  | const std::chrono::duration< Rep, Period > & | rel_time
| ) |  |

inline

Makes the current thread block until the condition variable is notified, the specified amount of time passes or it is woken up by some other measure.

This releases the lock, blocks the current thread and adds it to the list of threads waiting on `*this` condition variable. The lock needs to be acquired and owned by the calling thread. The lock is automatically reacquired after the call to wait.

Parameters

  [in,out] | lock | a Lock object which meets the BasicLockableConcept. Needs to be based on a PMEM-resident obj::mutex.
  [in] | rel_time | a specific duration, which when expired unblocks the thread.

Returns
  std::cv_status::timeout on timeout, std::cv_status::no_timeout otherwise.

Exceptions

  lock_error | when unlocking the lock or waiting on pcond fails.

## wait_for() [2/4]

template<typename Lock , typename Rep , typename Period , typename Predicate >

bool pmem::obj::condition_variable::wait_for | ( | Lock & | lock,
|  | const std::chrono::duration< Rep, Period > & | rel_time,
|  | Predicate | pred
| ) |  |

inline

Makes the current thread block until the condition variable is notified or the specified amount of time passes.

This releases the lock, blocks the current thread and adds it to the list of threads waiting on `*this` condition variable. The lock needs to be acquired and owned by the calling thread. The lock is automatically reacquired after the call to wait.

Parameters

  [in,out] | lock | a Lock object which meets the BasicLockableConcept. Needs to be based on a PMEM-resident obj::mutex.
  [in] | rel_time | a specific duration, which when expired unblocks the thread.
  [in] | pred | predicate which returns `false` if waiting is to be continued.

Returns
  `false` if pred evaluates to `false` after timeout expired, otherwise `true`.

Exceptions

  lock_error | when unlocking the lock or waiting on pcond fails.

## wait_for() [3/4]

template<typename Rep , typename Period >

std::cv_status pmem::obj::condition_variable::wait_for | ( | mutex & | lock,
|  | const std::chrono::duration< Rep, Period > & | rel_time
| ) |  |

inline

Makes the current thread block until the condition variable is notified, the specified amount of time passes or it is woken up by some other measure.

This releases the lock, blocks the current thread and adds it to the list of threads waiting on `*this` condition variable. The lock needs to be acquired and owned by the calling thread. The lock is automatically reacquired after the call to wait.

Parameters

  [in,out] | lock | a PMEM-resident obj::mutex.
  [in] | rel_time | a specific duration, which when expired unblocks the thread.

Returns
  std::cv_status::timeout on timeout, std::cv_status::no_timeout otherwise.

Exceptions

  lock_error | when unlocking the lock or waiting on pcond fails.

## wait_for() [4/4]

template<typename Rep , typename Period , typename Predicate >

bool pmem::obj::condition_variable::wait_for | ( | mutex & | lock,
|  | const std::chrono::duration< Rep, Period > & | rel_time,
|  | Predicate | pred
| ) |  |

inline

Makes the current thread block until the condition variable is notified or the specified amount of time passes.

This releases the lock, blocks the current thread and adds it to the list of threads waiting on `*this` condition variable. The lock needs to be acquired and owned by the calling thread. The lock is automatically reacquired after the call to wait.

Parameters

  [in,out] | lock | a PMEM-resident obj::mutex.
  [in] | rel_time | a specific duration, which when expired unblocks the thread.
  [in] | pred | predicate which returns `false` if waiting is to be continued.

Returns
  `false` if pred evaluates to `false` after timeout expired, otherwise `true`.

Exceptions

  lock_error | when unlocking the lock or waiting on pcond fails.

## wait_until() [1/4]

template<typename Clock , typename Duration >

std::cv_status pmem::obj::condition_variable::wait_until | ( | mutex & | lock,
|  | const std::chrono::time_point< Clock, Duration > & | timeout
| ) |  |

inline

Makes the current thread block until the condition variable is notified, a specific time is reached or it is woken up by some other measure.

This releases the lock, blocks the current thread and adds it to the list of threads waiting on `*this` condition variable. The lock needs to be acquired and owned by the calling thread. The lock is automatically reacquired after the call to wait.

Parameters

  [in,out] | lock | a PMEM-resident obj::mutex.
  [in] | timeout | a specific point in time, which when reached unblocks the thread.

Returns
  std::cv_status::timeout on timeout, std::cv_status::no_timeout otherwise.

Exceptions

  lock_error | when unlocking the lock or waiting on pcond fails.

## wait_until() [2/4]

template<typename Lock , typename Clock , typename Duration >

std::cv_status pmem::obj::condition_variable::wait_until | ( | Lock & | lock,
|  | const std::chrono::time_point< Clock, Duration > & | timeout
| ) |  |

inline

Makes the current thread block until the condition variable is notified, a specific time is reached or it is woken up by some other measure.

This releases the lock, blocks the current thread and adds it to the list of threads waiting on `*this` condition variable. The lock needs to be acquired and owned by the calling thread. The lock is automatically reacquired after the call to wait.

Parameters

  [in,out] | lock | a Lock object which meets the BasicLockableConcept. Needs to be based on a PMEM-resident obj::mutex.
  [in] | timeout | a specific point in time, which when reached unblocks the thread.

Returns
  std::cv_status::timeout on timeout, std::cv_status::no_timeout otherwise.

Exceptions

  lock_error | when unlocking the lock or waiting on pcond fails.

## wait_until() [3/4]

template<typename Clock , typename Duration , typename Predicate >

bool pmem::obj::condition_variable::wait_until | ( | mutex & | lock,
|  | const std::chrono::time_point< Clock, Duration > & | timeout,
|  | Predicate | pred
| ) |  |

inline

Makes the current thread block until the condition variable is notified or a specific time is reached.

This releases the lock, blocks the current thread and adds it to the list of threads waiting on `*this` condition variable. The lock needs to be acquired and owned by the calling thread. The lock is automatically reacquired after the call to wait.

Parameters

  [in,out] | lock | a PMEM-resident obj::mutex.
  [in] | timeout | a specific point in time, which when reached unblocks the thread.
  [in] | pred | predicate which returns `false` if waiting is to be continued.

Returns
  `false` if pred evaluates to `false` after timeout expired, otherwise `true`.

Exceptions

  lock_error | when unlocking the lock or waiting on pcond fails.

## wait_until() [4/4]

template<typename Lock , typename Clock , typename Duration , typename Predicate >

bool pmem::obj::condition_variable::wait_until | ( | Lock & | lock,
|  | const std::chrono::time_point< Clock, Duration > & | timeout,
|  | Predicate | pred
| ) |  |

inline

Makes the current thread block until the condition variable is notified or a specific time is reached.

This releases the lock, blocks the current thread and adds it to the list of threads waiting on `*this` condition variable. The lock needs to be acquired and owned by the calling thread. The lock is automatically reacquired after the call to wait.

Parameters

  [in,out] | lock | a Lock object which meets the BasicLockableConcept. Needs to be based on a PMEM-resident obj::mutex.
  [in] | timeout | a specific point in time, which when reached unblocks the thread.
  [in] | pred | predicate which returns `false` if waiting is to be continued.

Returns
  `false` if pred evaluates to `false` after timeout expired, otherwise `true`.

Exceptions

  lock_error | when unlocking the lock or waiting on pcond fails.

## Member Data Documentation

## pcond

PMEMcond pmem::obj::condition_variable::pcond

private

A POSIX style PMEM-resident condition variable.

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

- pmdk-1.4.1/src/include/libpmemobj++/condition_variable.hpp