xtd::threading::mutex Class Reference

Inheritance diagram for xtd::threading::mutex:

Definition

A synchronization primitive that can also be used for interprocess synchronization.

class mutex : public xtd::threading::wait_handle, public icomparable<mutex>, public xtd::iequatable<mutex>

Header

#include <xtd/threading/mutex>

Namespace

xtd::threading

Library

xtd.core

Remarks

When two or more threads need to access a shared resource at the same time, the system needs a synchronization mechanism to ensure that only one thread at a time uses the resource. xtd::threading::mutex is a synchronization primitive that grants exclusive access to the shared resource to only one thread. If a thread acquires a mutex, the second thread that wants to acquire that mutex is suspended until the first thread releases the mutex.

You can use the xtd::threading::wait_handle::wait_one method to request ownership of a mutex. The calling thread blocks until one of the following occurs:

• The mutex is signaled to indicate that it is not owned. When this happens, the xtd::threading::wait_handle::wait_one method returns true, and the calling thread assumes ownership of the mutex and accesses the resource protected by the mutex. When it has finished accessing the resource, the thread must call the xtd::threading::mutex::release_mutex method to release ownership of the mutex. The first example in the Examples section illustrates this pattern.
• The time-out interval specified in the call to a xtd::threading::wait_handle::wait_one method that has a

  milliseconds_timeout 

  or timeout parameter has elapsed. When this happens, the xtd::threading::wait_handle::wait_one method returns false, and the calling thread makes no further attempt to acquire ownership of the mutex. In this case, you should structure your code so that access to the resource that is protected by the mutex is denied to the calling thread. Because the thread never acquired ownership of the mutex, it must not call the xtd::threading::mutex::release_mutex method. The second example in the Examples section illustrates this pattern.

The xtd::threading::mutex class enforces thread identity, so a mutex can be released only by the thread that acquired it. By contrast, the xtd::threading::semaphore class does not enforce thread identity. A mutex can also be passed across application domain boundaries.

The thread that owns a mutex can request the same mutex in repeated calls to xtd::threading::wait_handle::wait_one without blocking its execution. However, the thread must call the xtd::threading::mutex::release_mutex method the same number of times to release ownership of the mutex.

Because the xtd::threading::mutex class inherits from xtd::threading::wait_handle, you can also call the static xtd::threading::wait_handle::wait_all and xtd::threading::wait_handle::wait_any methods to synchronize access to a protected resource.

If a thread terminates while owning a mutex, the mutex is said to be abandoned. The state of the mutex is set to signaled, and the next waiting thread gets ownership. An xtd::threading::abandoned_mutex_exception is thrown in the next thread that acquires the abandoned mutex.

Warning

An abandoned mutex often indicates a serious error in the code. When a thread exits without releasing the mutex, the data structures protected by the mutex might not be in a consistent state. The next thread to request ownership of the mutex can handle this exception and proceed, if the integrity of the data structures can be verified.

Remarks

In the case of a system-wide mutex, an abandoned mutex might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager).

Mutexes are of two types: local mutexes, which are unnamed, and named system mutexes. A local mutex exists only within your process. It can be used by any thread in your process that has a reference to the xtd::threading::mutex object that represents the mutex. Each unnamed xtd::threading::mutex object represents a separate local mutex.

Named system mutexes are visible throughout the operating system, and can be used to synchronize the activities of processes. You can create a xtd::threading::mutex object that represents a named system mutex by using a constructor that accepts a name. The operating-system object can be created at the same time, or it can exist before the creation of the xtd::threading::mutex object. You can create multiple xtd::threading::mutex objects that represent the same named system mutex, and you can use the xtd::threading::mutex::open_existing method to open an existing named system mutex.

Warning

The backslash () and slash(/) are a reserved character in a mutex name. Don't use a backslash () and slash (/) in a mutex name except as specified in the note on using mutexes in terminal server sessions. Otherwise, a xtd::io::directory_not_found_exception may be thrown, even though the name of the mutex represents an existing file.

Remarks

The unnamed mutex is a std::recursive_timed_mutex of C++17. You can therefore use xtd::threading::mutex or std::recursive_timed_mutex indifferently in your projects.

If you use other synchronization objects for your threads and you use xtd::threading::thread you are interested in using xtd::threading::mutex. You will also benefit from xtd::threading::wait_handle::wait_all and xtd::threading::wait_handle::wait_any among others to synchronize all your objects.

On the other hand, if you only use mutexes and you use std::thread then you are interested in using std::recursive_timed_mutex.

Examples

This example shows how a local xtd::threading::mutex object is used to synchronize access to a protected resource. Because each calling thread is blocked until it acquires ownership of the mutex, it must call the xtd::threading::mutex::release_mutex method to release ownership of the mutex.

#include <xtd/xtd>
 
namespace mutex_example {
  class program {
  public:
    static void main() {
      // Create the threads that will use the protected resource.
      for (auto i = 0; i < num_threads; ++i) {
        threads.add(thread {thread_proc});
        threads[threads.count() - 1].name(string::format("thread_{0}", i + 1));
        threads[threads.count() - 1].start();
      }
      
      thread::join_all(threads);
    }
    
    static void thread_proc() {
      for(auto i = 0; i < num_iterations; ++i)
        Use_resource();
    }
    
  private:
    // This method represents a resource that must be synchronized
    // so that only one thread at a time can enter.
    static void Use_resource() {
      // Wait until it is safe to enter.
      console::write_line("{0} is requesting the mutex",
                        thread::current_thread().name());
      mut.wait_one();
      
      console::write_line("{0} has entered the protected area",
                          thread::current_thread().name());
      
      // Place code to access non-reentrant resources here.
      
      // Simulate some work.
      thread::sleep(500);
      
      console::write_line("{0} is leaving the protected area",
                          thread::current_thread().name());
      
      // Release the mutex.
      mut.release_mutex();
      console::write_line("{0} has released the mutex",
                          thread::current_thread().name());
    }
 
    inline static list<thread> threads;
    // Create a new mutex. The creating thread does not own the mutex.
    inline static mutex mut;
    inline static constexpr int num_iterations = 1;
    inline static constexpr int num_threads = 3;
  };
}
 
startup_(mutex_example::program::main);
 
// This example produces output similar to the following:
//
// thread_1 is requesting the mutex
// thread_1 has entered the protected area
// thread_2 is requesting the mutex
// thread_3 is requesting the mutex
// thread_1 is leaving the protected area
// thread_1 has released the mutex
// thread_2 has entered the protected area
// thread_2 is leaving the protected area
// thread_2 has released the mutex
// thread_3 has entered the protected area
// thread_3 is leaving the protected area
// thread_3 has released the mutex

Public Aliases
using	native_handle_type
	Rpresents the native handle type.

Public Constructors
	mutex ()
	Initializes a new instance of the xtd::threading::mutex class with default properties.
	mutex (bool initially_owned)
	Initializes a new instance of the xtd::threading::mutex with a bool value that indicates whether the calling thread should have initial ownership of the mutex.
	mutex (const string &name)
	Initializes a new instance of the xtd::threading::mutex class with a string that is the name of the mutex.
	mutex (const string &name, bool &created_new)
	Initializes a new instance of the xtd::threading::mutex class with a string that is the name of the mutex, and a bool value that, when the method returns, indicates whether the calling thread was granted initial ownership of the mutex.
	mutex (bool initially_owned, const string &name)
	Initializes a new instance of the xtd::threading::mutex class with a bool value that indicates whether the calling thread should have initial ownership of the mutex, and a string that is the name of the mutex.
	mutex (bool initially_owned, const string &name, bool &created_new)
	Initializes a new instance of the xtd::threading::mutex class with a bool value that indicates whether the calling thread should have initial ownership of the mutex, a string that is the name of the mutex, and a bool value that, when the method returns, indicates whether the calling thread was granted initial ownership of the mutex.

Public Properties
intptr	handle () const noexcept override
	Gets the native operating system handle.
void	handle (intptr value) override
	Sets the native operating system handle.
native_handle_type	native_handle () const noexcept
	Returns the underlying implementation-defined native handle object.

Public Methods
void	close () override
	Releases all resources held by the current xtd::threading::wait_handle.
int32	compare_to (const mutex &value) const noexcept override
bool	equals (const object &obj) const noexcept override
	Determines whether the specified object is equal to the current object.
bool	equals (const mutex &other) const noexcept override
void	lock ()
	Locks the mutex. If another thread has already locked the mutex, a call to lock will block execution until the lock is acquired.
void	release_mutex ()
	Releases the Mutex once.
bool	try_lock () noexcept
	Tries to lock the mutex. Returns immediately. On successful lock acquisition returns true, otherwise returns false.
bool	try_lock_for (const time_span &timeout) noexcept
	Tries to lock the mutex. Blocks until specified timeout_duration has elapsed or the lock is acquired, whichever comes first. On successful lock acquisition returns true, otherwise returns false.
bool	try_lock_until (const date_time &timeout_time) noexcept
	Tries to lock the mutex. Blocks until specified timeout_time has been reached or the lock is acquired, whichever comes first. On successful lock acquisition returns true, otherwise returns false.
void	unlock ()
	Unlocks the mutex.

Public Static Methods
static mutex	open_existing (const string &name)
	Opens an existing named mutex.
static bool	try_open_existing (const string &name, mutex &result) noexcept
	Opens the specified named mutex, if it already exists, and returns a value that indicates whether the operation succeeded.

Protected Methods
bool	signal () override
	Releases ownership of the specified wait_handle object.
bool	wait (int32 milliseconds_timeout) override
	wait ownership of the specified mutex object.

Additional Inherited Members
static const intptr	invalid_handle
	Represents an invalid native operating system handle. This field is read-only.
static constexpr size_t	wait_timeout
	Indicates that a xtd::threading::wait_handle::wait_any operation timed out before any of the wait handles were signaled. This field is constant.
	wait_handle ()=default
	Initializes a new instance of the xtd::threading::wait_handle class.
virtual bool	wait_one ()
	Blocks the current thread until the current xtd::threading::wait_handle receives a signal.
virtual bool	wait_one (int32 milliseconds_timeout)
	Blocks the current thread until the current xtd::threading::wait_handle receives a signal, using 32-bit signed integer to measure the time interval.
virtual bool	wait_one (const time_span &timeout)
	Blocks the current thread until the current instance receives a signal, using a xtd::time_span to measure the time interval.
	object ()=default
	Create a new instance of the ultimate base class object.
virtual xtd::size	get_hash_code () const noexcept
	Serves as a hash function for a particular type.
virtual type_object	get_type () const noexcept
	Gets the type of the current instance.
template<class object_t>
xtd::unique_ptr_object< object_t >	memberwise_clone () const
	Creates a shallow copy of the current object.
virtual xtd::string	to_string () const noexcept
	Returns a xtd::string that represents the current object.
virtual int32	compare_to (const mutex &obj) const noexcept=0
	Compares the current instance with another object of the same type.
virtual bool	equals (const mutex &) const noexcept=0
	Indicates whether the current object is equal to another object of the same type.
static bool	signal_and_wait (wait_handle &to_signal, wait_handle &to_wait)
	Signals one xtd::threading::wait_handle and waits on another.
static bool	signal_and_wait (wait_handle &to_signal, wait_handle &to_wait, int32 milliseconds_timeout)
	Signals one xtd::threading::wait_handle and waits on another, specifying a time-out interval as a 32-bit signed integer.
static bool	signal_and_wait (wait_handle &to_signal, wait_handle &to_wait, const time_span &timeout)
	Signals one xtd::threading::wait_handle and waits on another, specifying a time-out interval as a time_span.
template<class collection_t>
static bool	wait_all (const collection_t &wait_handles)
	Waits for all the elements in the specified collection to receive a signal.
template<class collection_t>
static bool	wait_all (const collection_t &wait_handles, int32 milliseconds_timeout)
	Waits for all the elements in the specified collection to receive a signal, using an int32 value to measure the time interval.
template<class collection_t>
static bool	wait_all (const collection_t &wait_handles, const time_span &timeout)
	Waits for all the elements in the specified collection to receive a signal, using a xtd::time_span value to measure the time interval.
template<class collection_t>
static size_t	wait_any (const collection_t &wait_handles)
	Waits for any of the elements in the specified collection to receive a signal.
template<class collection_t>
static size_t	wait_any (const collection_t &wait_handles, int32 milliseconds_timeout)
	Waits for any of the elements in the specified collection to receive a signal, using a 32-bit signed integer to measure the time interval.
template<class collection_t>
static size_t	wait_any (const collection_t &wait_handles, const time_span &timeout)
	Waits for any of the elements in the specified collection to receive a signal, using a xtd::time_span to measure the time interval.
template<class object_a_t, class object_b_t>
static bool	equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are considered equal.
template<class object_a_t, class object_b_t>
static bool	reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are the same instance.
	abstract_object ()=default
	Initializes a new instance of the xtd::abstract_object class.

Member Typedef Documentation

native_handle_type

using xtd::threading::mutex::native_handle_type

Rpresents the native handle type.

Constructor & Destructor Documentation

mutex() [1/6]

xtd::threading::mutex::mutex

(

)

Initializes a new instance of the xtd::threading::mutex class with default properties.

Remarks

Calling this constructor overload is the same as calling the xtd::threading::mutex::mutex(bool) constructor overload and specifying false for initial ownership of the mutex. That is, the calling thread does not own the mutex.

mutex() [2/6]

xtd::threading::mutex::mutex ( bool initially_owned )

explicit

Initializes a new instance of the xtd::threading::mutex with a bool value that indicates whether the calling thread should have initial ownership of the mutex.

Parameters

initially_owned

true to give the calling thread initial ownership of the named system mutex if the named system mutex is created as a result of this call; otherwise, false.

mutex() [3/6]

xtd::threading::mutex::mutex ( const string & name )

explicit

Initializes a new instance of the xtd::threading::mutex class with a string that is the name of the mutex.

Parameters

name	The name, if the synchronization object is to be shared with other processes; otherwise, an empty string. The name is case-sensitive. The backslash character () and slsh (/) are reserved.

Exceptions

xtd::io::io_xception

name is invalid. This can be for various reasons, including some restrictions that may be placed by the operating system, such as an unknown prefix or invalid characters. Note that the name and common prefixes "Global\" and "Local" are case-sensitive. -or- There was some other error. The HResult property may provide more information.

Remarks

The initially owned is set to flase.

mutex() [4/6]

xtd::threading::mutex::mutex	(	const string &	name,
		bool &	created_new )

Initializes a new instance of the xtd::threading::mutex class with a string that is the name of the mutex, and a bool value that, when the method returns, indicates whether the calling thread was granted initial ownership of the mutex.

Parameters

name	The name, if the synchronization object is to be shared with other processes; otherwise, an empty string. The name is case-sensitive. The backslash character () and slsh (/) are reserved.
created_new	When this method returns, contains a bool that is true if a local mutex was created (that is, if name is empty string) or if the specified named system mutex was created; false if the specified named system mutex already existed.

Exceptions

xtd::io::io_xception

name is invalid. This can be for various reasons, including some restrictions that may be placed by the operating system, such as an unknown prefix or invalid characters. Note that the name and common prefixes "Global\" and "Local" are case-sensitive. -or- There was some other error. The HResult property may provide more information.

Remarks

The initially owned is set to flase.

mutex() [5/6]

xtd::threading::mutex::mutex	(	bool	initially_owned,
		const string &	name )

Initializes a new instance of the xtd::threading::mutex class with a bool value that indicates whether the calling thread should have initial ownership of the mutex, and a string that is the name of the mutex.

Parameters

initially_owned	true to give the calling thread initial ownership of the named system mutex if the named system mutex is created as a result of this call; otherwise, false.
name	The name, if the synchronization object is to be shared with other processes; otherwise, an empty string. The name is case-sensitive. The backslash character () and slsh (/) are reserved.

Exceptions

xtd::io::io_xception

name is invalid. This can be for various reasons, including some restrictions that may be placed by the operating system, such as an unknown prefix or invalid characters. Note that the name and common prefixes "Global\" and "Local" are case-sensitive. -or- There was some other error. The HResult property may provide more information.

mutex() [6/6]

xtd::threading::mutex::mutex	(	bool	initially_owned,
		const string &	name,
		bool &	created_new )

Initializes a new instance of the xtd::threading::mutex class with a bool value that indicates whether the calling thread should have initial ownership of the mutex, a string that is the name of the mutex, and a bool value that, when the method returns, indicates whether the calling thread was granted initial ownership of the mutex.

Parameters

initially_owned	true to give the calling thread initial ownership of the named system mutex if the named system mutex is created as a result of this call; otherwise, false.
name	The name, if the synchronization object is to be shared with other processes; otherwise, an empty string. The name is case-sensitive. The backslash character () and slsh (/) are reserved.
created_new	When this method returns, contains a bool that is true if a local mutex was created (that is, if name is empty string) or if the specified named system mutex was created; false if the specified named system mutex already existed.

Exceptions

xtd::io::io_xception

name is invalid. This can be for various reasons, including some restrictions that may be placed by the operating system, such as an unknown prefix or invalid characters. Note that the name and common prefixes "Global\" and "Local" are case-sensitive. -or- There was some other error. The HResult property may provide more information.

Member Function Documentation

handle() [1/2]

intptr xtd::threading::mutex::handle ( ) const

overridevirtualnoexcept

Gets the native operating system handle.

Returns

An intptr representing the native operating system handle.

Implements xtd::threading::wait_handle.

handle() [2/2]

void xtd::threading::mutex::handle ( intptr value )

overridevirtual

Sets the native operating system handle.

Parameters

value

An intptr representing the native operating system handle.

Implements xtd::threading::wait_handle.

native_handle()

native_handle_type xtd::threading::mutex::native_handle ( ) const

noexcept

Returns the underlying implementation-defined native handle object.

Returns

Implementation-defined native handle object.

close()

void xtd::threading::mutex::close ( )

overridevirtual

Releases all resources held by the current xtd::threading::wait_handle.

Remarks

You to call this method in the destructor of the inherited class.

Reimplemented from xtd::threading::wait_handle.

equals()

bool xtd::threading::mutex::equals ( const object & obj ) const

overridevirtualnoexcept

Determines whether the specified object is equal to the current object.

Parameters

obj	The object to compare with the current object.

Returns

true if the specified object is equal to the current object. otherwise, false.

Examples

The following code example compares the current instance with another object.

#include <xtd/xtd>
 
auto main() -> int {
  auto object1 = new_ptr<object>();
  auto object2 = new_ptr<object>();
  
  auto object3 = object2;
  console::write_line(object1->equals(*object3));
  console::write_line(*object1 == *object3);
  object3 = object1;
  console::write_line(object1->equals(*object3));
  console::write_line(*object1 == *object3);
}
 
// This code produces the following output :
//
// false
// false
// true
// true

Reimplemented from xtd::object.

lock()

void xtd::threading::mutex::lock

(

)

Locks the mutex. If another thread has already locked the mutex, a call to lock will block execution until the lock is acquired.

Remarks

If lock is called by a thread that already owns the mutex, the behavior is undefined: for example, the program may deadlock. An implementation that can detect the invalid usage is encouraged to throw a std::system_error with error condition resource_deadlock_would_occur instead of deadlocking.

Prior unlock() operations on the same mutex synchronize-with (as defined in std::memory_order) this operation.

Note

xtd::threading::mutex::lock() is usually not called directly: std::unique_lock, std::scoped_lock, and std::lock_guard are used to manage exclusive locking.

release_mutex()

void xtd::threading::mutex::release_mutex

(

)

Releases the Mutex once.

Exceptions

xtd::object_closed_exception

the handle is invalid

try_lock()

bool xtd::threading::mutex::try_lock ( )

noexcept

Tries to lock the mutex. Returns immediately. On successful lock acquisition returns true, otherwise returns false.

Parameters

timeout

timeout A xtd::time_span that represents the number of milliseconds to wait, or a xtd::time_span that represents -1 milliseconds to wait indefinitely.

Returns

true if the lock was acquired successfully, otherwise false.

Remarks

This function is allowed to fail spuriously and return false even if the mutex is not currently locked by any other thread.

If try_lock is called by a thread that already owns the mutex, the behavior is undefined.

Prior unlock() operation on the same mutex synchronizes-with (as defined in std::memory_order) this operation if it returns true. Note that prior lock() does not synchronize with this operation if it returns false.

try_lock_for()

bool xtd::threading::mutex::try_lock_for ( const time_span & timeout )

noexcept

Tries to lock the mutex. Blocks until specified timeout_duration has elapsed or the lock is acquired, whichever comes first. On successful lock acquisition returns true, otherwise returns false.

Parameters

timeout

minimum duration to block for

Returns

true if the lock was acquired successfully, otherwise false.

Remarks

If timeout_duration is less or equal timeout_duration.zero(), the function behaves like try_lock().

This function may block for longer than timeout_duration due to scheduling or resource contention delays.

The standard recommends that a steady_clock is used to measure the duration. If an implementation uses a system_clock instead, the wait time may also be sensitive to clock adjustments.

As with try_lock(), this function is allowed to fail spuriously and return false even if the mutex was not locked by any other thread at some point during timeout_duration.

Prior unlock() operation on the same mutex synchronizes-with (as defined in std::memory_order) this operation if it returns true.

If try_lock_for is called by a thread that already owns the mutex, the behavior is undefined.

try_lock_until()

bool xtd::threading::mutex::try_lock_until ( const date_time & timeout_time )

noexcept

Tries to lock the mutex. Blocks until specified timeout_time has been reached or the lock is acquired, whichever comes first. On successful lock acquisition returns true, otherwise returns false.

Parameters

timeout_time

maximum time point to block until

Returns

true if the lock was acquired successfully, otherwise false.

Remarks

If timeout_time has already passed, this function behaves like try_lock().

Clock must meet the Clock requirements. The program is ill-formed if std::chrono::is_clock_v<Clock> is false (since C++20).

The standard recommends that the clock tied to timeout_time be used, in which case adjustments of the clock may be taken into account. Thus, the duration of the block might be more or less than timeout_time - Clock::now() at the time of the call, depending on the direction of the adjustment and whether it is honored by the implementation. The function also may block until after timeout_time has been reached due to process scheduling or resource contention delays.

As with try_lock(), this function is allowed to fail spuriously and return false even if the mutex was not locked by any other thread at some point before timeout_time.

Prior unlock() operation on the same mutex synchronizes-with (as defined in std::memory_order) this operation if it returns true.

If try_lock_until is called by a thread that already owns the mutex, the behavior is undefined.

unlock()

void xtd::threading::mutex::unlock

(

)

Unlocks the mutex.

Remarks

The mutex must be locked by the current thread of execution, otherwise, the behavior is undefined.

This operation synchronizes-with (as defined in std::memory_order) any subsequent lock operation that obtains ownership of the same mutex.

xtd::threading::mutex::unlock() is usually not called directly: std::unique_lock and std::lock_guard are used to manage exclusive locking.

open_existing()

static mutex xtd::threading::mutex::open_existing ( const string & name )

static

Opens an existing named mutex.

Parameters

name	The name of a system-wide named mutex object.

Returns

A xtd::threading::mutex object that represents a named system mutex.

Exceptions

xtd::argument_exception	is a zero-length string -or- name is longer than 128 characters
xtd::io::io_exception	An Io error occurred.

try_open_existing()

static bool xtd::threading::mutex::try_open_existing ( const string & name, mutex & result )

staticnoexcept

Opens the specified named mutex, if it already exists, and returns a value that indicates whether the operation succeeded.

Parameters

name	The name of the synchronization object to be shared with other processes. The name is case-sensitive. The backslash character () and (/) are reserved.
result	When this method returns, contains a xtd::threading::mutex object that represents the named mutex if the call succeeded.

Returns

true if the named mutex was opened successfully; otherwise, false. In some cases, false may be returned for invalid names.

signal()

bool xtd::threading::mutex::signal ( )

overrideprotectedvirtual

Releases ownership of the specified wait_handle object.

Returns

true If the function succeeds, false otherwise.

Remarks

Override this function for all derived object

Implements xtd::threading::wait_handle.

wait()

bool xtd::threading::mutex::wait ( int32 milliseconds_timeout )

overrideprotectedvirtual

wait ownership of the specified mutex object.

Parameters

handle	A valid handle to an open object.
milliseconds_timeout	The number of milliseconds to wait, or -1 to wait indefinitely.

Returns

true if the current instance receives a signal; otherwise, false.

Remarks

If milliseconds_timeout is zero, the method does not block. It tests the state of the wait handle and returns immediately.

Override this function for all derived object

Implements xtd::threading::wait_handle.

---

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

• xtd.core/include/xtd/threading/mutex.hpp