Class

# Mutex

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

## Description

A type of `CriticalSection</api/language/threading/criticalsection>` that has operating system-wide scope and is visible to other applications.

## Methods

<div class="rst-class">

table-centered_column_4

</div>

| Name                              | Parameters                               | Returns                            | Shared |
|-----------------------------------|------------------------------------------|------------------------------------|--------|
| `Constructor<mutex.constructor0>` | name As `String</api/data_types/string>` |                                    |        |
| `Enter<mutex.enter>`              |                                          |                                    |        |
| `Leave<mutex.leave>`              |                                          |                                    |        |
| `TryEnter<mutex.tryenter>`        |                                          | `Boolean</api/data_types/boolean>` |        |

## Method descriptions

<div id="mutex.constructor0">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

Mutex.Constructor

**Constructor**(name as `String</api/data_types/string>`)

> <div class="note">
>
> <div class="title">
>
> Note
>
> </div>
>
> `Constructors</api/language/constructor>` are special methods called when you create an object with the `New</api/language/new>` keyword and pass in the parameters above.
>
> </div>
>
> The name passed will be used to create a file and therefore must be a valid filename for the host operating system.
>
> If you pass an empty string, the <span class="title-ref">Mutex</span> will be identical to a `CriticalSection</api/language/threading/criticalsection>`; it will not be visible to other applications. If you pass a name, you can use the name to access the <span class="title-ref">Mutex</span>.
>
> This example creates a <span class="title-ref">Mutex</span>.
>
> ``` xojo
> Var m As New Mutex("MyMutex")
> ```

<div id="mutex.enter">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

Mutex.Enter

**Enter**

> Attempts to get a lock on the resource managed by the CriticalSection.
>
> When the call to Enter succeeds, the function returns and your code has exclusive access to the protected resource. If the lock cannot be obtained immediately, Enter will block the current thread from continuing to run. It will wait for the resource to become available.
>
> Enter differs from the Signal method of the `Semaphore</api/language/threading/semaphore>` class in that it can be called multiple times from the currently executing thread. If the calling thread already owns the lock, the method returns immediately. This makes CriticalSections very useful for calling a method recursively.

<div id="mutex.leave">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

Mutex.Leave

**Leave**

> Call Leave when you are finished using the protected resource and you want to give it back to the CriticalSection.
>
> Every time you call Enter or TryEnter and succeed, you must call Leave. This includes calling it recursively. Otherwise the resource will be protected indefinitely.

<div id="mutex.tryenter">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

Mutex.TryEnter

**TryEnter** As `Boolean</api/data_types/boolean>`

> Attempts to get a lock on the resource managed by the CriticalSection.
>
> TryEnter is similar to Enter but returns a `Boolean</api/data_types/boolean>`. If it succeeds, it returns `True</api/language/true>` and the thread has exclusive use of the resource. If it fails, it returns `False</api/language/false>` but does not block execution of the thread.

## Notes

<span class="title-ref">Mutex</span> is short for Mutual Exclusion object. It allows several applications to share the same system resource, but not simultaneously. The suggested usage of a <span class="title-ref">Mutex</span> is to create a <span class="title-ref">Mutex</span> with a unique name when the application launches. When the application needs to use the resource, it calls the Enter or TryEnter methods to get a "lock" on the resource and calls the Leave method when it is finished (to release the lock). When you have a lock on a resource, it means you are allowed to use it.

The most common use of a <span class="title-ref">Mutex</span> is to determine whether another instance of your application is currently running in the same user account (not system-wide). You create a named <span class="title-ref">Mutex</span> in the application's Opening event and then check to see if you can get a lock on it. If the lock fails, then you know there's another instance of your application running. You can also use Mutexes to work with resources that are shared between applications in the same user account (not system-wide) such as a serial port, printer, or some other system device.

You can call Enter or TryEnter multiple times in the same way as with a `CriticalSection</api/language/threading/criticalsection>`, including recursive calls.

For web applications, the *name* value must not be the same as your `Application Identifier<webapplication.applicationidentifier>`.

If a thread that has a lock crashes, the lock is not released.

<div class="warning">

<div class="title">

Warning

</div>

If you use an `IPCSocket</api/networking/ipcsocket>` that uses SpecialFolder.Temporary to create the IPCSocket file, then the name of the file cannot be the same name as a <span class="title-ref">Mutex</span> (as it also uses that folder).

</div>

## Sample code

Add a property to your app:

``` xojo
mMutex As Mutex
```

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

In the App.Opening event handler, you can attempt to create a <span class="title-ref">Mutex</span>.

``` xojo
mMutex = New Mutex("MutexExample")

If Not mMutex.TryEnter Then
  MessageBox("You cannot have more than one copy of this app running!")
  mMutex = Nil
  Quit
End If
```

In App.Closing event handler, you can release the \`Mutex\`:

``` xojo
If mMutex <> Nil Then
  mMutex.Leave
End If
```

## Compatibility

|                       |                       |
|-----------------------|-----------------------|
| **Project Types**     | Console, Desktop, Web |
| **Operating Systems** | All                   |

<div class="seealso">

`CriticalSection</api/language/threading/criticalsection>` parent class; `DesktopApplication</api/user_interface/desktop/desktopapplication>`, `CriticalSection</api/language/threading/criticalsection>`, `Semaphore</api/language/threading/semaphore>`, `Thread</api/language/threading/thread>` classes.

</div>