Mutex Class
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
A synchronization primitive that can also be used for interprocess synchronization.
public ref class Mutex sealed : System::Threading::WaitHandlepublic sealed class Mutex : System.Threading.WaitHandle[System.Runtime.InteropServices.ComVisible(true)]
public sealed class Mutex : System.Threading.WaitHandletype Mutex = class
inherit WaitHandle[<System.Runtime.InteropServices.ComVisible(true)>]
type Mutex = class
inherit WaitHandlePublic NotInheritable Class Mutex
Inherits WaitHandle- Inheritance
- Inheritance
- Attributes
Examples
This example shows how a local Mutex object is used to synchronize access to a protected resource. Because each calling thread is blocked until it acquires ownership of the mutex, it must call the ReleaseMutex method to release ownership of the mutex.
using System;
using System.Threading;
class Example
{
// Create a new Mutex. The creating thread does not own the mutex.
private static Mutex mut = new Mutex();
private const int numIterations = 1;
private const int numThreads = 3;
static void Main()
{
// Create the threads that will use the protected resource.
for(int i = 0; i < numThreads; i++)
{
Thread newThread = new Thread(new ThreadStart(ThreadProc));
newThread.Name = String.Format("Thread{0}", i + 1);
newThread.Start();
}
// The main thread exits, but the application continues to
// run until all foreground threads have exited.
}
private static void ThreadProc()
{
for(int i = 0; i < numIterations; i++)
{
UseResource();
}
}
// This method represents a resource that must be synchronized
// so that only one thread at a time can enter.
private static void UseResource()
{
// Wait until it is safe to enter.
Console.WriteLine("{0} is requesting the mutex",
Thread.CurrentThread.Name);
mut.WaitOne();
Console.WriteLine("{0} has entered the protected area",
Thread.CurrentThread.Name);
// Place code to access non-reentrant resources here.
// Simulate some work.
Thread.Sleep(500);
Console.WriteLine("{0} is leaving the protected area",
Thread.CurrentThread.Name);
// Release the Mutex.
mut.ReleaseMutex();
Console.WriteLine("{0} has released the mutex",
Thread.CurrentThread.Name);
}
}
// The example displays output like the following:
// Thread1 is requesting the mutex
// Thread2 is requesting the mutex
// Thread1 has entered the protected area
// Thread3 is requesting the mutex
// Thread1 is leaving the protected area
// Thread1 has released the mutex
// Thread3 has entered the protected area
// Thread3 is leaving the protected area
// Thread3 has released the mutex
// Thread2 has entered the protected area
// Thread2 is leaving the protected area
// Thread2 has released the mutex
Imports System.Threading
Module Example
' Create a new Mutex. The creating thread does not own the mutex.
Private mut As New Mutex()
Private Const numIterations As Integer = 1
Private Const numThreads As Integer = 3
Public Sub Main()
' Create the threads that will use the protected resource.
For i As Integer = 0 To numThreads - 1
Dim newThread As New Thread(AddressOf ThreadProc)
newThread.Name = String.Format("Thread{0}", i + 1)
newThread.Start()
Next
' The main thread exits, but the application continues to
' run until all foreground threads have exited.
End Sub
Private Sub ThreadProc()
For i As Integer = 0 To numIterations - 1
UseResource()
Next
End Sub
' This method represents a resource that must be synchronized
' so that only one thread at a time can enter.
Private Sub UseResource()
' Wait until it is safe to enter.
Console.WriteLine("{0} is requesting the mutex",
Thread.CurrentThread.Name)
mut.WaitOne()
Console.WriteLine("{0} has entered the protected area",
Thread.CurrentThread.Name)
' Place code to access non-reentrant resources here.
' Simulate some work.
Thread.Sleep(500)
Console.WriteLine("{0} is leaving the protected area",
Thread.CurrentThread.Name)
' Release the Mutex.
mut.ReleaseMutex()
Console.WriteLine("{0} has released the mutex",
Thread.CurrentThread.Name)
End Sub
End Module
' The example displays output like the following:
' Thread1 is requesting the mutex
' Thread2 is requesting the mutex
' Thread1 has entered the protected area
' Thread3 is requesting the mutex
' Thread1 is leaving the protected area
' Thread1 has released the mutex
' Thread3 has entered the protected area
' Thread3 is leaving the protected area
' Thread3 has released the mutex
' Thread2 has entered the protected area
' Thread2 is leaving the protected area
' Thread2 has released the mutex
In the following example, each thread calls the WaitOne(Int32) method to acquire the mutex. If the time-out interval elapses, the method returns false, and the thread neither acquires the mutex nor gains access to the resource the mutex protects. The ReleaseMutex method is called only by the thread that acquires the mutex.
using System;
using System.Threading;
class Example
{
// Create a new Mutex. The creating thread does not own the mutex.
private static Mutex mut = new Mutex();
private const int numIterations = 1;
private const int numThreads = 3;
static void Main()
{
Example ex = new Example();
ex.StartThreads();
}
private void StartThreads()
{
// Create the threads that will use the protected resource.
for(int i = 0; i < numThreads; i++)
{
Thread newThread = new Thread(new ThreadStart(ThreadProc));
newThread.Name = String.Format("Thread{0}", i + 1);
newThread.Start();
}
// The main thread returns to Main and exits, but the application continues to
// run until all foreground threads have exited.
}
private static void ThreadProc()
{
for(int i = 0; i < numIterations; i++)
{
UseResource();
}
}
// This method represents a resource that must be synchronized
// so that only one thread at a time can enter.
private static void UseResource()
{
// Wait until it is safe to enter, and do not enter if the request times out.
Console.WriteLine("{0} is requesting the mutex", Thread.CurrentThread.Name);
if (mut.WaitOne(1000)) {
Console.WriteLine("{0} has entered the protected area",
Thread.CurrentThread.Name);
// Place code to access non-reentrant resources here.
// Simulate some work.
Thread.Sleep(5000);
Console.WriteLine("{0} is leaving the protected area",
Thread.CurrentThread.Name);
// Release the Mutex.
mut.ReleaseMutex();
Console.WriteLine("{0} has released the mutex",
Thread.CurrentThread.Name);
}
else {
Console.WriteLine("{0} will not acquire the mutex",
Thread.CurrentThread.Name);
}
}
~Example()
{
mut.Dispose();
}
}
// The example displays output like the following:
// Thread1 is requesting the mutex
// Thread1 has entered the protected area
// Thread2 is requesting the mutex
// Thread3 is requesting the mutex
// Thread2 will not acquire the mutex
// Thread3 will not acquire the mutex
// Thread1 is leaving the protected area
// Thread1 has released the mutex
Imports System.Threading
Class Example
' Create a new Mutex. The creating thread does not own the mutex.
Private mut As New Mutex()
Private Const numIterations As Integer = 1
Private Const numThreads As Integer = 3
Public Shared Sub Main()
Dim ex As New Example()
ex.StartThreads()
End Sub
Private Sub StartThreads()
' Create the threads that will use the protected resource.
For i As Integer = 0 To numThreads - 1
Dim newThread As New Thread(AddressOf ThreadProc)
newThread.Name = String.Format("Thread{0}", i + 1)
newThread.Start()
Next
' The main thread returns to Main and exits, but the application continues to
' run until all foreground threads have exited.
End Sub
Private Sub ThreadProc()
For i As Integer = 0 To numIterations - 1
UseResource()
Next
End Sub
' This method represents a resource that must be synchronized
' so that only one thread at a time can enter.
Private Sub UseResource()
' Wait until it is safe to enter.
Console.WriteLine("{0} is requesting the mutex",
Thread.CurrentThread.Name)
If mut.WaitOne(1000) Then
Console.WriteLine("{0} has entered the protected area",
Thread.CurrentThread.Name)
' Place code to access non-reentrant resources here.
' Simulate some work.
Thread.Sleep(5000)
Console.WriteLine("{0} is leaving the protected area",
Thread.CurrentThread.Name)
' Release the Mutex.
mut.ReleaseMutex()
Console.WriteLine("{0} has released the mutex",
Thread.CurrentThread.Name)
Else
Console.WriteLine("{0} will not acquire the mutex",
Thread.CurrentThread.Name)
End If
End Sub
Protected Overrides Sub Finalize()
mut.Dispose()
End Sub
End Class
' The example displays output like the following:
' Thread1 is requesting the mutex
' Thread1 has entered the protected area
' Thread2 is requesting the mutex
' Thread3 is requesting the mutex
' Thread2 will not acquire the mutex
' Thread3 will not acquire the mutex
' Thread1 is leaving the protected area
' Thread1 has released the mutex
Remarks
When two or more threads need to access a shared resource at the same time, the system needs a synchronization mechanism to ensure that only one thread at a time uses the resource. Mutex is a synchronization primitive that grants exclusive access to the shared resource to only one thread. If a thread acquires a mutex, the second thread that wants to acquire that mutex is suspended until the first thread releases the mutex.
Important
This type implements the IDisposable interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its Dispose method in a try/catch block. To dispose of it indirectly, use a language construct such as using (in C#) or Using (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the IDisposable interface topic.
You can use the WaitHandle.WaitOne method to request ownership of a mutex. The calling thread blocks until one of the following occurs:
The mutex is signaled to indicate that it is not owned. When this happens, the WaitOne method returns
true, and the calling thread assumes ownership of the mutex and accesses the resource protected by the mutex. When it has finished accessing the resource, the thread must call the ReleaseMutex method to release ownership of the mutex. The first example in the Examples section illustrates this pattern.The time-out interval specified in the call to a WaitOne method that has a
millisecondsTimeoutortimeoutparameter has elapsed. When this happens, the WaitOne method returnsfalse, and the calling thread makes no further attempt to acquire ownership of the mutex. In this case, you should structure your code so that access to the resource that is protected by the mutex is denied to the calling thread. Because the thread never acquired ownership of the mutex, it must not call the ReleaseMutex method. The second example in the Examples section illustrates this pattern.
The Mutex class enforces thread identity, so a mutex can be released only by the thread that acquired it. By contrast, the Semaphore class does not enforce thread identity. A mutex can also be passed across application domain boundaries.
The thread that owns a mutex can request the same mutex in repeated calls to WaitOne without blocking its execution. However, the thread must call the ReleaseMutex method the same number of times to release ownership of the mutex.
Because the Mutex class inherits from WaitHandle, you can also call the static WaitHandle.WaitAll and WaitHandle.WaitAny methods to synchronize access to a protected resource.
If a thread terminates while owning a mutex, the mutex is said to be abandoned. The state of the mutex is set to signaled, and the next waiting thread gets ownership. Beginning in version 2.0 of the .NET Framework, an AbandonedMutexException is thrown in the next thread that acquires the abandoned mutex. Before version 2.0 of the .NET Framework, no exception was thrown.
Caution
An abandoned mutex often indicates a serious error in the code. When a thread exits without releasing the mutex, the data structures protected by the mutex might not be in a consistent state. The next thread to request ownership of the mutex can handle this exception and proceed, if the integrity of the data structures can be verified.
In the case of a system-wide mutex, an abandoned mutex might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager).
Mutexes are of two types: local mutexes, which are unnamed, and named system mutexes. A local mutex exists only within your process. It can be used by any thread in your process that has a reference to the Mutex object that represents the mutex. Each unnamed Mutex object represents a separate local mutex.
Named system mutexes are visible throughout the operating system, and can be used to synchronize the activities of processes. You can create a Mutex object that represents a named system mutex by using a constructor that accepts a name. The operating-system object can be created at the same time, or it can exist before the creation of the Mutex object. You can create multiple Mutex objects that represent the same named system mutex, and you can use the OpenExisting method to open an existing named system mutex.
Note
On a server that is running Terminal Services, a named system mutex can have two levels of visibility. If its name begins with the prefix Global\, the mutex is visible in all terminal server sessions. If its name begins with the prefix Local\, the mutex is visible only in the terminal server session where it was created. In that case, a separate mutex with the same name can exist in each of the other terminal server sessions on the server. If you do not specify a prefix when you create a named mutex, it takes the prefix Local\. Within a terminal server session, two mutexes whose names differ only by their prefixes are separate mutexes, and both are visible to all processes in the terminal server session. That is, the prefix names Global\ and Local\ describe the scope of the mutex name relative to terminal server sessions, not relative to processes.
Caution
By default, a named mutex is not restricted to the user that created it. Other users may be able to open and use the mutex, including interfering with the mutex by entering the mutex and not exiting it. On Unix-like operating systems, the file system is used in the implementation of named mutexes, and other users may be able to interfere with named mutexes in more significant ways. On Windows, to restrict access to specific users, you can use a constructor overload or MutexAcl and pass in a MutexSecurity when creating the named mutex. On Unix-like operating systems, currently there is no way to restrict access to a named mutex. Avoid using named mutexes without access restrictions on systems that might have untrusted users running code.
The backslash (\) is a reserved character in a mutex name. Don't use a backslash (\) in a mutex name except as specified in the note on using mutexes in terminal server sessions. Otherwise, a DirectoryNotFoundException may be thrown, even though the name of the mutex represents an existing file.
Constructors
| Mutex() |
Initializes a new instance of the Mutex class with default properties. |
| Mutex(Boolean, String, Boolean, MutexSecurity) |
Initializes a new instance of the Mutex 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, a Boolean variable that, when the method returns, indicates whether the calling thread was granted initial ownership of the mutex, and the access control security to be applied to the named mutex. |
| Mutex(Boolean, String, Boolean) |
Initializes a new instance of the Mutex 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 a Boolean value that, when the method returns, indicates whether the calling thread was granted initial ownership of the mutex. |
| Mutex(Boolean, String) |
Initializes a new instance of the Mutex class with a Boolean value that indicates whether the calling thread should have initial ownership of the mutex, and a string that is the name of the mutex. |
| Mutex(Boolean) |
Initializes a new instance of the Mutex class with a Boolean value that indicates whether the calling thread should have initial ownership of the mutex. |
Fields
| WaitTimeout |
Indicates that a WaitAny(WaitHandle[], Int32, Boolean) operation timed out before any of the wait handles were signaled. This field is constant. (Inherited from WaitHandle) |
Properties
| Handle |
Obsolete.
Obsolete.
Gets or sets the native operating system handle. (Inherited from WaitHandle) |
| SafeWaitHandle |
Gets or sets the native operating system handle. (Inherited from WaitHandle) |
Methods
| Close() |
Releases all resources held by the current WaitHandle. (Inherited from WaitHandle) |
| CreateObjRef(Type) |
Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object. (Inherited from MarshalByRefObject) |
| Dispose() |
Releases all resources used by the current instance of the WaitHandle class. (Inherited from WaitHandle) |
| Dispose(Boolean) |
When overridden in a derived class, releases the unmanaged resources used by the WaitHandle, and optionally releases the managed resources. (Inherited from WaitHandle) |
| Equals(Object) |
Determines whether the specified object is equal to the current object. (Inherited from Object) |
| GetAccessControl() |
Gets a MutexSecurity object that represents the access control security for the named mutex. |
| GetHashCode() |
Serves as the default hash function. (Inherited from Object) |
| GetLifetimeService() |
Obsolete.
Retrieves the current lifetime service object that controls the lifetime policy for this instance. (Inherited from MarshalByRefObject) |
| GetType() |
Gets the Type of the current instance. (Inherited from Object) |
| InitializeLifetimeService() |
Obsolete.
Obtains a lifetime service object to control the lifetime policy for this instance. (Inherited from MarshalByRefObject) |
| MemberwiseClone() |
Creates a shallow copy of the current Object. (Inherited from Object) |
| MemberwiseClone(Boolean) |
Creates a shallow copy of the current MarshalByRefObject object. (Inherited from MarshalByRefObject) |
| OpenExisting(String, MutexRights) |
Opens the specified named mutex, if it already exists, with the desired security access. |
| OpenExisting(String) |
Opens the specified named mutex, if it already exists. |
| ReleaseMutex() |
Releases the Mutex once. |
| SetAccessControl(MutexSecurity) |
Sets the access control security for a named system mutex. |
| ToString() |
Returns a string that represents the current object. (Inherited from Object) |
| TryOpenExisting(String, Mutex) |
Opens the specified named mutex, if it already exists, and returns a value that indicates whether the operation succeeded. |
| TryOpenExisting(String, MutexRights, Mutex) |
Opens the specified named mutex, if it already exists, with the desired security access, and returns a value that indicates whether the operation succeeded. |
| WaitOne() |
Blocks the current thread until the current WaitHandle receives a signal. (Inherited from WaitHandle) |
| WaitOne(Int32, Boolean) |
Blocks the current thread until the current WaitHandle receives a signal, using a 32-bit signed integer to specify the time interval and specifying whether to exit the synchronization domain before the wait. (Inherited from WaitHandle) |
| WaitOne(Int32) |
Blocks the current thread until the current WaitHandle receives a signal, using a 32-bit signed integer to specify the time interval in milliseconds. (Inherited from WaitHandle) |
| WaitOne(TimeSpan, Boolean) |
Blocks the current thread until the current instance receives a signal, using a TimeSpan to specify the time interval and specifying whether to exit the synchronization domain before the wait. (Inherited from WaitHandle) |
| WaitOne(TimeSpan) |
Blocks the current thread until the current instance receives a signal, using a TimeSpan to specify the time interval. (Inherited from WaitHandle) |
Explicit Interface Implementations
| IDisposable.Dispose() |
This API supports the product infrastructure and is not intended to be used directly from your code. Releases all resources used by the WaitHandle. (Inherited from WaitHandle) |
Extension Methods
| GetAccessControl(Mutex) |
Returns the security descriptors for the specified |
| SetAccessControl(Mutex, MutexSecurity) |
Sets the security descriptors for the specified mutex. |
| GetSafeWaitHandle(WaitHandle) |
Gets the safe handle for a native operating system wait handle. |
| SetSafeWaitHandle(WaitHandle, SafeWaitHandle) |
Sets a safe handle for a native operating system wait handle. |
Applies to
Thread Safety
This type is thread safe.
