xtd: xtd::threading::semaphore Class Reference (original) (raw)
Limits the number of threads that can access a resource or pool of resources concurrently.
Defines a generalized comparison method that a value type or class implements to create a type-specif...
Definition icomparable.hpp:21
Defines a generalized method that a value type or class implements to create a type-specific method f...
Definition iequatable.hpp:22
semaphore()
Initializes a new instance of the xtd::threading::semaphore class.
Encapsulates operating system specific objects that wait for exclusive access to shared resources.
Definition wait_handle.hpp:52
#define core_export_
Define shared library export.
Definition core_export.hpp:13
Header
#include <xtd/threading/semaphore>
Namespace
Library
xtd.core
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/xtd>
namespace mutex_example {
class program {
public:
static void main() {
pool = semaphore {0, 3};
for(auto i = 1; i <= 5; ++i) {
threads.add(thread {worker});
threads[threads.count() - 1].start(i);
}
thread::sleep(500);
console::write_line("Main thread calls Release(3).");
pool.release(3);
thread::sleep(100);
console::write_line("Main thread exits.");
thread::join_all(threads, 100);
}
static void worker(any_object num) {
console::write_line("thread {0} begins "
"and waits for the semaphore.", num);
pool.wait_one();
int padding = interlocked::add(padding, 100);
console::write_line("thread {0} enters the semaphore.", num);
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 threads = list(5);
inline static semaphore pool;
};
}
startup_(mutex_example::program::main);
Creates and controls a thread, sets its priority, and gets its status.
Definition thread.hpp:49
#define startup_(main_method)
Defines the entry point to be called when the application loads. Generally this is set either to the ...
Definition startup.hpp:168
xtd::forms::style_sheets::lengths padding
Padding is used to create space around an element's content, inside of any defined borders.
Definition padding.hpp:26
@ i
The I key.
Definition console_key.hpp:104
| Public Constructors |
|---|
| 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 object &obj) const noexcept override |
| Determines whether the specified object is equal to the current object. | |
| bool | equals (const semaphore &other) const noexcept override |
| Determines whether the specified object is equal to the current object. | |
| 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. | |
| 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 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 semaphore &obj) const noexcept=0 |
| Compares the current instance with another object of the same type. | |
| virtual bool | equals (const semaphore &) 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. | |
| xtd::threading::semaphore::semaphore | ( | ) |
|---|
◆ semaphore() [2/9]
| xtd::threading::semaphore::semaphore ( const string & name) | explicit |
|---|
Initializes 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. |
|---|
◆ semaphore() [3/9]
| xtd::threading::semaphore::semaphore ( const string & name, bool & created_new ) | explicit |
|---|
Initializes 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. |
|---|
◆ 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
◆ semaphore() [5/9]
| xtd::threading::semaphore::semaphore | ( | int32 | initial_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, 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. |
◆ semaphore() [6/9]
| xtd::threading::semaphore::semaphore | ( | int32 | initial_count, |
|---|---|---|---|
| const string & | name, | ||
| bool & | created_new ) |
Initializes 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. |
◆ 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
◆ 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. |
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.
◆ semaphore() [9/9]
| xtd::threading::semaphore::semaphore | ( | int32 | initial_count, |
|---|---|---|---|
| int32 | maximum_count, | ||
| const string & | name, | ||
| bool & | created_new ) |
Initializes 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. |
◆ 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 |
|---|
◆ equals() [1/2]
| bool xtd::threading::semaphore::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.
Reimplemented from xtd::object.
◆ equals() [2/2]
| bool xtd::threading::semaphore::equals ( const semaphore & other) const | overridenoexcept |
|---|
Determines whether the specified object is equal to the current object.
Parameters
| other | The object to compare with the current object. |
|---|
Returns
true if the specified object is equal to the current object. otherwise, false.
◆ 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
◆ 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
◆ 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. |
◆ 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.
◆ signal()
| bool xtd::threading::semaphore::signal ( ) | overrideprotectedvirtual |
|---|
◆ 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.
Implements xtd::threading::wait_handle.
The documentation for this class was generated from the following file:
- xtd.core/include/xtd/threading/semaphore.hpp