Boost C++ Libraries Home Libraries People FAQ More

PrevUpHomeNext

Mutex Concepts

BasicLockable Concept
m.lock();
m.unlock();
is_basic_lockable trait -- EXTENSION
Lockable Concept
m.try_lock()
is_lockable trait -- EXTENSION
Recursive Lockable Concept
is_recursive_mutex_sur_parole trait -- EXTENSION
is_recursive_basic_lockable trait -- EXTENSION
is_recursive_lockable trait -- EXTENSION
TimedLockable Concept
m.try_lock_until(abs_time)
m.try_lock_for(rel_time)
m.timed_lock(abs_time)
m.timed_lock(rel_time)
SharedLockable Concept -- C++14
m.lock_shared()
m.try_lock_shared()
m.try_lock_shared_for(rel_time)
m.try_lock_shared_until(abs_time))
m.unlock_shared()
m.timed_lock_shared(abs_time)
UpgradeLockable Concept -- EXTENSION
m.lock_upgrade()
m.unlock_upgrade()
m.try_lock_upgrade()
m.try_lock_upgrade_for(rel_time)
m.try_lock_upgrade_until(abs_time)
m.try_unlock_shared_and_lock()
m.try_unlock_shared_and_lock_for(rel_time)
m.try_unlock_shared_and_lock_until(abs_time)
m.unlock_and_lock_shared()
m.try_unlock_shared_and_lock_upgrade()
m.try_unlock_shared_and_lock_upgrade_for(rel_time)
m.try_unlock_shared_and_lock_upgrade_until(abs_time)
m.unlock_and_lock_upgrade()
m.unlock_upgrade_and_lock()
m.try_unlock_upgrade_and_lock()
m.try_unlock_upgrade_and_lock_for(rel_time)
m.try_unlock_upgrade_and_lock_until(abs_time)
m.unlock_upgrade_and_lock_shared()

A mutex object facilitates protection against data races and allows thread-safe synchronization of data between threads. A thread obtains ownership of a mutex object by calling one of the lock functions and relinquishes ownership by calling the corresponding unlock function. Mutexes may be either recursive or non-recursive, and may grant simultaneous ownership to one or many threads. Boost.Thread supplies recursive and non-recursive mutexes with exclusive ownership semantics, along with a shared ownership (multiple-reader / single-writer) mutex.

Boost.Thread supports four basic concepts for lockable objects: Lockable, TimedLockable, SharedLockable and UpgradeLockable. Each mutex type implements one or more of these concepts, as do the various lock types.

// #include <boost/thread/lockable_concepts.hpp> 

namespace boost
{

  template<typename L>
  class BasicLockable; // EXTENSION
}

The BasicLockable concept models exclusive ownership. A type L meets the BasicLockable requirements if the following expressions are well-formed and have the specified semantics (m denotes a value of type L):

Lock ownership acquired through a call to lock() must be released through a call to unlock().

Requires:

The calling thread doesn't owns the mutex if the mutex is not recursive.

Effects:

The current thread blocks until ownership can be obtained for the current thread.

Synchronization:

Prior unlock() operations on the same object synchronizes with this operation.

Postcondition:

The current thread owns m.

Return type:

void.

Throws:

lock_error if an error occurs.

Error Conditions:

operation_not_permitted: if the thread does not have the privilege to perform the operation.

resource_deadlock_would_occur: if the implementation detects that a deadlock would occur.

device_or_resource_busy: if the mutex is already locked and blocking is not possible.

Thread safety:

If an exception is thrown then a lock shall not have been acquired for the current thread.

Requires:

The current thread owns m.

Synchronization:

This operation synchronizes with subsequent lock operations that obtain ownership on the same object.

Effects:

Releases a lock on m by the current thread.

Return type:

void.

Throws:

Nothing.

// #include <boost/thread/lockable_traits.hpp> 

namespace boost
{
  namespace sync
  {
    template<typename L>
    class is_basic_lockable;// EXTENSION
  }
}

Some of the algorithms on mutexes use this trait via SFINAE.

This trait is true_type if the parameter L meets the Lockable requirements.

[Warning] Warning

If BOOST_THREAD_NO_AUTO_DETECT_MUTEX_TYPES is defined you will need to specialize this traits for the models of BasicLockable you could build.

// #include <boost/thread/lockable_concepts.hpp> 
namespace boost
{
  template<typename L>
  class Lockable;
}

A type L meets the Lockable requirements if it meets the BasicLockable requirements and the following expressions are well-formed and have the specified semantics (m denotes a value of type L):

Lock ownership acquired through a call to try_lock() must be released through a call to unlock().

Requires:

The calling thread doesn't owns the mutex if the mutex is not recursive.

Effects:

Attempt to obtain ownership for the current thread without blocking.

Synchronization:

If try_lock() returns true, prior unlock() operations on the same object synchronize with this operation.

Note:

Since lock() does not synchronize with a failed subsequent try_lock(), the visibility rules are weak enough that little would be known about the state after a failure, even in the absence of spurious failures.

Return type:

bool.

Returns:

true if ownership was obtained for the current thread, false otherwise.

Postcondition:

If the call returns true, the current thread owns the m.

Throws:

Nothing.

// #include <boost/thread/lockable_traits.hpp> 
namespace boost
{
  namespace sync
  {
    template<typename L>
    class is_lockable;// EXTENSION
  }
}

Some of the algorithms on mutexes use this trait via SFINAE.

This trait is true_type if the parameter L meets the Lockable requirements.

[Warning] Warning

If BOOST_THREAD_NO_AUTO_DETECT_MUTEX_TYPES is defined you will need to specialize this traits for the models of Lockable you could build.

The user could require that the mutex passed to an algorithm is a recursive one. Whether a lockable is recursive or not can not be checked using template meta-programming. This is the motivation for the following trait.

// #include <boost/thread/lockable_traits.hpp> 

namespace boost
{
  namespace sync
  {
    template<typename L>
    class is_recursive_mutex_sur_parole: false_type; // EXTENSION
    template<>
    class is_recursive_mutex_sur_parole<recursive_mutex>: true_type; // EXTENSION
    template<>
    class is_recursive_mutex_sur_parole<timed_recursive_mutex>: true_type; // EXTENSION
  }
}

The trait is_recursive_mutex_sur_parole is false_type by default and is specialized for the provide recursive_mutex and timed_recursive_mutex.

It should be specialized by the user providing other model of recursive lockable.

// #include <boost/thread/lockable_traits.hpp> 
namespace boost
{
  namespace sync
  {
    template<typename L>
    class is_recursive_basic_lockable;// EXTENSION
  }
}

This traits is true_type if is_basic_lockable and is_recursive_mutex_sur_parole.

// #include <boost/thread/lockable_traits.hpp> 
namespace boost
{
  namespace sync
  {
    template<typename L>
    class is_recursive_lockable;// EXTENSION
  }
}

This traits is true_type if is_lockable and is_recursive_mutex_sur_parole.

// #include <boost/thread/lockable_concepts.hpp> 

namespace boost
{
  template<typename L>
  class TimedLockable; // EXTENSION
}

The TimedLockable concept refines the Lockable concept to add support for timeouts when trying to acquire the lock.

A type L meets the TimedLockable requirements if it meets the Lockable requirements and the following expressions are well-formed and have the specified semantics.

Variables:

  • m denotes a value of type L,
  • rel_time denotes a value of an instantiation of chrono::duration, and
  • abs_time denotes a value of an instantiation of chrono::time_point:

Expressions:

Lock ownership acquired through a call to try_lock_for or try_lock_until must be released through a call to unlock.

Requires:

The calling thread doesn't owns the mutex if the mutex is not recursive.

Effects:

Attempt to obtain ownership for the current thread. Blocks until ownership can be obtained, or the specified time is reached. If the specified time has already passed, behaves as try_lock().

Synchronization:

If try_lock_until() returns true, prior unlock() operations on the same object synchronize with this operation.

Return type:

bool.

Returns:

true if ownership was obtained for the current thread, false otherwise.

Postcondition:

If the call returns true, the current thread owns m.

Throws:

Nothing.

Requires:

The calling thread doesn't owns the mutex if the mutex is not recursive.

Effects:

As-if try_lock_until(chrono::steady_clock::now() + rel_time).

Synchronization:

If try_lock_for() returns true, prior unlock() operations on the same object synchronize with this operation.

[Warning] Warning

DEPRECATED since 4.00. The following expressions were required on version 2, but are now deprecated.

Use instead try_lock_for, try_lock_until.

Variables:

  • rel_time denotes a value of an instantiation of an unspecified DurationType arithmetic compatible with boost::system_time, and
  • abs_time denotes a value of an instantiation of boost::system_time:

Expressions:

Lock ownership acquired through a call to timed_lock() must be released through a call to unlock().

Effects:

Attempt to obtain ownership for the current thread. Blocks until ownership can be obtained, or the specified time is reached. If the specified time has already passed, behaves as try_lock().

Returns:

true if ownership was obtained for the current thread, false otherwise.

Postcondition:

If the call returns true, the current thread owns m.

Throws:

lock_error if an error occurs.

// #include <boost/thread/lockable_concepts.hpp> 

namespace boost
{
  template<typename L>
  class SharedLockable;  // C++14
}

The SharedLockable concept is a refinement of the TimedLockable concept that allows for shared ownership as well as exclusive ownership. This is the standard multiple-reader / single-write model: at most one thread can have exclusive ownership, and if any thread does have exclusive ownership, no other threads can have shared or exclusive ownership. Alternatively, many threads may have shared ownership.

A type L meets the SharedLockable requirements if it meets the TimedLockable requirements and the following expressions are well-formed and have the specified semantics.

Variables:

  • m denotes a value of type L,
  • rel_time denotes a value of an instantiation of chrono::duration, and
  • abs_time denotes a value of an instantiation of chrono::time_point:

Expressions:

Lock ownership acquired through a call to lock_shared(), try_lock_shared(), try_lock_shared_for or try_lock_shared_until must be released through a call to unlock_shared().

Effects:

The current thread blocks until shared ownership can be obtained for the current thread.

Postcondition:

The current thread has shared ownership of m.

Throws:

lock_error if an error occurs.

Effects:

Attempt to obtain shared ownership for the current thread without blocking.

Returns:

true if shared ownership was obtained for the current thread, false otherwise.

Postcondition:

If the call returns true, the current thread has shared ownership of m.

Throws:

lock_error if an error occurs.

Effects:

Attempt to obtain shared ownership for the current thread. Blocks until shared ownership can be obtained, or the specified duration is elapsed. If the specified duration is already elapsed, behaves as try_lock_shared().

Returns:

true if shared ownership was acquired for the current thread, false otherwise.

Postcondition:

If the call returns true, the current thread has shared ownership of m.

Throws:

lock_error if an error occurs.

Effects:

Attempt to obtain shared ownership for the current thread. Blocks until shared ownership can be obtained, or the specified time is reached. If the specified time has already passed, behaves as try_lock_shared().

Returns:

true if shared ownership was acquired for the current thread, false otherwise.

Postcondition:

If the call returns true, the current thread has shared ownership of m.

Throws:

lock_error if an error occurs.

Precondition:

The current thread has shared ownership of m.

Effects:

Releases shared ownership of m by the current thread.

Postcondition:

The current thread no longer has shared ownership of m.

Throws:

Nothing

[Warning] Warning

DEPRECATED since 3.00. The following expressions were required on version 2, but are now deprecated.

Use instead try_lock_shared_for, try_lock_shared_until.

Variables:

  • abs_time denotes a value of an instantiation of boost::system_time:

Expressions:

  • m.timed_lock_shared(abs_time);

Lock ownership acquired through a call to timed_lock_shared() must be released through a call to unlock_shared().

Effects:

Attempt to obtain shared ownership for the current thread. Blocks until shared ownership can be obtained, or the specified time is reached. If the specified time has already passed, behaves as try_lock_shared().

Returns:

true if shared ownership was acquired for the current thread, false otherwise.

Postcondition:

If the call returns true, the current thread has shared ownership of m.

Throws:

lock_error if an error occurs.

// #include <boost/thread/lockable_concepts.hpp> 

namespace boost
{
  template<typename L>
  class UpgradeLockable; // EXTENSION
}

The UpgradeLockable concept is a refinement of the SharedLockable concept that allows for upgradable ownership as well as shared ownership and exclusive ownership. This is an extension to the multiple-reader / single-write model provided by the SharedLockable concept: a single thread may have upgradable ownership at the same time as others have shared ownership. The thread with upgradable ownership may at any time attempt to upgrade that ownership to exclusive ownership. If no other threads have shared ownership, the upgrade is completed immediately, and the thread now has exclusive ownership, which must be relinquished by a call to unlock(), just as if it had been acquired by a call to lock().

If a thread with upgradable ownership tries to upgrade whilst other threads have shared ownership, the attempt will fail and the thread will block until exclusive ownership can be acquired.

Ownership can also be downgraded as well as upgraded: exclusive ownership of an implementation of the UpgradeLockable concept can be downgraded to upgradable ownership or shared ownership, and upgradable ownership can be downgraded to plain shared ownership.

A type L meets the UpgradeLockable requirements if it meets the SharedLockable requirements and the following expressions are well-formed and have the specified semantics.

Variables:

  • m denotes a value of type L,
  • rel_time denotes a value of an instantiation of chrono::duration, and
  • abs_time denotes a value of an instantiation of chrono::time_point:

Expressions:

If `BOOST_THREAD_PROVIDES_SHARED_MUTEX_UPWARDS_CONVERSION is defined the following expressions are also required:

Lock ownership acquired through a call to lock_upgrade() must be released through a call to unlock_upgrade(). If the ownership type is changed through a call to one of the unlock_xxx_and_lock_yyy() functions, ownership must be released through a call to the unlock function corresponding to the new level of ownership.

Precondition:

The calling thread has no ownership of the mutex.

Effects:

The current thread blocks until upgrade ownership can be obtained for the current thread.

Postcondition:

The current thread has upgrade ownership of m.

Synchronization:

Prior unlock_upgrade() operations on the same object synchronize with this operation.

Throws:

lock_error if an error occurs.

Precondition:

The current thread has upgrade ownership of m.

Effects:

Releases upgrade ownership of m by the current thread.

Postcondition:

The current thread no longer has upgrade ownership of m.

Synchronization:

This operation synchronizes with subsequent lock operations that obtain ownership on the same object.

Throws:

Nothing

Precondition:

The calling thread has no ownership of the mutex.

Effects:

Attempts to obtain upgrade ownership of the mutex for the calling thread without blocking. If upgrade ownership is not obtained, there is no effect and try_lock_upgrade() immediately returns.

Returns:

true if upgrade ownership was acquired for the current thread, false otherwise.

Postcondition:

If the call returns true, the current thread has upgrade ownership of m.

Synchronization:

If try_lock_upgrade() returns true, prior unlock_upgrade() operations on the same object synchronize with this operation.

Throws:

Nothing

Precondition:

The calling thread has no ownership of the mutex.

Effects:

If the tick period of rel_time is not exactly convertible to the native tick period, the duration shall be rounded up to the nearest native tick period. Attempts to obtain upgrade lock ownership for the calling thread within the relative timeout specified by rel_time. If the time specified by rel_time is less than or equal to rel_time.zero(), the function attempts to obtain ownership without blocking (as if by calling try_lock_upgrade()). The function returns within the timeout specified by rel_time only if it has obtained upgrade ownership of the mutex object.

Returns:

true if upgrade ownership was acquired for the current thread, false otherwise.

Postcondition:

If the call returns true, the current thread has upgrade ownership of m.

Synchronization:

If try_lock_upgrade_for(rel_time) returns true, prior unlock_upgrade() operations on the same object synchronize with this operation.

Throws:

Nothing

Notes:

Available only if BOOST_THREAD_PROVIDES_GENERIC_SHARED_MUTEX_ON_WIN is defined on Windows platform

Precondition:

The calling thread has no ownership of the mutex.

Effects:

The function attempts to obtain upgrade ownership of the mutex. If abs_time has already passed, the function attempts to obtain upgrade ownership without blocking (as if by calling try_lock_upgrade()). The function returns before the absolute timeout specified by abs_time only if it has obtained upgrade ownership of the mutex object.

Returns:

true if upgrade ownership was acquired for the current thread, false otherwise.

Postcondition:

If the call returns true, the current thread has upgrade ownership of m.

Synchronization:

If try_lock_upgrade_until(abs_time) returns true, prior unlock_upgrade() operations on the same object synchronize with this operation.

Throws:

Nothing

Notes:

Available only if BOOST_THREAD_PROVIDES_GENERIC_SHARED_MUTEX_ON_WIN is defined on Windows platform

Precondition:

The calling thread must hold a shared lock on the mutex.

Effects:

The function attempts to atomically convert the ownership from shared to exclusive for the calling thread without blocking. For this conversion to be successful, this thread must be the only thread holding any ownership of the lock. If the conversion is not successful, the shared ownership of m is retained.

Returns:

true if exclusive ownership was acquired for the current thread, false otherwise.

Postcondition:

If the call returns true, the current thread has exclusive ownership of m.

Synchronization:

If try_unlock_shared_and_lock() returns true, prior unlock() and subsequent lock operations on the same object synchronize with this operation.

Throws:

Nothing

Notes:

Available only if BOOST_THREAD_PROVIDES_SHARED_MUTEX_UPWARDS_CONVERSION and BOOST_THREAD_PROVIDES_GENERIC_SHARED_MUTEX_ON_WIN is defined on Windows platform

Precondition:

The calling thread shall hold a shared lock on the mutex.

Effects:

If the tick period of rel_time is not exactly convertible to the native tick period, the duration shall be rounded up to the nearest native tick period. The function attempts to atomically convert the ownership from shared to exclusive for the calling thread within the relative timeout specified by rel_time. If the time specified by rel_time is less than or equal to rel_time.zero(), the function attempts to obtain exclusive ownership without blocking (as if by calling try_unlock_shared_and_lock()). The function shall return within the timeout specified by rel_time only if it has obtained exclusive ownership of the mutex object. For this conversion to be successful, this thread must be the only thread holding any ownership of the lock at the moment of conversion. If the conversion is not successful, the shared ownership of the mutex is retained.

Returns:

true if exclusive ownership was acquired for the current thread, false otherwise.

Postcondition:

If the call returns true, the current thread has exclusive ownership of m.

Synchronization:

If try_unlock_shared_and_lock_for(rel_time) returns true, prior unlock() and subsequent lock operations on the same object synchronize with this operation.

Throws:

Nothing

Notes:

Available only if BOOST_THREAD_PROVIDES_SHARED_MUTEX_UPWARDS_CONVERSION and BOOST_THREAD_PROVIDES_GENERIC_SHARED_MUTEX_ON_WIN is defined on Windows platform

Precondition:

The calling thread shall hold a shared lock on the mutex.

Effects:

The function attempts to atomically convert the ownership from shared to exclusive for the calling thread within the absolute timeout specified by abs_time. If abs_time has already passed, the function attempts to obtain exclusive ownership without blocking (as if by calling try_unlock_shared_and_lock()). The function shall return before the absolute timeout specified by abs_time only if it has obtained exclusive ownership of the mutex object. For this conversion to be successful, this thread must be the only thread holding any ownership of the lock at the moment of conversion. If the conversion is not successful, the shared ownership of the mutex is retained.

Returns:

true if exclusive ownership was acquired for the current thread, false otherwise.

Postcondition:

If the call returns true, the current thread has exclusive ownership of m.

Synchronization:

If try_unlock_shared_and_lock_until(rel_time) returns true, prior unlock() and subsequent lock operations on the same object synchronize with this operation.

Throws:

Nothing

Notes:

Available only if BOOST_THREAD_PROVIDES_SHARED_MUTEX_UPWARDS_CONVERSION and BOOST_THREAD_PROVIDES_GENERIC_SHARED_MUTEX_ON_WIN is defined on Windows platform

Precondition:

The calling thread shall hold an exclusive lock on m.

Effects:

Atomically converts the ownership from exclusive to shared for the calling thread.

Postcondition:

The current thread has shared ownership of m.

Synchronization:

This operation synchronizes with subsequent lock operations that obtain ownership of the same object.

Throws:

Nothing

Precondition:

The calling thread shall hold a shared lock on the mutex.

Effects:

The function attempts to atomically convert the ownership from shared to upgrade for the calling thread without blocking. For this conversion to be successful, there must be no thread holding upgrade ownership of this object. If the conversion is not successful, the shared ownership of the mutex is retained.

Returns:

true if upgrade ownership was acquired for the current thread, false otherwise.

Postcondition:

If the call returns true, the current thread has upgrade ownership of m.

Synchronization:

If try_unlock_shared_and_lock_upgrade() returns true, prior unlock_upgrade() and subsequent lock operations on the same object synchronize with this operation.

Throws:

Nothing

Notes:

Available only if BOOST_THREAD_PROVIDES_SHARED_MUTEX_UPWARDS_CONVERSION and BOOST_THREAD_PROVIDES_GENERIC_SHARED_MUTEX_ON_WIN is defined on Windows platform

Precondition:

The calling thread shall hold a shared lock on the mutex.

Effects:

If the tick period of rel_time is not exactly convertible to the native tick period, the duration shall be rounded up to the nearest native tick period. The function attempts to atomically convert the ownership from shared to upgrade for the calling thread within the relative timeout specified by rel_time. If the time specified by rel_time is less than or equal to rel_time.zero(), the function attempts to obtain upgrade ownership without blocking (as if by calling try_unlock_shared_and_lock_upgrade()). The function shall return within the timeout specified by rel_time only if it has obtained exclusive ownership of the mutex object. For this conversion to be successful, there must be no thread holding upgrade ownership of this object at the moment of conversion. If the conversion is not successful, the shared ownership of m is retained.

Returns:

true if upgrade ownership was acquired for the current thread, false otherwise.

Postcondition:

If the call returns true, the current thread has upgrade ownership of m.

Synchronization:

If try_unlock_shared_and_lock_upgrade_for(rel_time) returns true, prior unlock_upgrade() and subsequent lock operations on the same object synchronize with this operation.

Throws:

Nothing

Notes:

Available only if BOOST_THREAD_PROVIDES_SHARED_MUTEX_UPWARDS_CONVERSION and BOOST_THREAD_PROVIDES_GENERIC_SHARED_MUTEX_ON_WIN is defined on Windows platform

Precondition:

The calling thread shall hold a shared lock on the mutex.

Effects:

The function attempts to atomically convert the ownership from shared to upgrade for the calling thread within the absolute timeout specified by abs_time. If abs_time has already passed, the function attempts to obtain upgrade ownership without blocking (as if by calling try_unlock_shared_and_lock_upgrade()). The function shall return before the absolute timeout specified by abs_time only if it has obtained upgrade ownership of the mutex object. For this conversion to be successful, there must be no thread holding upgrade ownership of this object at the moment of conversion. If the conversion is not successful, the shared ownership of the mutex is retained.

Returns:

true if upgrade ownership was acquired for the current thread, false otherwise.

Postcondition:

If the call returns true, the current thread has upgrade ownership of m.

Synchronization:

If try_unlock_shared_and_lock_upgrade_until(rel_time) returns true, prior unlock_upgrade() and subsequent lock operations on the same object synchronize with this operation.

Throws:

Nothing

Notes:

Available only if BOOST_THREAD_PROVIDES_SHARED_MUTEX_UPWARDS_CONVERSION and BOOST_THREAD_PROVIDES_GENERIC_SHARED_MUTEX_ON_WIN is defined on Windows platform

Precondition:

The current thread has exclusive ownership of m.

Effects:

Atomically releases exclusive ownership of m by the current thread and acquires upgrade ownership of m without blocking.

Postcondition:

The current thread has upgrade ownership of m.

Synchronization:

This operation synchronizes with subsequent lock operations that obtain ownership of the same object.

Throws:

Nothing

Precondition:

The current thread has upgrade ownership of m.

Effects:

Atomically releases upgrade ownership of m by the current thread and acquires exclusive ownership of m. If any other threads have shared ownership, blocks until exclusive ownership can be acquired.

Postcondition:

The current thread has exclusive ownership of m.

Synchronization:

This operation synchronizes with prior unlock_shared()() and subsequent lock operations that obtain ownership of the same object.

Throws:

Nothing

Precondition:

The calling thread shall hold an upgrade lock on the mutex.

Effects:

The function attempts to atomically convert the ownership from upgrade to exclusive for the calling thread without blocking. For this conversion to be successful, this thread must be the only thread holding any ownership of the lock. If the conversion is not successful, the upgrade ownership of m is retained.

Returns:

true if exclusive ownership was acquired for the current thread, false otherwise.

Postcondition:

If the call returns true, the current thread has exclusive ownership of m.

Synchronization:

If try_unlock_upgrade_and_lock() returns true, prior unlock() and subsequent lock operations on the same object synchronize with this operation.

Throws:

Nothing

Notes:

Available only if BOOST_THREAD_PROVIDES_GENERIC_SHARED_MUTEX_ON_WIN is defined on Windows platform

Precondition:

The calling thread shall hold an upgrade lock on the mutex.

Effects:

If the tick period of rel_time is not exactly convertible to the native tick period, the duration shall be rounded up to the nearest native tick period. The function attempts to atomically convert the ownership from upgrade to exclusive for the calling thread within the relative timeout specified by rel_time. If the time specified by rel_time is less than or equal to rel_time.zero(), the function attempts to obtain exclusive ownership without blocking (as if by calling try_unlock_upgrade_and_lock()). The function shall return within the timeout specified by rel_time only if it has obtained exclusive ownership of the mutex object. For this conversion to be successful, this thread shall be the only thread holding any ownership of the lock at the moment of conversion. If the conversion is not successful, the upgrade ownership of m is retained.

Returns:

true if exclusive ownership was acquired for the current thread, false otherwise.

Postcondition:

If the call returns true, the current thread has exclusive ownership of m.

Synchronization:

If try_unlock_upgrade_and_lock_for(rel_time) returns true, prior unlock() and subsequent lock operations on the same object synchronize with this operation.

Throws:

Nothing

Notes:

Available only if BOOST_THREAD_PROVIDES_GENERIC_SHARED_MUTEX_ON_WIN is defined on Windows platform

Precondition:

The calling thread shall hold an upgrade lock on the mutex.

Effects:

The function attempts to atomically convert the ownership from upgrade to exclusive for the calling thread within the absolute timeout specified by abs_time. If abs_time has already passed, the function attempts to obtain exclusive ownership without blocking (as if by calling try_unlock_upgrade_and_lock()). The function shall return before the absolute timeout specified by abs_time only if it has obtained exclusive ownership of the mutex object. For this conversion to be successful, this thread shall be the only thread holding any ownership of the lock at the moment of conversion. If the conversion is not successful, the upgrade ownership of m is retained.

Returns:

true if exclusive ownership was acquired for the current thread, false otherwise.

Postcondition:

If the call returns true, the current thread has exclusive ownership of m.

Synchronization:

If try_unlock_upgrade_and_lock_for(rel_time) returns true, prior unlock() and subsequent lock operations on the same object synchronize with this operation.

Throws:

Nothing

Notes:

Available only if BOOST_THREAD_PROVIDES_GENERIC_SHARED_MUTEX_ON_WIN is defined on Windows platform

Precondition:

The current thread has upgrade ownership of m.

Effects:

Atomically releases upgrade ownership of m by the current thread and acquires shared ownership of m without blocking.

Postcondition:

The current thread has shared ownership of m.

Synchronization:

This operation synchronizes with prior unlock_shared() and subsequent lock operations that obtain ownership of the same object.

Throws:

Nothing


PrevUpHomeNext