API Proposal: Port OpenExisting and TryOpenExisting methods for EventWaitHandle/Mutex/Semaphore from .NET Framework

[carlossanlop]

Background and Motivation

We have customers showing interest in getting the TryOpenExisting methods that take a *Rights parameter ported from .NET Framework (EventWaitHandleRights, MutexRights, SemaphoreRights).

We currently only provide the OpenExisting and TryOpenExisting methods that take a name string as the only parameter, but none that allow specifying rights.

In 3.1, we approved this proposal to port from .NET Framework the methods that could create EventWaitHandle, Mutex and Semaphore objects and take an ACL security object.

Since the original .NET Framework Create methods were static and Windows-specific, we decided to port them into 3.1 inside new static, Windows-specific and ACL-specific classes inside the System.Threading.AccessControl assembly and as part of the System.Threading namespace.

Since the OpenExisting and TryOpenExisting methods are also static in .NET Framework, we could reuse these classes and add the new methods there.

Proposed APIs

namespace System.Threading
{
    public static partial class EventWaitHandleAcl
    {
        public static EventWaitHandle OpenExisting(string name, EventWaitHandleRights rights);
        public static bool TryOpenExisting(string name, EventWaitHandleRights rights, out EventWaitHandle result);
    }
    public static partial class MutexAcl
    {
        public static Mutex OpenExisting(string name, MutexRights rights);
        public static bool TryOpenExisting(string name, MutexRights rights, out Mutex result);
    }
    public static partial class SemaphoreAcl
    {
        public static Semaphore OpenExisting(string name, SemaphoreRights rights);
        public static bool TryOpenExisting(string name, SemaphoreRights rights, out Semaphore result);
    }
}

Usage

using System.Security.AccessControl;
using System.Threading;

...

// EventWaitHandle

EventWaitHandle eventWaitHandle1 = EventWaitHandleAcl.OpenExisting("eventWaitHandle", EventWaitHandleRights.FullControl);

if (EventWaitHandleAcl.TryOpenExisting("eventWaitHandle", EventWaitHandleRights.FullControl, out EventWaitHandle eventWaitHandle2)) { /*...*/ }

// Mutex

Mutex mutex1 = MutexAcl.OpenExisting("mutexName", MutexRights.FullControl);

if (MutexAcl.TryOpenExisting("mutexName", MutexRights.FullControl, out Mutex mutex2)) { /*...*/ }

// Semaphore

Semaphore semaphore1 = SemaphoreAcl.OpenExisting("semaphoreName", SemaphoreRights.FullControl);

if (SemaphoreAcl.TryOpenExisting("semaphoreName", MutexRights.FullControl, out Semaphore semaphore2)) { /*...*/ }

Alternative designs

We also have the ThreadingAclExtensions static class in the System.Threading.AccessControl, where we have the GetAccessControl and SetAccessControl static methods defined for EventWaitHandle/Mutex/Semaphore, which is the class that the original 3.1 proposal was suggesting to use for adding the new APIs, but we opted to create the new classes instead.

Risks

Not sure if a risk, but just in case, I thought it was worth pointing out that the System.Threading.AccessControl assembly is a .NET Standard 2.0 OOB package and Windows specific.

runtime/src/libraries/System.Threading.AccessControl/src/System.Threading.AccessControl.csproj

Sources

Links to docs and source code

• EventWaitHandle

  • OpenExisting
    • .NET Framework Docs: https://docs.microsoft.com/en-us/dotnet/api/system.threading.eventwaithandle.openexisting?view=netframework-4.8
    • Reference Source: https://referencesource.microsoft.com/#mscorlib/system/threading/eventwaithandle.cs,178
    • .NET 5.0 Docs: https://docs.microsoft.com/en-us/dotnet/api/system.threading.eventwaithandle.openexisting?view=net-5.0
    • Source.dot.net: https://source.dot.net/#System.Private.CoreLib/EventWaitHandle.cs,32
  • TryOpenExisting
    • .NET Framework Docs: https://docs.microsoft.com/en-us/dotnet/api/system.threading.eventwaithandle.tryopenexisting?view=netframework-4.8
    • Reference Source: https://referencesource.microsoft.com/#mscorlib/system/threading/eventwaithandle.cs,201
    • .NET 5.0 Docs: https://docs.microsoft.com/en-us/dotnet/api/system.threading.eventwaithandle.tryopenexisting?view=net-5.0
    • Source.dot.net: https://source.dot.net/#System.Private.CoreLib/EventWaitHandle.cs,49

• Mutex

  • OpenExisting
    • .NET Framework Docs: https://docs.microsoft.com/en-us/dotnet/api/system.threading.mutex.openexisting?view=netframework-4.8
    • Reference Source: https://referencesource.microsoft.com/#mscorlib/system/threading/mutex.cs,309
    • .NET 5.0 Docs: https://docs.microsoft.com/en-us/dotnet/api/system.threading.mutex.openexisting?view=net-5.0
    • Source.dot.net: https://source.dot.net/#System.Private.CoreLib/Mutex.cs,41
  • TryOpenExisting
    • .NET Framework Docs: https://docs.microsoft.com/en-us/dotnet/api/system.threading.mutex.tryopenexisting?view=netframework-4.8
    • Reference Source: https://referencesource.microsoft.com/#mscorlib/system/threading/mutex.cs,344
    • .NET 5.0 Docs: https://docs.microsoft.com/en-us/dotnet/api/system.threading.mutex.tryopenexisting?view=net-5.0
    • Source.dot.net: https://source.dot.net/#System.Private.CoreLib/Mutex.cs,58

• Semaphore

  • OpenExisting
    • .NET Framework Docs: https://docs.microsoft.com/en-us/dotnet/api/system.threading.semaphore.openexisting?view=netframework-4.8
    • Reference Source: https://referencesource.microsoft.com/#System/sys/system/threading/semaphore.cs,178
    • .NET 5.0 Docs: https://docs.microsoft.com/en-us/dotnet/api/system.threading.semaphore.openexisting?view=net-5.0
    • Source.dot.net: https://source.dot.net/#System.Private.CoreLib/Semaphore.cs,37
  • TryOpenExisting
    • .NET Framework Docs: https://docs.microsoft.com/en-us/dotnet/api/system.threading.semaphore.tryopenexisting?view=netframework-4.8
    • Reference Source: https://referencesource.microsoft.com/#System/sys/system/threading/semaphore.cs,219
    • .NET 5.0 Docs: https://docs.microsoft.com/en-us/dotnet/api/system.threading.semaphore.tryopenexisting?view=net-5.0
    • Source.dot.net: https://source.dot.net/#System.Private.CoreLib/Semaphore.cs,54

[terrajobst]

Video

• Looks good as proposed, follows the pattern

namespace System.Threading
{
    public static partial class EventWaitHandleAcl
    {
        public static EventWaitHandle OpenExisting(string name, EventWaitHandleRights rights);
        public static bool TryOpenExisting(string name, EventWaitHandleRights rights, out EventWaitHandle result);
    }
    public static partial class MutexAcl
    {
        public static Mutex OpenExisting(string name, MutexRights rights);
        public static bool TryOpenExisting(string name, MutexRights rights, out Mutex result);
    }
    public static partial class SemaphoreAcl
    {
        public static Semaphore OpenExisting(string name, SemaphoreRights rights);
        public static bool TryOpenExisting(string name, SemaphoreRights rights, out Semaphore result);
    }
}