Class AsyncCrossProcessMutex

Namespace

Microsoft.VisualStudio.Threading

Assembly

Microsoft.VisualStudio.Threading.dll

A mutex that can be entered asynchronously.

public class AsyncCrossProcessMutex : IDisposable

Inheritance

object

AsyncCrossProcessMutex

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Examples

using AsyncCrossProcessMutex mutex = new("Some-Unique Name"); using (await mutex.EnterAsync()) { // Code that must not execute in parallel with any other thread or process protected by the same named mutex. }

Remarks

This class utilizes the OS mutex synchronization primitive, which is fundamentally thread-affinitized and requires synchronously blocking the thread that will own the mutex. This makes a native mutex unsuitable for use in async methods, where the thread that enters the mutex may not be the same thread that exits it. This class solves that problem by using a private dedicated thread to enter and release the mutex, but otherwise allows its owner to execute async code, switch threads, etc.

Constructors

AsyncCrossProcessMutex(string)

Initializes a new instance of the AsyncCrossProcessMutex class.

public AsyncCrossProcessMutex(string name)

Parameters

name string

A non-empty name for the mutex, which follows standard mutex naming rules. This name will share a namespace with other processes in the system and collisions will result in the processes sharing a single mutex across processes.

Remarks

See the help docs on the underlying Mutex class for more information on the name parameter. Consider when reading that the initiallyOwned parameter for that constructor is always false for this class.

Properties

Name

Gets the name of the mutex.

public string Name { get; }

Property Value

string

Methods

Dispose()

Disposes of the underlying native objects.

public void Dispose()

EnterAsync()

Acquires the mutex asynchronously.

public Task<AsyncCrossProcessMutex.LockReleaser> EnterAsync()

Returns

Task<AsyncCrossProcessMutex.LockReleaser>

A value whose disposal will release the mutex.

Exceptions

TimeoutException

Thrown from the awaited result if the mutex could not be acquired within the specified timeout.

ArgumentOutOfRangeException

Thrown from the awaited result if the timeout is a negative number other than -1 milliseconds, which represents an infinite timeout.

InvalidOperationException

Thrown if called before a prior call to this method has completed, with its releaser disposed if the mutex was entered.

EnterAsync(TimeSpan)

Acquires the mutex asynchronously.

public Task<AsyncCrossProcessMutex.LockReleaser> EnterAsync(TimeSpan timeout)

Parameters

timeout TimeSpan

The maximum time to wait before timing out. Use InfiniteTimeSpan for no timeout, or Zero to acquire the mutex only if it is immediately available.

Returns

Task<AsyncCrossProcessMutex.LockReleaser>

A value whose disposal will release the mutex.

Exceptions

TimeoutException

Thrown from the awaited result if the mutex could not be acquired within the specified timeout.

ArgumentOutOfRangeException

Thrown from the awaited result if the timeout is a negative number other than -1 milliseconds, which represents an infinite timeout.

InvalidOperationException

Thrown if called before a prior call to this method has completed, with its releaser disposed if the mutex was entered.

TryEnterAsync(TimeSpan)

Acquires the mutex asynchronously, allowing for timeouts without throwing exceptions.

public Task<AsyncCrossProcessMutex.LockReleaser?> TryEnterAsync(TimeSpan timeout)

Parameters

timeout TimeSpan

The maximum time to wait before timing out. Use InfiniteTimeSpan for no timeout, or Zero to acquire the mutex only if it is immediately available.

Returns

Task<AsyncCrossProcessMutex.LockReleaser?>

If the mutex was acquired, the result is a value whose disposal will release the mutex. In the event of a timeout, the result in a null value.

Exceptions

ArgumentOutOfRangeException

Thrown from the awaited result if the timeout is a negative number other than -1 milliseconds, which represents an infinite timeout.

InvalidOperationException

Thrown if called before a prior call to this method has completed, with its releaser disposed if the mutex was entered.