From 502a329709cc463893a1c85601fe9f86c5f9723a Mon Sep 17 00:00:00 2001 From: Eduardo Velarde <32459232+eduardo-vp@users.noreply.github.com> Date: Fri, 12 Sep 2025 13:39:48 -0700 Subject: [PATCH] Update the new APIs for Mutex, Semaphore, and EventWaitHandle (#11799) --- xml/System.Threading/EventWaitHandle.xml | 264 +++++++++++++----- xml/System.Threading/Mutex.xml | 263 +++++++++++++---- .../NamedWaitHandleOptions.xml | 48 +++- xml/System.Threading/Semaphore.xml | 217 +++++++++++--- 4 files changed, 622 insertions(+), 170 deletions(-) diff --git a/xml/System.Threading/EventWaitHandle.xml b/xml/System.Threading/EventWaitHandle.xml index aa3f1df00e6..1450854593d 100644 --- a/xml/System.Threading/EventWaitHandle.xml +++ b/xml/System.Threading/EventWaitHandle.xml @@ -76,7 +76,7 @@ The class allows threads to communicate For more information, see the [Thread interaction, or signaling](/dotnet/standard/threading/overview-of-synchronization-primitives#thread-interaction-or-signaling) section of the [Overview of synchronization primitives](/dotnet/standard/threading/overview-of-synchronization-primitives) article. > [!CAUTION] -> By default, a named event is not restricted to the user that created it. Other users may be able to open and use the event, including interfering with the event by setting or resetting it inappropriately. To restrict access to specific users, you can use a constructor overload or and pass in an when creating the named event. Avoid using named events without access restrictions on systems that might have untrusted users running code. +> By default, a named event is not restricted to the user that created it. Other users might be able to open and use the event, including interfering with the event by setting or resetting it inappropriately. To restrict access to specific users, you can use a constructor overload or and pass in an when creating the named event. Avoid using named events without access restrictions on systems that might have untrusted users running code. ## Examples The following code example uses the method overload to allow the main thread to signal a blocked thread and then wait until the thread finishes a task. @@ -159,7 +159,7 @@ The class allows threads to communicate flag is specified for `mode`, threads that wait on the event will not block. If the initial state is signaled, and `mode` is , the first thread that waits on the event will be released immediately, after which the event will reset, and subsequent threads will block. + If the initial state of the event is nonsignaled, threads that wait on the event will block. If the initial state is signaled, and the flag is specified for `mode`, threads that wait on the event will not block. If the initial state is signaled and `mode` is , the first thread that waits on the event will be released immediately, after which the event will reset, and subsequent threads will block. ## Examples The following code example uses the method overload to allow the main thread to signal a blocked thread and then wait until the thread finishes a task. @@ -224,36 +224,36 @@ The class allows threads to communicate to set the initial state to signaled if the named event is created as a result of this call; to set it to nonsignaled. One of the values that determines whether the event resets automatically or manually. - The name, if the synchronization object is to be shared with other processes; otherwise, 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. + The name, if the synchronization object is to be shared with other processes; otherwise, or an empty string. The name is case-sensitive. The backslash character (\\) is reserved and can only be used to specify a namespace. For more information on namespaces, see the remarks section. There might 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. Initializes a new instance of the class, specifying whether the wait handle is initially signaled if created as a result of this call, whether it resets automatically or manually, and the name of a system synchronization event. [!CAUTION] -> By default, a named event is not restricted to the user that created it. Other users may be able to open and use the event, including interfering with the event by setting or resetting it inappropriately. To restrict access to specific users, you can use a constructor overload or and pass in an when creating the named event. Avoid using named events without access restrictions on systems that might have untrusted users running code. +> By default, a named event is not restricted to the user that created it. Other users might be able to open and use the event, including interfering with the event by setting or resetting it inappropriately. To restrict access to specific users, you can use a constructor overload or and pass in an when creating the named event. Avoid using named events without access restrictions on systems that might have untrusted users running code. > [!IMPORTANT] > When using this constructor for named system events, specify `false` for `initialState`. This constructor provides no way to determine whether a named system event was created, so you cannot make any assumptions about the state of the named event. To determine whether a named event was created, use the constructor or the constructor. - If the initial state of the event is nonsignaled, threads that wait on the event will block. If the initial state is signaled, and the flag is specified for `mode`, threads that wait on the event will not block. If the initial state is signaled, and `mode` is , the first thread that waits on the event will be released immediately, after which the event will reset, and subsequent threads will block. + If the initial state of the event is nonsignaled, threads that wait on the event will block. If the initial state is signaled, and the flag is specified for `mode`, threads that wait on the event will not block. If the initial state is signaled and `mode` is , the first thread that waits on the event will be released immediately, after which the event will reset, and subsequent threads will block. ]]> - 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. + is invalid. This can be for various reasons, including some restrictions that might 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. +There was some other error. The `HResult` property might provide more information. Windows only: specified an unknown namespace. See Object Names for more information. - The is too long. Length restrictions may depend on the operating system or configuration. + The is too long. Length restrictions might depend on the operating system or configuration. The named event exists and has access control security, but the user does not have . A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. @@ -315,34 +315,34 @@ There was some other error. The `HResult` property may provide more information. to set the initial state to signaled if the named event is created as a result of this call; to set it to nonsignaled. One of the values that determines whether the event resets automatically or manually. - The name, if the synchronization object is to be shared with other processes; otherwise, 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. + The name, if the synchronization object is to be shared with other processes; otherwise, or an empty string. The name is case-sensitive. The backslash character (\\) is reserved and can only be used to specify a namespace. For more information on namespaces, see the remarks section. There might 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. When this method returns, contains if a local event was created (that is, if is or an empty string) or if the specified named system event was created; if the specified named system event already existed. This parameter is passed uninitialized. Initializes a new instance of the class, specifying whether the wait handle is initially signaled if created as a result of this call, whether it resets automatically or manually, the name of a system synchronization event, and a Boolean variable whose value after the call indicates whether the named system event was created. flag is specified for `mode`, threads that wait on the event will not block. If the initial state is signaled, and `mode` is , the first thread that waits on the event will be released immediately, after which the event will reset, and subsequent threads will block. + If the initial state of the event is nonsignaled, threads that wait on the event will block. If the initial state is signaled, and the flag is specified for `mode`, threads that wait on the event will not block. If the initial state is signaled and `mode` is , the first thread that waits on the event will be released immediately, after which the event will reset, and subsequent threads will block. > [!CAUTION] -> By default, a named event is not restricted to the user that created it. Other users may be able to open and use the event, including interfering with the event by setting or resetting it inappropriately. To restrict access to specific users, you can use a constructor overload or and pass in an when creating the named event. Avoid using named events without access restrictions on systems that might have untrusted users running code. +> By default, a named event is not restricted to the user that created it. Other users might be able to open and use the event, including interfering with the event by setting or resetting it inappropriately. To restrict access to specific users, you can use a constructor overload or and pass in an when creating the named event. Avoid using named events without access restrictions on systems that might have untrusted users running code. ]]> - 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. + is invalid. This can be for various reasons, including some restrictions that might 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. +There was some other error. The `HResult` property might provide more information. Windows only: specified an unknown namespace. See Object Names for more information. - The is too long. Length restrictions may depend on the operating system or configuration. + The is too long. Length restrictions might depend on the operating system or configuration. The named event exists and has access control security, but the user does not have . A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. @@ -379,12 +379,47 @@ There was some other error. The `HResult` property may provide more information. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. + + to set the initial state to signaled if the named event is created as a result of this call; to set it to nonsignaled. + One of the values that determines whether the event resets automatically or manually. + The name, if the synchronization object is to be shared with other processes; otherwise, or an empty string. The name is case-sensitive. + The scope options for the named handle. Defaults to access limited to current user and current session only. The specified options might affect the namespace for the name and access to the underlying handle object. + Initializes a new instance of the class, specifying whether the wait handle is initially signaled if created as a result of this call, whether it resets automatically or manually, the name of a system synchronization event, and options to set user-scope and session-scope access. + + [!IMPORTANT] +> When using this constructor for named system events, specify `false` for `initialState`. This constructor provides no way to determine whether a named system event was created, so you can't make any assumptions about the state of the named event. To determine whether a named event was created, use the constructor or the constructor. + +If the initial state of the event is nonsignaled, threads that wait on the event will block. If the initial state is signaled and the flag is specified for `mode`, threads that wait on the event will not block. If the initial state is signaled and `mode` is , the first thread that waits on the event will be released immediately, after which the event will reset and subsequent threads will block. + +On Windows, `options` can be provided to specify whether the named system event is accessible to the current user only, or to all users. It also allows you to specify whether the named system event is accessible to processes in the current session only, or to all sessions. For more information, see . + +> [!CAUTION] +> On Unix-based operating systems, the `options` parameter has no effect as named system events aren't supported. + + ]]> + + + is invalid. This can be for various reasons, including some restrictions that might 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 might provide more information. + Windows only: specified an unknown namespace. See Object Names for more information. + The is too long. Length restrictions might depend on the operating system or configuration. + The named event exists and has access control security, but the user does not have . + A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. +-or- + +An object with the specified exists, but the specified are not compatible with the existing object's options. + + The enum value was out of legal range. + Overview of synchronization primitives @@ -423,7 +458,7 @@ There was some other error. The `HResult` property may provide more information. to set the initial state to signaled if the named event is created as a result of this call; to set it to nonsignaled. One of the values that determines whether the event resets automatically or manually. - The name, if the synchronization object is to be shared with other processes; otherwise, 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. + The name, if the synchronization object is to be shared with other processes; otherwise, or an empty string. The name is case-sensitive. The backslash character (\\) is reserved and can only be used to specify a namespace. For more information on namespaces, see the remarks section. There might 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. When this method returns, contains if a local event was created (that is, if is or an empty string) or if the specified named system event was created; if the specified named system event already existed. This parameter is passed uninitialized. An object that represents the access control security to be applied to the named system event. Initializes a new instance of the class, specifying whether the wait handle is initially signaled if created as a result of this call, whether it resets automatically or manually, the name of a system synchronization event, a Boolean variable whose value after the call indicates whether the named system event was created, and the access control security to be applied to the named event if it is created. @@ -440,16 +475,16 @@ There was some other error. The `HResult` property may provide more information. > [!NOTE] > The caller has full control over the newly created object even if `eventSecurity` denies or fails to grant some access rights to the current user. However, if the current user attempts to get another object to represent the same named event, using either a constructor or the method, Windows access control security is applied. - The `name` may be prefixed with `Global\` or `Local\` to specify a namespace. When the `Global` namespace is specified, the synchronization object may be shared with any processes on the system. When the `Local` namespace is specified, which is also the default when no namespace is specified, the synchronization object may be shared with processes in the same session. On Windows, a session is a login session, and services typically run in a different non-interactive session. On Unix-like operating systems, each shell has its own session. Session-local synchronization objects may be appropriate for synchronizing between processes with a parent/child relationship where they all run in the same session. For more information about synchronization object names on Windows, see [Object Names](/windows/win32/sync/object-names). + The `name` can be prefixed with `Global\` or `Local\` to specify a namespace. When the `Global` namespace is specified, the synchronization object can be shared with any processes on the system. When the `Local` namespace is specified, which is also the default when no namespace is specified, the synchronization object can be shared with processes in the same session. On Windows, a session is a login session, and services typically run in a different non-interactive session. On Unix-like operating systems, each shell has its own session. Session-local synchronization objects might be appropriate for synchronizing between processes with a parent/child relationship where they all run in the same session. For more information about synchronization object names on Windows, see [Object Names](/windows/win32/sync/object-names). If a `name` is provided and a synchronization object of the requested type already exists in the namespace, the existing synchronization object is opened. If a synchronization object of a different type already exists in the namespace, a `WaitHandleCannotBeOpenedException` is thrown. Otherwise, a new synchronization object is created. If a system event with the name specified for the `name` parameter already exists, the `initialState` parameter is ignored. After calling this constructor, use the value in the variable specified for the `ref` parameter (`ByRef` parameter in Visual Basic) `createdNew` to determine whether the named system event already existed or was created. - If the initial state of the event is nonsignaled, threads that wait on the event will block. If the initial state is signaled, and the flag is specified for `mode`, threads that wait on the event will not block. If the initial state is signaled, and `mode` is , the first thread that waits on the event will be released immediately, after which the event will reset, and subsequent threads will block. + If the initial state of the event is nonsignaled, threads that wait on the event will block. If the initial state is signaled, and the flag is specified for `mode`, threads that wait on the event will not block. If the initial state is signaled and `mode` is , the first thread that waits on the event will be released immediately, after which the event will reset, and subsequent threads will block. > [!CAUTION] -> By default, a named event is not restricted to the user that created it. Other users may be able to open and use the event, including interfering with the event by setting or resetting it inappropriately. To restrict access to specific users, you can pass in an when creating the named event. Avoid using named events without access restrictions on systems that might have untrusted users running code. +> By default, a named event is not restricted to the user that created it. Other users might be able to open and use the event, including interfering with the event by setting or resetting it inappropriately. To restrict access to specific users, you can pass in an when creating the named event. Avoid using named events without access restrictions on systems that might have untrusted users running code. ## Examples The following code example demonstrates the cross-process behavior of a named system event with access control security. The example uses the method overload to test for the existence of a named event. @@ -466,13 +501,13 @@ There was some other error. The `HResult` property may provide more information. ]]> - 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. + is invalid. This can be for various reasons, including some restrictions that might 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. +There was some other error. The `HResult` property might provide more information. Windows only: specified an unknown namespace. See Object Names for more information. - The is too long. Length restrictions may depend on the operating system or configuration. + The is too long. Length restrictions might depend on the operating system or configuration. The named event exists and has access control security, but the user does not have . A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. @@ -510,13 +545,46 @@ There was some other error. The `HResult` property may provide more information. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. + + to set the initial state to signaled if the named event is created as a result of this call; to set it to nonsignaled. + One of the values that determines whether the event resets automatically or manually. + The name, if the synchronization object is to be shared with other processes; otherwise, or an empty string. The name is case-sensitive. + The scope options for the named handle. Defaults to access limited to current user and current session only. The specified options might affect the namespace for the name and access to the underlying handle object. + When this method returns, contains if a local event was created (that is, if is or an empty string) or if the specified named system event was created; contains if the specified named system event already existed. This parameter is passed uninitialized. + Initializes a new instance of the class, specifying whether the wait handle is initially signaled if created as a result of this call, whether it resets automatically or manually, the name of a system synchronization event, options to set user-scope and session-scope access, and a Boolean variable whose value after the call indicates whether the named system event was created. + + flag is specified for `mode`, threads that wait on the event will not block. If the initial state is signaled and `mode` is , the first thread that waits on the event will be released immediately, after which the event will reset, and subsequent threads will block. + +On Windows, `options` can be provided to specify whether the named system event is accessible to the current user only or to all users. It also allows you to specify whether the named system event is accessible to processes in the current session only or to all sessions. For more information, see . + +> [!CAUTION] +> On Unix-based operating systems, the `options` parameter has no effect as named system events are not supported. + + ]]> + + + is invalid. This can be for various reasons, including some restrictions that might 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 might provide more information. + Windows only: specified an unknown namespace. See Object Names for more information. + The is too long. Length restrictions might depend on the operating system or configuration. + The named event exists and has access control security, but the user does not have . + A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. + + -or- + +An object with the specified exists, but the specified are not compatible with the existing object's options. + + The enum value was out of legal range. + Overview of synchronization primitives @@ -644,14 +712,14 @@ There was some other error. The `HResult` property may provide more information. - The name of the synchronization object to be opened and 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. + The name of the synchronization object to be opened and shared with other processes. The name is case-sensitive. The backslash character (\\) is reserved and can only be used to specify a namespace. For more information on namespaces, see the remarks section. There might 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. Opens the specified named synchronization event, if it already exists. An object that represents the named system event. - A synchronization object with the provided cannot be opened. It may not exist, or a synchronization object of a different type might have the same name. In some cases, this exception may be thrown for invalid names. + A synchronization object with the provided cannot be opened. It might not exist, or a synchronization object of a different type might have the same name. In some cases, this exception might be thrown for invalid names. is an empty string. @@ -675,13 +743,13 @@ There was some other error. The `HResult` property may provide more information. is . - 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. + is invalid. This can be for various reasons, including some restrictions that might 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. +There was some other error. The `HResult` property might provide more information. Windows only: specified an unknown namespace. See Object Names for more information. - The is too long. Length restrictions may depend on the operating system or configuration. + The is too long. Length restrictions might depend on the operating system or configuration. The named event exists, but the user does not have the security access required to use it. Overview of synchronization primitives @@ -719,7 +787,7 @@ There was some other error. The `HResult` property may provide more information. - The name of the synchronization object to be opened and 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. + The name of the synchronization object to be opened and shared with other processes. The name is case-sensitive. The backslash character (\\) is reserved and can only be used to specify a namespace. For more information on namespaces, see the remarks section. There might 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. A bitwise combination of the enumeration values that represent the desired security access. Opens the specified named synchronization event, if it already exists, with the desired security access. An object that represents the named system event. @@ -727,7 +795,7 @@ There was some other error. The `HResult` property may provide more information. is longer than MAX_PATH (260 characters). is . - A synchronization object with the provided cannot be opened. It may not exist, or a synchronization object of a different type might have the same name. In some cases, this exception may be thrown for invalid names. + A synchronization object with the provided cannot be opened. It might not exist, or a synchronization object of a different type might have the same name. In some cases, this exception might be thrown for invalid names. - 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. + is invalid. This can be for various reasons, including some restrictions that might 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. +There was some other error. The `HResult` property might provide more information. Windows only: specified an unknown namespace. See Object Names for more information. - The is too long. Length restrictions may depend on the operating system or configuration. + The is too long. Length restrictions might depend on the operating system or configuration. The named event exists, but the user does not have the desired security access. Overview of synchronization primitives @@ -804,11 +872,40 @@ There was some other error. The `HResult` property may provide more information. - To be added. - To be added. - To be added. - To be added. - To be added. + The name of the synchronization object to be opened and shared with other processes. The name is case-sensitive. + The scope options for the named handle. Defaults to access limited to current user and current session only. The specified options might affect the namespace for the name and access to the underlying handle object. + Opens the specified named synchronization event, if it already exists. If the options are set to the current user only, the object's access controls are verified for the calling user. + An object that represents the named system event. + + method tries to open the specified named system event. To create the system event when it does not already exist, use one of the constructors that has a `name` parameter. + +Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system event. + + ]]> + + A synchronization object with the provided cannot be opened. It might not exist, or a synchronization object of a different type might have the same name. In some cases, this exception might be thrown for invalid names. + +-or- + +An object with the specified exists, but the specified are not compatible with the existing object's options. + + is an empty string. + + is . + + is invalid. This can be for various reasons, including some restrictions that might 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 might provide more information. + Windows only: specified an unknown namespace. See Object Names for more information. + The is too long. Length restrictions might depend on the operating system or configuration. + The named event exists, but the user does not have the security access required to use it. + Overview of synchronization primitives @@ -1075,16 +1172,16 @@ There was some other error. The `HResult` property may provide more information. - The name of the synchronization object to be opened and 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. + The name of the synchronization object to be opened and shared with other processes. The name is case-sensitive. The backslash character (\\) is reserved and can only be used to specify a namespace. For more information on namespaces, see the remarks section. There might 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. When this method returns, contains a object that represents the named synchronization event if the call succeeded, or if the call failed. This parameter is treated as uninitialized. Opens the specified named synchronization event, if it already exists, and returns a value that indicates whether the operation succeeded. - if the named synchronization event was opened successfully; otherwise, . In some cases, may be returned for invalid names. + if the named synchronization event was opened successfully; otherwise, . In some cases, might be returned for invalid names. is . - 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. For some invalid names, the method may return instead. + is invalid. This can be for various reasons, including some restrictions that might 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. For some invalid names, the method might return instead. -or- -There was some other error. The `HResult` property may provide more information. - The is too long. Length restrictions may depend on the operating system or configuration. +There was some other error. The `HResult` property might provide more information. + The is too long. Length restrictions might depend on the operating system or configuration. The named event exists, but the user does not have the desired security access. @@ -1149,17 +1246,17 @@ There was some other error. The `HResult` property may provide more information. - The name of the synchronization object to be opened and 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. + The name of the synchronization object to be opened and shared with other processes. The name is case-sensitive. The backslash character (\\) is reserved and can only be used to specify a namespace. For more information on namespaces, see the remarks section. There might 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. A bitwise combination of the enumeration values that represent the desired security access. When this method returns, contains a object that represents the named synchronization event if the call succeeded, or if the call failed. This parameter is treated as uninitialized. Opens the specified named synchronization event, if it already exists, with the desired security access, and returns a value that indicates whether the operation succeeded. - if the named synchronization event was opened successfully; otherwise, . In some cases, may be returned for invalid names. + if the named synchronization event was opened successfully; otherwise, . In some cases, might be returned for invalid names. is . - 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. For some invalid names, the method may return instead. + is invalid. This can be for various reasons, including some restrictions that might 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. For some invalid names, the method might return instead. -or- -There was some other error. The `HResult` property may provide more information. - The is too long. Length restrictions may depend on the operating system or configuration. +There was some other error. The `HResult` property might provide more information. + The is too long. Length restrictions might depend on the operating system or configuration. The named event exists, but the user does not have the desired security access. @@ -1235,12 +1332,37 @@ There was some other error. The `HResult` property may provide more information. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. + The name of the synchronization object to be opened and shared with other processes. The name is case-sensitive. + The scope options for the named handle. Defaults to access limited to current user and current session only. The specified options might affect the namespace for the name and access to the underlying handle object. + When this method returns, contains a object that represents the named synchronization event if the call succeeded, or if the call failed. This parameter is treated as uninitialized. + Opens the specified named synchronization event, if it already exists, and returns a value that indicates whether the operation succeeded. If the options are set to the current user only, the object's access controls are verified for the calling user. + + if the named synchronization event was opened successfully; otherwise, . In some cases, might be returned for invalid names. + + constructors that has a `name` parameter. + +If you are uncertain whether a named synchronization event exists, use this method overload instead of the method overload, which throws an exception if the synchronization event does not exist. + +Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system event. + + ]]> + + + is an empty string. + + is . + + is invalid. This can be for various reasons, including some restrictions that might 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. For some invalid names, the method might return instead. + +-or- + +There was some other error. The `HResult` property might provide more information. + The is too long. Length restrictions might depend on the operating system or configuration. + The named event exists, but the user does not have the desired security access. diff --git a/xml/System.Threading/Mutex.xml b/xml/System.Threading/Mutex.xml index f1f120679f4..277153c75f4 100644 --- a/xml/System.Threading/Mutex.xml +++ b/xml/System.Threading/Mutex.xml @@ -326,9 +326,9 @@ This constructor initializes a object that represents a named system mutex. You can create multiple objects that represent the same named system mutex. - If the named mutex has already been created with access control security, and the caller does not have , an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. + If the named mutex has already been created with access control security and the caller does not have , an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. - If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. In this case, `createdNew` is always `true`. + If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. Because they are system-wide, named mutexes can be used to coordinate resource use across process boundaries. @@ -354,13 +354,13 @@ The named mutex exists and has access control security, but the user does not have . - 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. + is invalid. This can be for various reasons, including some restrictions that might 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. +There was some other error. The `HResult` property might provide more information. Windows only: specified an unknown namespace. See Object Names for more information. - The is too long. Length restrictions may depend on the operating system or configuration. + The is too long. Length restrictions might depend on the operating system or configuration. A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. .NET Framework only: is longer than MAX_PATH (260 characters). @@ -391,10 +391,43 @@ There was some other error. The `HResult` property may provide more information. - To be added. - To be added. - To be added. - To be added. + The name, if the synchronization object is to be shared with other processes; otherwise, or an empty string. The name is case-sensitive. + The scope options for the named system mutex. Defaults to access limited to current user and current session only. The specified options might affect the namespace for the name and access to the underlying system mutex object. + Initializes a new instance of the class with a string that is the name of the mutex and options to set user-scope and session-scope access. The calling thread does not request to have initial ownership of the mutex. + + object that represents a named system mutex. You can create multiple objects that represent the same named system mutex. + +If the named mutex has already been created with access control security and the caller does not have , an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. + +If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. + +Because they are system-wide, named mutexes can be used to coordinate resource use across process boundaries. + +The `options` parameter can be provided to specify whether the named mutex is accessible to the current user only or to all users. It also allows you to specify whether the named mutex is accessible to processes in the current session only or to all sessions. For more information, see . + +[!INCLUDE[backslash-mutex-note](~/includes/backslash-mutex.md)] + + ]]> + + The named mutex exists and has access control security, but the user does not have . + + is invalid. This can be for various reasons, including some restrictions that might 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 might provide more information. + Windows only: specified an unknown namespace. See Object Names for more information. + The is too long. Length restrictions might depend on the operating system or configuration. + A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. + -or- + +An object with the specified exists, but the specified are not compatible with the existing object's options. + Managed Threading + Mutexes @@ -465,7 +498,7 @@ There was some other error. The `HResult` property may provide more information. This constructor initializes a object that represents a named system mutex. You can create multiple objects that represent the same named system mutex. - If the named mutex has already been created with access control security, and the caller does not have rights, an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. + If the named mutex has already been created with access control security and the caller does not have rights, an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. In this case, `createdNew` is always `true`. @@ -489,13 +522,13 @@ There was some other error. The `HResult` property may provide more information. The named mutex exists and has access control security, but the user does not have . - 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. + is invalid. This can be for various reasons, including some restrictions that might 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. +There was some other error. The `HResult` property might provide more information. Windows only: specified an unknown namespace. See Object Names for more information. - The is too long. Length restrictions may depend on the operating system or configuration. + The is too long. Length restrictions might depend on the operating system or configuration. A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. .NET Framework only: is longer than MAX_PATH (260 characters). @@ -527,11 +560,45 @@ There was some other error. The `HResult` property may provide more information. - To be added. - To be added. - To be added. - To be added. - To be added. + + to give the calling thread initial ownership of the named system mutex if the named system mutex is created as a result of this call; otherwise, . + The name, if the synchronization object is to be shared with other processes; otherwise, or an empty string. The name is case-sensitive. + The scope options for the named system mutex. Defaults to access limited to current user and current session only. The specified options might affect the namespace for the name and access to the underlying system mutex object. + Initializes a new instance of the class with a Boolean value that indicates whether the calling thread should have initial ownership of the mutex, a string that is the name of the mutex, and options to set user-scope and session-scope access. + + constructor if you need to determine initial ownership. + +This constructor initializes a object that represents a named system mutex. You can create multiple objects that represent the same named system mutex. + +If the named mutex has already been created with access control security and the caller does not have , an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. + +If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. + +Because they are system-wide, named mutexes can be used to coordinate resource use across process boundaries. + +The `options` parameter can be provided to specify whether the named mutex is accessible to the current user only or to all users. It also allows you to specify whether the named mutex is accessible to processes in the current session only or to all sessions. For more information, see . + + ]]> + + The named mutex exists and has access control security, but the user does not have . + + is invalid. This can be for various reasons, including some restrictions that might 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 might provide more information. + Windows only: specified an unknown namespace. See Object Names for more information. + The is too long. Length restrictions might depend on the operating system or configuration. + A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. +-or- + +An object with the specified exists, but the specified are not compatible with the existing object's options. + Managed Threading + Mutexes @@ -595,7 +662,7 @@ There was some other error. The `HResult` property may provide more information. > [!NOTE] > The caller has full control over the newly created object even if `mutexSecurity` denies or fails to grant some access rights to the current user. However, if the current user attempts to get another object to represent the same named mutex, using either a constructor or the method, Windows access control security is applied. - If the named mutex has already been created with access control security, and the caller does not have , an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. + If the named mutex has already been created with access control security and the caller does not have , an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. In this case, `createdNew` is always `true`. @@ -625,13 +692,13 @@ There was some other error. The `HResult` property may provide more information. ]]> - 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. + is invalid. This can be for various reasons, including some restrictions that might 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. +There was some other error. The `HResult` property might provide more information. Windows only: specified an unknown namespace. See Object Names for more information. - The is too long. Length restrictions may depend on the operating system or configuration. + The is too long. Length restrictions might depend on the operating system or configuration. The named mutex exists and has access control security, but the user does not have . A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. @@ -663,12 +730,45 @@ There was some other error. The `HResult` property may provide more information. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. + to give the calling thread initial ownership of the named system mutex if the named system mutex is created as a result of this call; otherwise, . + The name, if the synchronization object is to be shared with other processes; otherwise, or an empty string. The name is case-sensitive. + The scope options for the named system mutex. Defaults to access limited to current user and current session only. The specified options might affect the namespace for the name and access to the underlying system mutex object. + When this method returns, contains a Boolean that is if a local mutex was created (that is, if is or an empty string) or if the specified named system mutex was created; contains if the specified named system mutex already existed. This parameter is passed uninitialized. + Initializes a new instance of the class with a Boolean value that indicates whether the calling thread should have initial ownership of the mutex, a string that is the name of the mutex, options to set user-scope and session-scope access, and a Boolean value that, when the method returns, indicates whether the calling thread was granted initial ownership of the mutex. + + method. + +This constructor initializes a object that represents a named system mutex. You can create multiple objects that represent the same named system mutex. + +If the named mutex has already been created with access control security and the caller does not have rights, an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. + +If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. In this case, `createdNew` is always `true`. + +Because they are system-wide, named mutexes can be used to coordinate resource use across process boundaries. + +The `options` parameter can be provided to specify whether the named mutex is accessible to the current user only or to all users. It also allows you to specify whether the named mutex is accessible to processes in the current session only or to all sessions. For more information, see . + + ]]> + + The named mutex exists and has access control security, but the user does not have . + + is invalid. This can be for various reasons, including some restrictions that might 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 might provide more information. + Windows only: specified an unknown namespace. See Object Names for more information. + The is too long. Length restrictions might depend on the operating system or configuration. + A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. + -or- + +An object with the specified exists, but the specified are not compatible with the existing object's options. + Managed Threading + Mutexes @@ -839,13 +939,13 @@ There was some other error. The `HResult` property may provide more information. is . A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. In some cases, this exception may be thrown for invalid names. - 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. + is invalid. This can be for various reasons, including some restrictions that might 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. +There was some other error. The `HResult` property might provide more information. Windows only: specified an unknown namespace. See Object Names for more information. - The is too long. Length restrictions may depend on the operating system or configuration. + The is too long. Length restrictions might depend on the operating system or configuration. The named mutex exists, but the user does not have the security access required to use it. @@ -928,13 +1028,13 @@ There was some other error. The `HResult` property may provide more information. is . A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. In some cases, this exception may be thrown for invalid names. - 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. + is invalid. This can be for various reasons, including some restrictions that might 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. +There was some other error. The `HResult` property might provide more information. Windows only: specified an unknown namespace. See Object Names for more information. - The is too long. Length restrictions may depend on the operating system or configuration. + The is too long. Length restrictions might depend on the operating system or configuration. The named mutex exists, but the user does not have the desired security access. @@ -964,11 +1064,41 @@ There was some other error. The `HResult` property may provide more information. - To be added. - To be added. - To be added. - To be added. - To be added. + The name of the synchronization object to be shared with other processes. The name is case-sensitive. + The scope options for the named system mutex. Defaults to access limited to current user and current session only. The specified options might affect the namespace for the name and access to the underlying system mutex object. + Opens the specified named mutex, if it already exists. If the options are set to the current user only, the object's access controls are verified for the calling user. + An object that represents the named system mutex. + + method tries to open the specified named system mutex. To create the system mutex when it does not already exist, use one of the constructors that has a `name` parameter. + +Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system mutex. + +This method does not request ownership of the mutex. + + ]]> + + + is an empty string. + + is . + A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. In some cases, this exception may be thrown for invalid names. + +-or- + +An object with the specified exists, but the specified are not compatible with the existing object's options. + + is invalid. This can be for various reasons, including some restrictions that might 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 might provide more information. + Windows only: specified an unknown namespace. See Object Names for more information. + The is too long. Length restrictions might depend on the operating system or configuration. + The named mutex exists, but the user does not have the security access required to use it. @@ -1195,7 +1325,7 @@ There was some other error. The `HResult` property may provide more information. When this method returns, contains a object that represents the named mutex if the call succeeded, or if the call failed. This parameter is treated as uninitialized. Opens the specified named mutex, if it already exists, and returns a value that indicates whether the operation succeeded. - if the named mutex was opened successfully; otherwise, . In some cases, may be returned for invalid names. + if the named mutex was opened successfully; otherwise, . In some cases, might be returned for invalid names. is . - 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. For some invalid names, the method may return instead. + is invalid. This can be for various reasons, including some restrictions that might 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. For some invalid names, the method may return instead. -or- -There was some other error. The `HResult` property may provide more information. - The is too long. Length restrictions may depend on the operating system or configuration. +There was some other error. The `HResult` property might provide more information. + The is too long. Length restrictions might depend on the operating system or configuration. The named mutex exists, but the user does not have the security access required to use it. @@ -1272,7 +1402,7 @@ There was some other error. The `HResult` property may provide more information. When this method returns, contains a object that represents the named mutex if the call succeeded, or if the call failed. This parameter is treated as uninitialized. Opens the specified named mutex, if it already exists, with the desired security access, and returns a value that indicates whether the operation succeeded. - if the named mutex was opened successfully; otherwise, . In some cases, may be returned for invalid names. + if the named mutex was opened successfully; otherwise, . In some cases, might be returned for invalid names. is . - 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. For some invalid names, the method may return instead. + is invalid. This can be for various reasons, including some restrictions that might 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. For some invalid names, the method may return instead. -or- -There was some other error. The `HResult` property may provide more information. - The is too long. Length restrictions may depend on the operating system or configuration. +There was some other error. The `HResult` property might provide more information. + The is too long. Length restrictions might depend on the operating system or configuration. The named mutex exists, but the user does not have the security access required to use it. @@ -1349,12 +1479,39 @@ There was some other error. The `HResult` property may provide more information. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. + The name of the synchronization object to be shared with other processes. The name is case-sensitive. + The scope options for the named system mutex. Defaults to access limited to current user and current session only. The specified options might affect the namespace for the name and access to the underlying system mutex object. + When this method returns, contains a object that represents the named mutex if the call succeeded, or if the call failed. This parameter is treated as uninitialized. + Opens the specified named mutex, if it already exists, and returns a value that indicates whether the operation succeeded. If the options are set to the current user only, the object's access controls are verified for the calling user. + + if the named mutex was opened successfully; otherwise, . In some cases, might be returned for invalid names. + + constructors that has a `name` parameter. + +If you are uncertain whether a named mutex exists, use this method overload instead of the method overload, which throws an exception if the mutex does not exist. + +Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system mutex. + +This method does not request ownership of the mutex. + + ]]> + + + is an empty string. + + is . + + is invalid. This can be for various reasons, including some restrictions that might 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. For some invalid names, the method may return instead. + +-or- + +There was some other error. The `HResult` property might provide more information. + The is too long. Length restrictions might depend on the operating system or configuration. + The named mutex exists, but the user does not have the security access required to use it. diff --git a/xml/System.Threading/NamedWaitHandleOptions.xml b/xml/System.Threading/NamedWaitHandleOptions.xml index 21d538be3c8..a72d0dd3515 100644 --- a/xml/System.Threading/NamedWaitHandleOptions.xml +++ b/xml/System.Threading/NamedWaitHandleOptions.xml @@ -14,8 +14,16 @@ - To be added. - To be added. + Represents a set of options for named synchronization objects that are wait handles and can be shared between processes, such as , , and . + + , , and . + +As an alternative to the methods that accept a parameter to set the scope, methods that only take a `name` parameter can prefix the parameter with `Global\` or `Local\` to specify a namespace. When the `Global` namespace is specified, the synchronization object can be shared with any processes on the system. When the `Local` namespace is specified, which is also the default when no namespace is specified, the synchronization object can be shared with processes in the same session. On Windows, a session is a login session, and services typically run in a different non-interactive session. On Unix-like operating systems, each shell has its own session. Session-local synchronization objects might be appropriate for synchronizing between processes with a parent/child relationship where they all run in the same session. For more information about synchronization object names on Windows, see [Object Names](https://learn.microsoft.com/windows/win32/sync/object-names). + + ]]> + @@ -34,9 +42,22 @@ System.Boolean - To be added. - To be added. - To be added. + Gets or sets a value that indicates whether the named synchronization object is limited in access to the current session. + + if the named synchronization object is limited in access to the current session; otherwise, . The default is . + + + @@ -55,9 +76,20 @@ System.Boolean - To be added. - To be added. - To be added. + Gets or sets a value that indicates whether the named synchronization object is limited in access to the current user. + + if the named synchronization object is limited in access to the current user; otherwise, . The default is . + + + diff --git a/xml/System.Threading/Semaphore.xml b/xml/System.Threading/Semaphore.xml index fa1d8b86095..5b2d0705b08 100644 --- a/xml/System.Threading/Semaphore.xml +++ b/xml/System.Threading/Semaphore.xml @@ -274,11 +274,11 @@ is less than 0. - 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. + is invalid. This can be for various reasons, including some restrictions that might 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. +There was some other error. The `HResult` property might provide more information. Windows only: specified an unknown namespace. See Object Names for more information. The is too long. Length restrictions may depend on the operating system or configuration. The named semaphore exists and has access control security, and the user does not have . @@ -383,11 +383,11 @@ There was some other error. The `HResult` property may provide more information. is less than 0. - 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. + is invalid. This can be for various reasons, including some restrictions that might 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. +There was some other error. The `HResult` property might provide more information. Windows only: specified an unknown namespace. See Object Names for more information. The is too long. Length restrictions may depend on the operating system or configuration. The named semaphore exists and has access control security, and the user does not have . @@ -421,12 +421,58 @@ There was some other error. The `HResult` property may provide more information. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. + The initial number of requests for the semaphore that can be satisfied concurrently. + The maximum number of requests for the semaphore that can be satisfied concurrently. + The name, if the synchronization object is to be shared with other processes; otherwise, or an empty string. The name is case-sensitive. + The scope options for the named semaphore. Defaults to access limited to current user and current session only. The specified options might affect the namespace for the name and access to the underlying semaphore object. + Initializes a new instance of the class, specifying the initial number of entries and the maximum number of concurrent entries, and optionally specifying the name of a system semaphore object and options to set user-scope and session-scope access. + + object that represents a named system semaphore. You can create multiple 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 unless `options` specifies access limited to the current user and the synchronization object is not compatible with it, in which case a `WaitHandleCannotBeOpenedException` is thrown. If a synchronization object of a different type already exists in the namespace, a `WaitHandleCannotBeOpenedException` is thrown as well. Otherwise, a new synchronization object is created. + +If the named system semaphore does not exist, it is created with the initial count and maximum count specified by `initialCount` and `maximumCount`. If the named system semaphore already exists, `initialCount` and `maximumCount` are not used, although invalid values still cause exceptions. If you need to determine whether or not a named system semaphore was created, use the constructor overload instead. + +> [!IMPORTANT] +> When you use this constructor overload, the recommended practice is to specify the same number for `initialCount` and `maximumCount`. If `initialCount` is less than `maximumCount`, and a named system semaphore is created, the effect is the same as if the current thread had called (`maximumCount` minus `initialCount`) times. However, with this constructor overload, there's no way to determine whether a named system semaphore was created. + +If you specify `null` or an empty string for `name`, a local semaphore is created, as if you had called the 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 method. The method attempts to open an existing named semaphore, and throws an exception if the system semaphore does not exist. + +On Windows, `options` can be provided to specify whether the named semaphore is accessible to the current user only or to all users. It also allows you to specify whether the named semaphore is accessible to processes in the current session only or to all sessions. For more information, see . + +> [!CAUTION] +> On Unix-based operating systems, the `options` parameter has no effect as named semaphores are not supported. + + ]]> + + + is greater than . + +-or- + + is less than 0. + + is invalid. This can be for various reasons, including some restrictions that might 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 might provide more information. + Windows only: specified an unknown namespace. See Object Names for more information. + The is too long. Length restrictions may depend on the operating system or configuration. + The named semaphore exists and has access control security, and the user does not have . + A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. + + -or- + +An object with the specified exists, but the specified are not compatible with the existing object's options. + Managed Threading + Semaphore @@ -516,11 +562,11 @@ There was some other error. The `HResult` property may provide more information. is less than 0. The named semaphore exists and has access control security, and the user does not have . - 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. + is invalid. This can be for various reasons, including some restrictions that might 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. +There was some other error. The `HResult` property might provide more information. Windows only: specified an unknown namespace. See Object Names for more information. The is too long. Length restrictions may depend on the operating system or configuration. A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. @@ -554,13 +600,56 @@ There was some other error. The `HResult` property may provide more information. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. + The initial number of requests for the semaphore that can be satisfied concurrently. + The maximum number of requests for the semaphore that can be satisfied concurrently. + The name, if the synchronization object is to be shared with other processes; otherwise, or an empty string. The name is case-sensitive. + The scope options for the named semaphore. Defaults to access limited to current user and current session only. The specified options might affect the namespace for the name and access to the underlying semaphore object. + When this method returns, contains if a local semaphore was created (that is, if is or an empty string) or if the specified named system semaphore was created; contains if the specified named system semaphore already existed. This parameter is passed uninitialized. + Initializes a new instance of the class, specifying the initial number of entries and the maximum number of concurrent entries, optionally specifying the name of a system semaphore object and options to set user-scope and session-scope access, and specifying a variable that receives a value indicating whether a new system semaphore was created. + + object that represents a named system semaphore. You can create multiple objects that represent the same named system semaphore. + +If the named system semaphore does not exist, it is created with the initial count and maximum count specified by `initialCount` and `maximumCount`. If the named system semaphore already exists, `initialCount` and `maximumCount` are not used, although invalid values still cause exceptions. Use the `createdNew` parameter to determine whether the system semaphore was created by this constructor. + +If `initialCount` is less than `maximumCount`, and `createdNew` is `true`, the effect is the same as if the current thread had called (`maximumCount` minus `initialCount`) times. + +If you specify `null` or an empty string for `name`, a local semaphore is created, as if you had called the constructor overload. In this case, `createdNew` is always `true`. + +Because named semaphores are visible throughout the operating system, they can be used to coordinate resource use across process boundaries. + +On Windows, `options` can be provided to specify whether the named semaphore is accessible to the current user only or to all users. It also allows you to specify whether the named semaphore is accessible to processes in the current session only or to all sessions. For more information, see . + +> [!CAUTION] +> On Unix-based operating systems, the `options` parameter has no effect as named semaphores are not supported. + + ]]> + + + is greater than . + +-or- + + is less than 0. + + is invalid. This can be for various reasons, including some restrictions that might 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 might provide more information. + Windows only: specified an unknown namespace. See Object Names for more information. + The is too long. Length restrictions may depend on the operating system or configuration. + The named semaphore exists and has access control security, and the user does not have . + A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. + + -or- + +An object with the specified exists, but the specified are not compatible with the existing object's options. + Managed Threading + Semaphore @@ -730,11 +819,11 @@ There was some other error. The `HResult` property may provide more information. is . A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. In some cases, this exception may be thrown for invalid names. - 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. + is invalid. This can be for various reasons, including some restrictions that might 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. +There was some other error. The `HResult` property might provide more information. The is too long. Length restrictions may depend on the operating system or configuration. The named semaphore exists, but the user does not have the security access required to use it. Managed Threading @@ -812,11 +901,11 @@ There was some other error. The `HResult` property may provide more information. is . A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. In some cases, this exception may be thrown for invalid names. - 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. + is invalid. This can be for various reasons, including some restrictions that might 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. +There was some other error. The `HResult` property might provide more information. The is too long. Length restrictions may depend on the operating system or configuration. The named semaphore exists, but the user does not have the desired security access rights. Managed Threading @@ -855,11 +944,40 @@ There was some other error. The `HResult` property may provide more information. - To be added. - To be added. - To be added. - To be added. - To be added. + 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. + The scope options for the named semaphore. Defaults to access limited to current user and current session only. The specified options might affect the namespace for the name and access to the underlying semaphore object. + Opens the specified named semaphore, if it already exists. If the options are set to the current user only, the object's access controls are verified for the calling user. + An object that represents the named system semaphore. + + method tries to open the specified named semaphore. To create the system semaphore when it does not already exist, use one of the constructors that has a `name` parameter. + +Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system semaphore. + + ]]> + + + is an empty string. + + is . + A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. + +-or- + +An object with the specified exists, but the specified are not compatible with the existing object's options. + + is invalid. This can be for various reasons, including some restrictions that might 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 might provide more information. + The is too long. Length restrictions may depend on the operating system or configuration. + The named semaphore exists, but the user does not have the security access required to use it. + Managed Threading + Semaphore @@ -1207,11 +1325,11 @@ There was some other error. The `HResult` property may provide more information. is . - 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. For some invalid names, the method may return instead. + is invalid. This can be for various reasons, including some restrictions that might 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. For some invalid names, the method may return instead. -or- -There was some other error. The `HResult` property may provide more information. +There was some other error. The `HResult` property might provide more information. The is too long. Length restrictions may depend on the operating system or configuration. The named semaphore exists, but the user does not have the security access required to use it. @@ -1276,11 +1394,11 @@ There was some other error. The `HResult` property may provide more information. is . - 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. For some invalid names, the method may return instead. + is invalid. This can be for various reasons, including some restrictions that might 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. For some invalid names, the method may return instead. -or- -There was some other error. The `HResult` property may provide more information. +There was some other error. The `HResult` property might provide more information. The is too long. Length restrictions may depend on the operating system or configuration. The named semaphore exists, but the user does not have the security access required to use it. @@ -1329,12 +1447,35 @@ There was some other error. The `HResult` property may provide more information. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. + 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. + The scope options for the named semaphore. Defaults to access limited to current user and current session only. The specified options might affect the namespace for the name and access to the underlying semaphore object. + When this method returns, contains a object that represents the named semaphore if the call succeeded, or if the call failed. This parameter is treated as uninitialized. + Opens the specified named semaphore, if it already exists, and returns a value that indicates whether the operation succeeded. If the options are set to the current user only, the object's access controls are verified for the calling user. + + if the named semaphore was opened successfully; otherwise, . In some cases, may be returned for invalid names. + + constructors that has a `name` parameter. + +If you are uncertain whether a named semaphore exists, use this method overload instead of the method overload, which throws an exception if the semaphore does not exist. + + ]]> + + + is an empty string. + + is . + + is invalid. This can be for various reasons, including some restrictions that might 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. For some invalid names, the method may return instead. + +-or- + +There was some other error. The `HResult` property might provide more information. + The is too long. Length restrictions may depend on the operating system or configuration. + The named semaphore exists, but the user does not have the security access required to use it.