xtd::threading::semaphore Class Reference

Inheritance diagram for xtd::threading::semaphore:

Definition

Limits the number of threads that can access a resource or pool of resources concurrently.

class core_export_ semaphore : public xtd::threading::wait_handle, public xtd::icomparable<semaphore>, public xtd::iequatable<semaphore>

Header

#include <xtd/threading/semaphore>

Namespace

xtd::threading

Library

xtd.core

Remarks

Use the xtd::threading::semaphore class to control access to a pool of resources. Threads enter the semaphore by calling the xtd::threading::wait_handle::wait_one method, which is inherited from the xtd::threading::wait_handle class, and release the semaphore by calling the xtd::threading::semaphore::release method.

The count on a semaphore is decremented each time a thread enters the semaphore, and incremented when a thread releases the semaphore. When the count is zero, subsequent requests block until other threads release the semaphore. When all threads have released the semaphore, the count is at the maximum value specified when the semaphore was created.

There is no guaranteed order, such as FIFO or LIFO, in which blocked threads enter the semaphore.

A thread can enter the semaphore multiple times, by calling the xtd::threading::wait_handle::wait_one method repeatedly. To release some or all of these entries, the thread can call the parameterless xtd::threading::semaphore::release() method overload multiple times, or it can call the xtd::threading::semaphore::release(int32) method overload that specifies the number of entries to be released.

The xtd::threading::semaphore class does not enforce thread identity on calls to xtd::threading::wait_handle::wait_one or xtd::threading::semaphore::release. It is the programmer's responsibility to ensure that threads do not release the semaphore too many times. For example, suppose a semaphore has a maximum count of two, and that thread A and thread B both enter the semaphore. If a programming error in thread B causes it to call xtd::threading::semaphore::release twice, both calls succeed. The count on the semaphore is full, and when thread A eventually calls xtd::threading::semaphore::release, a xtd::threading::semaphore_full_exception is thrown.

Semaphores are of two types: local semaphores and named system semaphores. If you create a xtd::threading::semaphore object using a constructor that accepts a name, it is associated with an operating-system semaphore of that name. Named system semaphores are visible throughout the operating system, and can be used to synchronize the activities of processes. You can create multiple xtd::threading::semaphore objects that represent the same named system semaphore, and you can use the xtd::threading::semaphore::open_existing method to open an existing named system semaphore.

A local semaphore exists only within your process. It can be used by any thread in your process that has a reference to the local xtd::threading::semaphore object. Each xtd::threading::semaphore object is a separate local semaphore.

Example

The following code example creates a semaphore with a maximum count of three and an initial count of zero. The example starts five threads, which block waiting for the semaphore. The main thread uses the xtd::threading::semaphore::release(int32) method overload to increase the semaphore count to its maximum, allowing three threads to enter the semaphore. Each thread uses the xtd::threading::thread::sleep method to wait for one second, to simulate work, and then calls the xtd::threading::semaphore::release() method overload to release the semaphore. Each time the semaphore is released, the previous semaphore count is displayed. Console messages track semaphore use. The simulated work interval is increased slightly for each thread, to make the output easier to read.

#include <xtd/collections/generic/list>
#include <xtd/threading/interlocked>
#include <xtd/threading/semaphore>
#include <xtd/threading/thread>
#include <xtd/console>
#include <xtd/startup>
 
using namespace xtd;
using namespace xtd::collections::generic;
using namespace xtd::threading;
 
namespace mutex_example {
  class program {
  public:
    static void main() {
      // Create a semaphore that can satisfy up to three
      // concurrent requests. Use an initial count of zero,
      // so that the entire semaphore count is initially
      // owned by the main program thread.
      //
      pool = semaphore {0, 3};
      
      // Create and start five numbered threads.
      //
      for(auto i = 1; i <= 5; ++i) {
        threads.emplace_back(worker);
        
        // Start the thread, passing the number.
        //
        threads.back().start(i);
      }
      
      // Wait for half a second, to allow all the
      // threads to start and to block on the semaphore.
      //
      thread::sleep(500);
      
      // The main thread starts out holding the entire
      // semaphore count. Calling Release(3) brings the
      // semaphore count back to its maximum value, and
      // allows the waiting threads to enter the semaphore,
      // up to three at a time.
      //
      console::write_line("Main thread calls Release(3).");
      pool.release(3);
      
      thread::sleep(100);
      console::write_line("Main thread exits.");
      
      // Join all threads with timeout because the pool
      // semaphore released only for 3 threads.
      thread::join_all(threads, 100);
    }
    
    static void worker(std::any num) {
      // Each worker thread begins by requesting the
      // semaphore.
      console::write_line("thread {0} begins "
                          "and waits for the semaphore.", num);
      pool.wait_one();
      
      // A padding interval to make the output more orderly.
      int padding = interlocked::add(padding, 100);
      
      console::write_line("thread {0} enters the semaphore.", num);
      
      // The thread's "work" consists of sleeping for
      // about a second. Each thread "works" a little
      // longer, just to make the output more orderly.
      //
      thread::sleep(1000 + padding);
      
      console::write_line("thread {0} releases the semaphore.", num);
      console::write_line("thread {0} previous semaphore count: {1}",
                          num, pool.release());
    }
    
  private:
    inline static list<thread> threads = list<thread>(5);
 
    // A semaphore that simulates a limited resource pool.
    //
    inline static semaphore pool;
    
    // A padding interval to make the output more orderly.
    inline static int padding;
    
  };
}
 
startup_(mutex_example::program::main);
 
// This example produces output similar to the following:
//
// thread 2 begins and waits for the semaphore.
// thread 5 begins and waits for the semaphore.
// thread 4 begins and waits for the semaphore.
// thread 1 begins and waits for the semaphore.
// thread 3 begins and waits for the semaphore.
// Main thread calls Release(3).
// thread 5 enters the semaphore.
// thread 2 enters the semaphore.
// thread 1 enters the semaphore.
// thread 5 releases the semaphore.
// thread 5 previous semaphore count: 0
// thread 4 enters the semaphore.
// thread 2 releases the semaphore.
// thread 2 previous semaphore count: 0
// thread 3 enters the semaphore.
// thread 1 releases the semaphore.
// thread 1 previous semaphore count: 0
// thread 4 releases the semaphore.
// thread 4 previous semaphore count: 1
// thread 3 releases the semaphore.
// thread 3 previous semaphore count: 2
// Main thread exits.

Examples

semaphore.cpp.

Public Constructors
	semaphore ()
	Initializes a new instance of the xtd::threading::semaphore class.
	semaphore (const string &name)
	nitializes a new instance of the xtd::threading::semaphore class, specifying optionally specifying the name of a system semaphore object.
	semaphore (const string &name, bool &created_new)
	nitializes a new instance of the xtd::threading::semaphore class, specifying optionally specifying the name of a system semaphore object, and specifying a variable that receives a value indicating whether a new system semaphore was created.
	semaphore (int32 initial_count)
	Initializes a new instance of the xtd::threading::semaphore class, specifying the initial number of entries.
	semaphore (int32 initial_count, const string &name)
	nitializes a new instance of the xtd::threading::semaphore class, specifying the initial number of entries and the maximum number of concurrent entries, optionally specifying the name of a system semaphore object.
	semaphore (int32 initial_count, const string &name, bool &created_new)
	nitializes a new instance of the xtd::threading::semaphore class, specifying the initial number of entries and the maximum number of concurrent entries, optionally specifying the name of a system semaphore object, and specifying a variable that receives a value indicating whether a new system semaphore was created.
	semaphore (int32 initial_count, int32 maximum_count)
	Initializes a new instance of the xtd::threading::semaphore class, specifying the initial number of entries and the maximum number of concurrent entries.
	semaphore (int32 initial_count, int32 maximum_count, const string &name)
	Initializes a new instance of the xtd::threading::semaphore class, specifying the initial number of entries and the maximum number of concurrent entries, and optionally specifying the name of a system semaphore object.
	semaphore (int32 initial_count, int32 maximum_count, const string &name, bool &created_new)
	nitializes a new instance of the xtd::threading::semaphore class, specifying the initial number of entries and the maximum number of concurrent entries, optionally specifying the name of a system semaphore object, and specifying a variable that receives a value indicating whether a new system semaphore was created.

Public Properties
intptr	handle () const noexcept override
	Gets the native operating system handle.
void	handle (intptr value) override
	Sets the native operating system handle.

Public Methods
void	close () override
	Releases all resources held by the current xtd::threading::wait_handle.
int32	compare_to (const semaphore &value) const noexcept override
bool	equals (const semaphore &value) const noexcept override
int32	release ()
	Exits the semaphore and returns the previous count.
int32	release (int32 release_count)
	Exits the semaphore a specified number of times and returns the previous count.
virtual bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object.
template<typename object_a_t , typename 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.

Public Static Methods
static semaphore	open_existing (const string &name)
	Opens the specified named semaphore, if it already exists.
static bool	try_open_existing (const string &name, semaphore &result) noexcept
	Opens the specified named semaphore, 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 Public Attributes inherited from xtd::threading::wait_handle
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.
Public Member Functions inherited from xtd::threading::wait_handle
	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.
Public Member Functions inherited from xtd::object
	object ()=default
	Create a new instance of the ultimate base class object.
virtual size_t	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<typename object_t >
xtd::uptr< 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.
Public Member Functions inherited from xtd::icomparable< semaphore >
virtual int32	compare_to (const semaphore &obj) const noexcept=0
	Compares the current instance with another object of the same type.
Public Member Functions inherited from xtd::iequatable< semaphore >
virtual bool	equals (const semaphore &) const noexcept=0
	Indicates whether the current object is equal to another object of the same type.
Static Public Member Functions inherited from xtd::threading::wait_handle
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<typename 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<typename 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<typename 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<typename 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<typename 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<typename 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.
Static Public Member Functions inherited from xtd::object
template<typename object_a_t , typename 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<typename object_a_t , typename 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.
Protected Member Functions inherited from xtd::threading::wait_handle
Protected Member Functions inherited from xtd::abstract_object
	abstract_object ()=default
	Initializes a new instance of the xtd::abstract_object class.

Constructor & Destructor Documentation

semaphore() [1/9]

xtd::threading::semaphore::semaphore

(

)

Initializes a new instance of the xtd::threading::semaphore class.

Remarks

The initial count is set to 0 and the maximum count is set to xtd::int32_object::max_value.

semaphore() [2/9]

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

explicit

nitializes a new instance of the xtd::threading::semaphore class, specifying optionally specifying the name of a system semaphore object.

Parameters

name

The name, if the synchronization object is to be shared with other processes; otherwise, null or an empty string. The name is case-sensitive. The backslash character () is reserved and may only be used to specify a namespace. For more information on namespaces, see the remarks section. There may be further restrictions on the name depending on the operating system. For example, on Unix-based operating systems, the name after excluding the namespace must be a valid file name.

Exceptions

xtd::io::io_exception

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

This constructor initializes a xtd::threading::semaphore object that represents a named system semaphore. You can create multiple xtd::threading::semaphore objects that represent the same named system semaphore.

The initial count is set to 0 and the maximum count is set to xtd::int32_object::max_value.

If a name is provided and a synchronization object of the requested type already exists in the namespace, the existing synchronization object is used. Use createdNew to determine whether the system semaphore was created.

If you specify an empty string ("") for name, a local semaphore is created, as if you had called the xtd::threading::semaphore(int32, int32) constructor overload.

Because named semaphores are visible throughout the operating system, they can be used to coordinate resource use across process boundaries.

If you want to find out whether a named system semaphore exists, use the xtd::threading::semaphore::open_existing method. The xtd::threading::semaphore::open_existing method attempts to open an existing named semaphore, and throws an exception if the system semaphore does not exist.

semaphore() [3/9]

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

explicit

nitializes a new instance of the xtd::threading::semaphore class, specifying optionally specifying the name of a system semaphore object, and specifying a variable that receives a value indicating whether a new system semaphore was created.

Parameters

name

The name, if the synchronization object is to be shared with other processes; otherwise, null or an empty string. The name is case-sensitive. The backslash character () is reserved and may only be used to specify a namespace. For more information on namespaces, see the remarks section. There may be further restrictions on the name depending on the operating system. For example, on Unix-based operating systems, the name after excluding the namespace must be a valid file name.

created_new

When this method returns, contains true if a local semaphore was created (that is, if name is null or an empty string) or if the specified named system semaphore was created; false if the specified named system semaphore already existed. This parameter is passed uninitialized.

Exceptions

xtd::io::io_exception

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

This constructor initializes a xtd::threading::semaphore object that represents a named system semaphore. You can create multiple xtd::threading::semaphore objects that represent the same named system semaphore.

The initial count is set to 0 and the maximum count is set to xtd::int32_object::max_value.

If a name is provided and a synchronization object of the requested type already exists in the namespace, the existing synchronization object is used. Use createdNew to determine whether the system semaphore was created.

If you specify an empty string ("") for name, a local semaphore is created, as if you had called the xtd::threading::semaphore(int32, int32) constructor overload.

Because named semaphores are visible throughout the operating system, they can be used to coordinate resource use across process boundaries.

If you want to find out whether a named system semaphore exists, use the xtd::threading::semaphore::open_existing method. The xtd::threading::semaphore::open_existing method attempts to open an existing named semaphore, and throws an exception if the system semaphore does not exist.

semaphore() [4/9]

xtd::threading::semaphore::semaphore ( int32  initial_count )

explicit

Initializes a new instance of the xtd::threading::semaphore class, specifying the initial number of entries.

Parameters

initial_count

The initial number of requests for the semaphore that can be granted concurrently.

Exceptions

xtd::argument_out_of_range_exception

initial_count is less than 0.

Remarks

This constructor initializes an unnamed semaphore. All threads that use an instance of such a semaphore must have references to the instance.

The maximum count is set to xtd::int32_object::max_value.

semaphore() [5/9]

xtd::threading::semaphore::semaphore	(	int32	initial_count,
		const string &	name
	)

nitializes a new instance of the xtd::threading::semaphore class, specifying the initial number of entries and the maximum number of concurrent entries, optionally specifying the name of a system semaphore object.

Parameters

initial_count

The initial number of requests for the semaphore that can be granted concurrently.

name

The name, if the synchronization object is to be shared with other processes; otherwise, null or an empty string. The name is case-sensitive. The backslash character () is reserved and may only be used to specify a namespace. For more information on namespaces, see the remarks section. There may be further restrictions on the name depending on the operating system. For example, on Unix-based operating systems, the name after excluding the namespace must be a valid file name.

Exceptions

xtd::argument_out_of_range_exception	initial_count is less than 0.
xtd::io::io_exception	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

This constructor initializes a xtd::threading::semaphore object that represents a named system semaphore. You can create multiple xtd::threading::semaphore objects that represent the same named system semaphore.

If a name is provided and a synchronization object of the requested type already exists in the namespace, the existing synchronization object is used. Use createdNew to determine whether the system semaphore was created.

The maximum count is set to xtd::int32_object::max_value.

If you specify an empty string ("") for name, a local semaphore is created, as if you had called the xtd::threading::semaphore(int32, int32) constructor overload.

Because named semaphores are visible throughout the operating system, they can be used to coordinate resource use across process boundaries.

If you want to find out whether a named system semaphore exists, use the xtd::threading::semaphore::open_existing method. The xtd::threading::semaphore::open_existing method attempts to open an existing named semaphore, and throws an exception if the system semaphore does not exist.

semaphore() [6/9]

xtd::threading::semaphore::semaphore	(	int32	initial_count,
		const string &	name,
		bool &	created_new
	)

nitializes a new instance of the xtd::threading::semaphore class, specifying the initial number of entries and the maximum number of concurrent entries, optionally specifying the name of a system semaphore object, and specifying a variable that receives a value indicating whether a new system semaphore was created.

Parameters

initial_count	The initial number of requests for the semaphore that can be granted concurrently.
name	The name, if the synchronization object is to be shared with other processes; otherwise, null or an empty string. The name is case-sensitive. The backslash character () is reserved and may only be used to specify a namespace. For more information on namespaces, see the remarks section. There may be further restrictions on the name depending on the operating system. For example, on Unix-based operating systems, the name after excluding the namespace must be a valid file name.
created_new	When this method returns, contains true if a local semaphore was created (that is, if name is null or an empty string) or if the specified named system semaphore was created; false if the specified named system semaphore already existed. This parameter is passed uninitialized.

Exceptions

xtd::argument_out_of_range_exception	initial_count is less than 0.
xtd::io::io_exception	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

This constructor initializes a xtd::threading::semaphore object that represents a named system semaphore. You can create multiple xtd::threading::semaphore objects that represent the same named system semaphore.

If a name is provided and a synchronization object of the requested type already exists in the namespace, the existing synchronization object is used. Use createdNew to determine whether the system semaphore was created.

The maximum count is set to xtd::int32_object::max_value.

If you specify an empty string ("") for name, a local semaphore is created, as if you had called the xtd::threading::semaphore(int32, int32) constructor overload.

Because named semaphores are visible throughout the operating system, they can be used to coordinate resource use across process boundaries.

If you want to find out whether a named system semaphore exists, use the xtd::threading::semaphore::open_existing method. The xtd::threading::semaphore::open_existing method attempts to open an existing named semaphore, and throws an exception if the system semaphore does not exist.

semaphore() [7/9]

xtd::threading::semaphore::semaphore	(	int32	initial_count,
		int32	maximum_count
	)

Initializes a new instance of the xtd::threading::semaphore class, specifying the initial number of entries and the maximum number of concurrent entries.

Parameters

initial_count	The initial number of requests for the semaphore that can be granted concurrently.
maximum_count	The maximum number of requests for the semaphore that can be granted concurrently.

Exceptions

xtd::argument_exception	initial_count is greater than maximum_count.
xtd::argument_out_of_range_exception	maximum_count is less than 1. -or- initial_count is less than 0.

Remarks

This constructor initializes an unnamed semaphore. All threads that use an instance of such a semaphore must have references to the instance.

If initial_count is less than maximum_count, the effect is the same as if the current thread had called xtd::threading::wait_handle::wait_one (maximum_count minus initial_count) times. If you do not want to reserve any entries for the thread that creates the semaphore, use the same number for maximum_count and initial_count.

semaphore() [8/9]

xtd::threading::semaphore::semaphore	(	int32	initial_count,
		int32	maximum_count,
		const string &	name
	)

Initializes a new instance of the xtd::threading::semaphore class, specifying the initial number of entries and the maximum number of concurrent entries, and optionally specifying the name of a system semaphore object.

Parameters

initial_count	The initial number of requests for the semaphore that can be granted concurrently.
maximum_count	The maximum number of requests for the semaphore that can be granted concurrently.
name	The name, if the synchronization object is to be shared with other processes; otherwise, null or an empty string. The name is case-sensitive. The backslash character () is reserved and may only be used to specify a namespace. For more information on namespaces, see the remarks section. There may be further restrictions on the name depending on the operating system. For example, on Unix-based operating systems, the name after excluding the namespace must be a valid file name.

Exceptions

xtd::argument_exception	initial_count is greater than maximum_count.
xtd::argument_out_of_range_exception	maximum_count is less than 1. -or- initial_count is less than 0.
xtd::io::io_exception	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

This constructor initializes a xtd::threading::semaphore object that represents a named system semaphore. You can create multiple xtd::threading::semaphore objects that represent the same named system semaphore.

If a name is provided and a synchronization object of the requested type already exists in the namespace, the existing synchronization object is used.

If initial_count is less than maximum_count, the effect is the same as if the current thread had called xtd::threading::wait_handle::wait_one (maximum_count minus initial_count) times. If you do not want to reserve any entries for the thread that creates the semaphore, use the same number for maximum_count and initial_count.

Warning

When you use this constructor overload, the recommended practice is to specify the same number for initial_count and maximum_count. If initial_count is less than maximum_count, and a named system semaphore is created, the effect is the same as if the current thread had called xtd::threading::wait_handle::wait_one (maximum_count minus initial_count) times. However, with this constructor overload there is no way to determine whether a named system semaphore was created.

Remarks

If you specify an empty string ("") for name, a local semaphore is created, as if you had called the xtd::threading::semaphore(int32, int32) constructor overload.

Because named semaphores are visible throughout the operating system, they can be used to coordinate resource use across process boundaries.

If you want to find out whether a named system semaphore exists, use the xtd::threading::semaphore::open_existing method. The xtd::threading::semaphore::open_existing method attempts to open an existing named semaphore, and throws an exception if the system semaphore does not exist.

semaphore() [9/9]

xtd::threading::semaphore::semaphore	(	int32	initial_count,
		int32	maximum_count,
		const string &	name,
		bool &	created_new
	)

nitializes a new instance of the xtd::threading::semaphore class, specifying the initial number of entries and the maximum number of concurrent entries, optionally specifying the name of a system semaphore object, and specifying a variable that receives a value indicating whether a new system semaphore was created.

Parameters

initial_count	The initial number of requests for the semaphore that can be granted concurrently.
maximum_count	The maximum number of requests for the semaphore that can be granted concurrently.
name	The name, if the synchronization object is to be shared with other processes; otherwise, null or an empty string. The name is case-sensitive. The backslash character () is reserved and may only be used to specify a namespace. For more information on namespaces, see the remarks section. There may be further restrictions on the name depending on the operating system. For example, on Unix-based operating systems, the name after excluding the namespace must be a valid file name.
created_new	When this method returns, contains true if a local semaphore was created (that is, if name is null or an empty string) or if the specified named system semaphore was created; false if the specified named system semaphore already existed. This parameter is passed uninitialized.

Exceptions

xtd::argument_exception	initial_count is greater than maximum_count.
xtd::argument_out_of_range_exception	maximum_count is less than 1. -or- initial_count is less than 0.
xtd::io::io_exception	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

This constructor initializes a xtd::threading::semaphore object that represents a named system semaphore. You can create multiple xtd::threading::semaphore objects that represent the same named system semaphore.

If a name is provided and a synchronization object of the requested type already exists in the namespace, the existing synchronization object is used. Use createdNew to determine whether the system semaphore was created.

If initial_count is less than maximum_count, the effect is the same as if the current thread had called xtd::threading::wait_handle::wait_one (maximum_count minus initial_count) times. If you do not want to reserve any entries for the thread that creates the semaphore, use the same number for maximum_count and initial_count.

If you specify an empty string ("") for name, a local semaphore is created, as if you had called the xtd::threading::semaphore(int32, int32) constructor overload.

Because named semaphores are visible throughout the operating system, they can be used to coordinate resource use across process boundaries.

If you want to find out whether a named system semaphore exists, use the xtd::threading::semaphore::open_existing method. The xtd::threading::semaphore::open_existing method attempts to open an existing named semaphore, and throws an exception if the system semaphore does not exist.

Member Function Documentation

handle() [1/2]

intptr xtd::threading::semaphore::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::semaphore::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.

close()

void xtd::threading::semaphore::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.

release() [1/2]

int32 xtd::threading::semaphore::release

(

)

Exits the semaphore and returns the previous count.

Returns

The count on the semaphore before the xtd::threading::semaphore::release method was called.

Exceptions

xtd::threading::semaphore_full_exception	The semaphore count is already at the maximum value.
xtd::io::io_exception	A Win32 or pthred error occurred with a named semaphore.

Remarks

Threads typically use the xtd::threading::wait_handle::wait_one method to enter the semaphore, and they typically use this method overload to exit.

If a xtd::threading::semaphore_full_exception is thrown by the xtd::threading::release method, it does not necessarily indicate a problem with the calling thread. A programming error in another thread might have caused that thread to exit the semaphore more times than it entered.

release() [2/2]

int32 xtd::threading::semaphore::release

(

int32

release_count

)

Exits the semaphore a specified number of times and returns the previous count.

Parameters

release_count

The number of times to exit the semaphore.

Returns

The count on the semaphore before the xtd::threading::semaphore::release method was called.

Exceptions

xtd::argument_out_of_range_exception	releaseCount is less than 1.
xtd::threading::semaphore_full_exception	The semaphore count is already at the maximum value.

Remarks

Threads typically use the xtd::threading::wait_handle::wait_one method to enter the semaphore, and they typically use this method overload to exit.

If a xtd::threading::semaphore_full_exception is thrown by the xtd::threading::release method, it does not necessarily indicate a problem with the calling thread. A programming error in another thread might have caused that thread to exit the semaphore more times than it entered.

open_existing()

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

static

Opens the specified named semaphore, if it already exists.

Parameters

name	The name of the synchronization object to be shared with other processes. The name is case-sensitive.

Returns

An object that represents the named system semaphore.

Exceptions

xtd::argument_exception	name is an empty string.
xtd::io::io_exception	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. -or- There was some other error. The HResult property may provide more information.

Remarks

If a synchronization object of the requested type exists in the namespace, the existing synchronization object is opened.

The xtd::threading::semaphore::open_existing method tries to open the specified named semaphore. To create the system semaphore when it does not already exist, use one of the xtd::threading::semaphore constructors that has a name parameter.

Multiple calls to this method that use the same value for name do not necessarily return the same xtd::threading::semaphore object, even though the objects that are returned represent the same named system semaphore.

try_open_existing()

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

staticnoexcept

Opens the specified named semaphore, 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 () is reserved and may only be used to specify a namespace. For more information on namespaces, see the remarks section. There may be further restrictions on the name depending on the operating system. For example, on Unix-based operating systems, the name after excluding the namespace must be a valid file name.

result

When this method returns, contains a xtd::threading::semaphore object that represents the named semaphore if the call succeeded.

Returns

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

Remarks

If a synchronization object of the requested type exists in the namespace, the existing synchronization object is opened.

The xtd::threading::semaphore::open_existing method tries to open the specified named semaphore. To create the system semaphore when it does not already exist, use one of the xtd::threading::semaphore constructors that has a name parameter.

Multiple calls to this method that use the same value for name do not necessarily return the same xtd::threading::semaphore object, even though the objects that are returned represent the same named system semaphore.

signal()

bool xtd::threading::semaphore::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::semaphore::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.

equals() [1/2]

virtual bool xtd::object::equals ( const object &  obj ) const

virtualnoexcept

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/console>
 
using namespace 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.

equals() [2/2]

template<typename object_a_t , typename object_b_t >

static bool xtd::object::equals ( const object_a_t &  object_a, const object_b_t &  object_b  )

inlinestaticnoexcept

Determines whether the specified object instances are considered equal.

Parameters

object_a	The first object to compare.
object_b	The second object to compare.

Returns

true if object_a is the same instance as object_b or if both are null references or if object_a(object_b) returns true. otherwise, false.

Examples

The following code example compares different objects.

#include <xtd/console>
 
using namespace xtd;
 
auto main() -> int {
  string s1 = "Tom";
  string s2 = "Carol";
  console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
  
  s1 = "Tom";
  s2 = "Tom";
  console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
  
  s1 = "";
  s2 = "Tom";
  console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
  
  s1 = "Carol";
  s2 = "";
  console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
  
  s1 = "";
  s2 = "";
  console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
}
 
// This code produces the following output :
//
// object::equals("Tom", "Carol") => false
// object::equals("Tom", "Tom") => true
// object::equals("", "Tom") => false
// object::equals("Carol", "") => false
// object::equals("", "") => true

---

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

• xtd.core/include/xtd/threading/semaphore.h