Class

# Semaphore

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

## Description

Used to control access to resources in a multithreaded environment.

## Methods

<div class="rst-class">

table-centered_column_4

</div>

| Name                                  | Parameters                                              | Returns                            | Shared |
|---------------------------------------|---------------------------------------------------------|------------------------------------|--------|
| `Constructor<semaphore.constructor0>` | resourceCount As `Integer</api/data_types/integer>` = 1 |                                    |        |
| `Release<semaphore.release>`          |                                                         |                                    |        |
| `Signal<semaphore.signal>`            |                                                         |                                    |        |
| `TrySignal<semaphore.trysignal>`      |                                                         | `Boolean</api/data_types/boolean>` |        |
| `Type<semaphore.type>`                | `Types<thread.types>`                                   |                                    |        |

## Method descriptions

<div id="semaphore.constructor0">

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

</div>

<div class="rst-class">

forsearch

</div>

Semaphore.Constructor

**Constructor**(resourceCount As `Integer</api/data_types/integer>` = 1)

> <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 <span class="title-ref">Semaphore</span> has a constructor that takes the initial count of the number of resources the <span class="title-ref">Semaphore</span> is protecting as an optional parameter. This defaults to 1. If you need to manage access to a single resource, you can instead use a `CriticalSection</api/language/threading/criticalsection>`.

<div id="semaphore.release">

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

</div>

<div class="rst-class">

forsearch

</div>

Semaphore.Release

**Release**

> Call Release to give a locked resource back to the <span class="title-ref">Semaphore</span>. You must call Release when you are finished using a locked resource in order to make it available to other requests.

<div id="semaphore.signal">

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

</div>

<div class="rst-class">

forsearch

</div>

Semaphore.Signal

**Signal**

> Call Signal to obtain a lock on a resource. Once you are done with the shared resource, the thread should call Release to increment the internal counter.
>
> Every time thread calls Signal, the <span class="title-ref">Semaphore</span> decrements the counter. If the counter is less than zero, it suspends the thread.
>
> When you obtain a lock, you can use the resource without fear that another thread will try to use it simultaneously. If the call succeeds, this function returns immediately and you code continues to execute. If the lock is not available, then the thread that called this method will wait until the lock becomes available. When the call returns, you will have the lock, but you may have to wait until the lock becomes available. When you are finished using the resource, call the Release method to give it back to the <span class="title-ref">Semaphore</span>.

<div id="semaphore.trysignal">

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

</div>

<div class="rst-class">

forsearch

</div>

Semaphore.TrySignal

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

> This is a more friendly version of the Signal method that gives you a sneak-peek to determine whether there is a lock available.
>
> If there is a lock available, you are granted the lock and TrySignal returns `True</api/language/true>`. When you are finished with the resource, call Release to give it back to the <span class="title-ref">Semaphore</span>. If the lock is not available, you do not wait for it. Instead, TrySignal returns `False</api/language/false>` to let you know. Do not attempt to use the resource after it returns `False</api/language/false>` because you are likely to collide with another thread.
>
> This example tests whether the lock is available before trying to use the resource.
>
> ``` xojo
> ' Want to make sure that only the right thread
> ' gets in here.  One at a time!
> If mLock.TrySignal Then
>   ' Now that we're here, we can change the resource
>   SharedResource.Value = value
>   AccessText.Text = id.ToString
>
>   ' And now that we've done something with the
>   ' resource, we want to release our lock on it
>   mLock.Release
> End If
> ```

<div id="semaphore.type">

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

</div>

<div class="rst-class">

forsearch

</div>

Semaphore.Type

**Type** As `Types<thread.types>`

> Indicates the type of the <span class="title-ref">Semaphore</span>, Cooperative or preemptive. Cooperative is the default.
>
> Carefully read the `Preemptive Threads<thread.preemptive_threads>` notes before using them.

## Notes

A <span class="title-ref">Semaphore</span> is an object that can be used to coordinate access to a shared resource.

To acquire the ownership of a <span class="title-ref">Semaphore</span>, a thread calls the Signal or TrySignal methods. If the <span class="title-ref">Semaphore</span> isn't owned, the thread acquires ownership, which means you have a lock on it. Otherwise the thread is forced to wait until the <span class="title-ref">Semaphore</span> is released via the Release method by the owning thread.

Every time you successfully obtain an ownership lock on the resource, the <span class="title-ref">Semaphore</span> will decrement its internal count of available resources. When there are no more resources, threads that request ownership locks will begin to block and wait for resources. This is why you can specify the initial count of resources - to give you more control over the behavior of the <span class="title-ref">Semaphore</span>.

The <span class="title-ref">Semaphore</span> class is different from the `CriticalSection</api/language/threading/criticalsection>` and `Mutex</api/language/threading/mutex>` classes in this way: calling Signal in the same thread will cause the counter to decrement. If you call Signal recursively, you will cause the application to hang.

## Sample code

This example uses a <span class="title-ref">Semaphore</span> to ensure that only one thread at a time writes to a file.

Add a public property to the App class:

``` xojo
FileAccess As Semaphore
```

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

And in the Opening event handler, initialize it:

``` xojo
' Allow only a single thread to access the file at a time
FileAccess = New Semaphore(1)
FileAccess.Type = Thread.Types.Preemptive
```

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

In the thread, check the FileAccess <span class="title-ref">Semaphore</span> to see if you can write to the file:

``` xojo
' This will Suspend this thread if another has the lock
' When it is released, this thread will continue to run
App.FileAccess.Signal

' Now you can open the file for writing
WriteDataToFile ' Call your code here

' When you are finished, release the semaphore
App.FileAccess.Release
```

## Compatibility

|                       |     |
|-----------------------|-----|
| **Project Types**     | All |
| **Operating Systems** | All |

<div class="seealso">

`Object</api/data_types/additional_types/object>` parent class; `CriticalSection</api/language/threading/criticalsection>`, `Mutex</api/language/threading/mutex>`, `Thread</api/language/threading/thread>` classes.

</div>