PMDK C++ bindings  1.12.1-rc1
This is the C++ bindings documentation for PMDK's libpmemobj.
Public Types | Public Member Functions | Private Member Functions | Private Attributes | List of all members
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.
 

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_variableoperator= (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.
 

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 <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.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();
}

Constructor & Destructor Documentation

◆ condition_variable()

pmem::obj::condition_variable::condition_variable ( )
inline

Default constructor.

Exceptions
lock_errorwhen the condition_variable is not from persistent memory.

Member Function Documentation

◆ native_handle()

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

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_errorwhen the signal fails on the pcond.

◆ wait() [1/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]locka Lock object which meets the BasicLockableConcept. Needs to be based on a PMEM-resident obj::mutex.
Exceptions
lock_errorwhen unlocking the lock or waiting on pcond fails.

◆ wait() [2/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]locka Lock object which meets the BasicLockableConcept. Needs to be based on a PMEM-resident obj::mutex.
[in]predpredicate which returns false if waiting is to be continued.
Exceptions
lock_errorwhen unlocking the lock or waiting on pcond fails.

◆ wait() [3/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]locka PMEM-resident obj::mutex.
Exceptions
lock_errorwhen unlocking the lock or waiting on pcond fails.

◆ wait() [4/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]locka PMEM-resident obj::mutex.
[in]predpredicate which returns false if waiting is to be continued.
Exceptions
lock_errorwhen 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]locka Lock object which meets the BasicLockableConcept. Needs to be based on a PMEM-resident obj::mutex.
[in]rel_timea specific duration, which when expired unblocks the thread.
Returns
std::cv_status::timeout on timeout, std::cv_status::no_timeout otherwise.
Exceptions
lock_errorwhen 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]locka Lock object which meets the BasicLockableConcept. Needs to be based on a PMEM-resident obj::mutex.
[in]rel_timea specific duration, which when expired unblocks the thread.
[in]predpredicate which returns false if waiting is to be continued.
Returns
false if pred evaluates to false after timeout expired, otherwise true.
Exceptions
lock_errorwhen 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]locka PMEM-resident obj::mutex.
[in]rel_timea specific duration, which when expired unblocks the thread.
Returns
std::cv_status::timeout on timeout, std::cv_status::no_timeout otherwise.
Exceptions
lock_errorwhen 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]locka PMEM-resident obj::mutex.
[in]rel_timea specific duration, which when expired unblocks the thread.
[in]predpredicate which returns false if waiting is to be continued.
Returns
false if pred evaluates to false after timeout expired, otherwise true.
Exceptions
lock_errorwhen unlocking the lock or waiting on pcond fails.

◆ wait_until() [1/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]locka Lock object which meets the BasicLockableConcept. Needs to be based on a PMEM-resident obj::mutex.
[in]timeouta 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_errorwhen unlocking the lock or waiting on pcond fails.

◆ wait_until() [2/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]locka Lock object which meets the BasicLockableConcept. Needs to be based on a PMEM-resident obj::mutex.
[in]timeouta specific point in time, which when reached unblocks the thread.
[in]predpredicate which returns false if waiting is to be continued.
Returns
false if pred evaluates to false after timeout expired, otherwise true.
Exceptions
lock_errorwhen unlocking the lock or waiting on pcond fails.

◆ wait_until() [3/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]locka PMEM-resident obj::mutex.
[in]timeouta 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_errorwhen unlocking the lock or waiting on pcond fails.

◆ wait_until() [4/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]locka PMEM-resident obj::mutex.
[in]timeouta specific point in time, which when reached unblocks the thread.
[in]predpredicate which returns false if waiting is to be continued.
Returns
false if pred evaluates to false after timeout expired, otherwise true.
Exceptions
lock_errorwhen unlocking the lock or waiting on pcond fails.

The documentation for this class was generated from the following file:
pmem::obj::pool::root
persistent_ptr< T > root()
Retrieves pool's root object.
Definition: pool.hpp:627
pool.hpp
C++ pmemobj pool.
pmem::obj
Main libpmemobj namespace.
Definition: allocation_flag.hpp:18
condition_variable.hpp
Pmem-resident condition variable.
persistent_ptr.hpp
Persistent smart pointer.
mutex.hpp
Pmem-resident mutex.