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_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.

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.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_error when 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_error when 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] 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() [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]	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() [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] lock a PMEM-resident obj::mutex.

Exceptions

lock_error when 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]	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_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 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() [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]	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.

◆ 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]	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() [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]	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.

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

libpmemobj++/condition_variable.hpp

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ condition_variable()

Member Function Documentation

◆ native_handle()

◆ notify_all()

◆ notify_one()

◆ wait() [1/4]

◆ wait() [2/4]

◆ wait() [3/4]

◆ wait() [4/4]

◆ wait_for() [1/4]

◆ wait_for() [2/4]

◆ wait_for() [3/4]

◆ wait_for() [4/4]

◆ wait_until() [1/4]

◆ wait_until() [2/4]

◆ wait_until() [3/4]

◆ wait_until() [4/4]