xtd 0.2.0
Loading...
Searching...
No Matches
xtd::threading::semaphore Class Reference
Inheritance diagram for xtd::threading::semaphore:
xtd::threading::wait_handle xtd::icomparable< semaphore > xtd::iequatable< semaphore > xtd::abstract_object xtd::interface xtd::comparison_operators< type_t, comparable_t > xtd::interface xtd::equality_operators< type_t, equatable_t > xtd::object

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>
Defines a generalized comparison method that a value type or class implements to create a type-specif...
Definition icomparable.h:21
Defines a generalized method that a value type or class implements to create a type-specific method f...
Definition iequatable.h:22
Limits the number of threads that can access a resource or pool of resources concurrently.
Definition semaphore.h:38
Encapsulates operating system specific objects that wait for exclusive access to shared resources.
Definition wait_handle.h:52
#define core_export_
Define shared library export.
Definition core_export.h:13
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.
Represents a strongly typed list of objects that can be accessed by index. Provides methods to search...
Definition list.h:71
#define startup_(main_method)
Defines the entry point to be called when the application loads. Generally this is set either to the ...
Definition startup.h:175
xtd::forms::style_sheets::lengths padding
Padding is used to create space around an element's content, inside of any defined borders.
Definition padding.h:26
@ i
The I key.
The xtd::collections::generic namespace contains interfaces and classes that define generic collectio...
Definition comparer.h:15
The xtd::threading namespace provides classes and interfaces that enable multithreaded programming....
Definition abandoned_mutex_exception.h:11
The xtd namespace contains all fundamental classes to access Hardware, Os, System,...
Definition xtd_about_box.h:10
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
nameThe 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_exceptionname 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
nameThe 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_newWhen 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_exceptionname 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_countThe initial number of requests for the semaphore that can be granted concurrently.
Exceptions
xtd::argument_out_of_range_exceptioninitial_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_countThe initial number of requests for the semaphore that can be granted concurrently.
nameThe 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_exceptioninitial_count is less than 0.
xtd::io::io_exceptionname 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_countThe initial number of requests for the semaphore that can be granted concurrently.
nameThe 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_newWhen 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_exceptioninitial_count is less than 0.
xtd::io::io_exceptionname 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_countThe initial number of requests for the semaphore that can be granted concurrently.
maximum_countThe maximum number of requests for the semaphore that can be granted concurrently.
Exceptions
xtd::argument_exceptioninitial_count is greater than maximum_count.
xtd::argument_out_of_range_exceptionmaximum_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_countThe initial number of requests for the semaphore that can be granted concurrently.
maximum_countThe maximum number of requests for the semaphore that can be granted concurrently.
nameThe 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_exceptioninitial_count is greater than maximum_count.
xtd::argument_out_of_range_exceptionmaximum_count is less than 1.
-or-
initial_count is less than 0.
xtd::io::io_exceptionname 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_countThe initial number of requests for the semaphore that can be granted concurrently.
maximum_countThe maximum number of requests for the semaphore that can be granted concurrently.
nameThe 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_newWhen 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_exceptioninitial_count is greater than maximum_count.
xtd::argument_out_of_range_exceptionmaximum_count is less than 1.
-or-
initial_count is less than 0.
xtd::io::io_exceptionname 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
valueAn 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_exceptionThe semaphore count is already at the maximum value.
xtd::io::io_exceptionA 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_countThe 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_exceptionreleaseCount is less than 1.
xtd::threading::semaphore_full_exceptionThe 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
nameThe 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_exceptionname is an empty string.
xtd::io::io_exceptionname 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
nameThe 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.
resultWhen 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
handleA valid handle to an open object.
milliseconds_timeoutThe 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
objThe 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
static void write_line()
Writes the current line terminator to the standard output stream using the specified format informati...

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_aThe first object to compare.
object_bThe 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
virtual bool equals(const object &obj) const noexcept
Determines whether the specified object is equal to the current object.

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