# Threading and Synchronization

Storm is aware of threads by default, and aims to avoid data races. To achieve this, Storm utilizes some mechanisms in the standard library. In particular, the classes `core.Thread` and `core.Future<T>` are central to making inter-thread communication happen. This part of the library also provides some utility functions to affect thread behavior.

Even though Storm avoids data races by default, it is sometimes necessary to explicitly synchronize code. This is particularly true when integrating external libraries in C++. As such, Storm provides a number of synchronization primitives that can be used for these purposes.

## Thread

The `core.Thread` class represents an OS thread in Storm. As such, different threads may execute in parallel at the discretion of the operating system. Threads are typically created lazily. This means that the actual OS thread is not created until work is submitted to it. The thread is then kept alive and accepts work until the associated `Thread` object has been destroyed. At that point it executes until its work-queue is empty and then terminates. In Storm's threading model, it is common for threads to be created soon after startup, and then kept alive until the application ends (since they are bound to `NamedThread` entities).

The thread class itself does not contain facilities to submit work to a thread. Rather, one needs to use the language facilities to submit work to threads (e.g. the `spawn` keyword in Basic Storm, or creating an actor associated with the thread).

The `Thread` class has the following members:

- `init()`

  Create a thread.

- `core.Bool ==(core.Thread o)`

  Check for equality.

- `core.Nat hash()`

  Compute a hash.

The following free functions are also useful to modify the behavior of threads:

- `void sleep(core.Duration d)`

  Sleep for the specified duration. Do not expect more than ms precision.

- `void yield()`

  Yield the current thread. This causes the current UThread to stop running, and the system will schedule another thread that is ready to run if possible. The current thread is still marked as ready, and will continue to execute whenever the scheduler schedules it again.

## Future

As mentioned above, the `core.Future<T>` class is central for inter-thread communication. A future represents an object of type `T` that will be present at some time in the future. The future is expected to be populated by some particular thread (typically the thread that received a message), and other thread(s) may wait for the value to become available (typically the thread that sent the message). Since a future may be used to wait for values, it is possible to set `T` to `void` to indicate that one is only interested in waiting for an action to complete, but not the actual object.

In addition to the result `T`, a future may also store the result in form of an exception. This causes the future to throw the exception whenever a thread asks for the result. As such, this behavior is used to propagate exceptions across thread boundaries.

Since future objects are thread-safe, it is safe to share them between different threads. Because of this, making a copy of a future object will create a copy that refers to the same internal representation. This means that all copies are linked, and can be used interchangeably. This also means that it is possible to pass a future object to other threads, even though parameters are copied.

The `Future<T>` class has the following members:

- `void post(T value)`

  Save `value` in the future. This makes any threads waiting for the value wake up. It is only possible to call `post` or `error` once for each future.

- `void error(Exception exception)`

  Save `exception` as an error in the future. This makes any threads waiting for the value to wake up. It is only possible to call `post` or `error` once for each future.

- `T result()`

  Wait until the result is available, and return it. If the result posted was an error, it is thrown by the `result` function. It is possible to call `result` any number of times.

- `void errorResult()`

  Like `result`, but only waits for a result to become available and throws an error if appropriate. The result stored in the future (if any) is not returned.

- `void detach()`

  Informs the future that no more threads will call `result` or `errorResult`. This means that any internal data structures can be freed prematurely.

  This is typically used when spawning a thread when one does not wish to wait for the result. This call informs the system that any results from the spawned thread can be discarded. It also causes the future to output any errors produced by the detached future, as they would otherwise appear to be silently ignored by the system.

## Locks

The simplest synchronization primitive available in Storm is a recursive lock (sometimes called a recursive mutex). This is implemented by the class `core.sync.Lock`. The lock itself is thread-safe, and therefore all copies of a `Lock` object continue to refer to the same lock. This makes it possible to share the lock between different threads in Storm. Furthermore, the lock is aware of Storm's threading model, which means that it only blocks the currently active user-mode thread.

The lock does not provide the any public members except a default constructor, and logic for copying the lock. Acquiring and releasing the lock is managed by the nested type `core.sync.Lock.Guard`. This type takes a lock as a parameter to its constructor. The lock is then acquired in the constructor and released in the destructor. As such, assuming that the `Guard` object is stack-allocated, then releasing the lock will be performed automatically. In Basic Storm, using a lock may look like this:

    use core:sync;

    void function(Lock lock) {
        // Do something that does not require the lock...
        {
            Lock:Guard guard(lock);
            // The lock is now held, manipulate shared data.
        }
        // The lock is now released as the 'guard' is not in scope anymore.
        // Do something that does not require the lock...
    }

## Semaphores

Semaphores provide more flexibility compared to locks. It is, however, easier to cause deadlocks when using semaphores. In Storm, the class `core.sync.Sema` implements a semaphore. As with locks, the semaphore is thread-safe, and therefore all copies of a `Sema` object continue to refer to the same semaphore. It is thereby possible to share semaphores between threads. Furthermore, the lock is aware of Storm's threading model, which means that it only blocks the currently active user-mode thread.

A semaphore can be thought of as an integer variable that needs to be positive. The semaphore provides two operations that modify the integer variable, `up` and `down`. The `up` operation increment the integer. This operation never has to wait, as there is no risk of the variable becoming negative. The `down` operation attempts to decrement the integer. To avoid it becoming negative, it waits if the integer was zero already. Future calls to `up` will cause it to wake and succeed in decreasing the integer.

The semaphore has the following members:

- `init()`

  Create a semaphore initialized to 1.

- `init(core.Nat count)`

  Create a semaphore initialized to `count`.

- `void up()`

  Increase the value in the semaphore by 1. May wake any waiting threads.

- `void down()`

  Attempt to decrease the value in the semaphore by 1. Will wait in case the value would become negative.

## Events

Events provide a convenient way to wait for some event to occur. In contrast to futures, events can be reset and reused without creating and distributing new event variables. As such, an event can be thought of as a boolean variable that is either `true` or `false`. Whenever the variable is `false`, all threads that call `wait` will wait until the variable becomes `true`. When the variable is `true`, then threads never wait, and any waiting threads will continue executing. Events can therefore be used to implement condition variables.

In Storm, events are implemented by the class `core.sync.Event`. As with the other synchronization primitives, copies of an event refer to the same underlying variable. It is therefore possible to share event variables between threads. Furthermore, the lock is aware of Storm's threading model, which means that it only blocks the currently active user-mode thread.

An event has the following members:

- `init()`

  Create an event. The created event is initially not set.

- `void set()`

  Set the event. This causes all threads currently waiting to continue executing, and all future calls to `wait` to return immediately.

- `void clear()`

  Clear the event. This causes future threads to `wait` to cause threads to wait for the event to become set again. Note that calling `clear` while other threads might call `wait` causes a race condition, as there is no guarantee in what order the two operations will complete. As such, some caution is required when using `clear`.

- `void wait()`

  Wait for the event to become signaled, if it is not already.

- `core.Bool isSet()`

  Check if the condition is set. While this function is thread safe, it is generally risky to inspect the state of an event and later act upon it. After checking the state, there is generally no guarantee that the state remains the same immediately after checking it.