std.concurrency

This is a low-level messaging API upon which more structured or restrictive APIs may be built. The general idea is that every messageable entity is represented by a common handle type called a Tid, which allows messages to be sent to logical threads that are executing in both the current process and in external processes using the same interface. This is an important aspect of scalability because it allows the components of a program to be spread across available resources with few to no changes to the actual implementation.

A logical thread is an execution context that has its own stack and which runs asynchronously to other logical threads. These may be preemptively scheduled kernel threads, fibers (cooperative user-space threads), or some other concept with similar behavior.

The type of concurrency used when logical threads are created is determined by the Scheduler selected at initialization time. The default behavior is currently to create a new kernel thread per call to spawn, but other schedulers are available that multiplex fibers across the main thread or use some combination of the two approaches.

Public Imports

std.variant
public import std.variant;

Members

Classes

FiberScheduler
class FiberScheduler

An example Scheduler using Fibers.

Generator
class Generator(T)

A Generator is a Fiber that periodically returns values of type T to the caller via yield. This is represented as an InputRange.

LinkTerminated
class LinkTerminated

Thrown if a linked thread has terminated.

MailboxFull
class MailboxFull

Thrown on mailbox crowding if the mailbox is configured with OnCrowding.throwException.

MessageMismatch
class MessageMismatch

Thrown on calls to receiveOnly if a message other than the type the receiving thread expected is sent.

OwnerTerminated
class OwnerTerminated

Thrown on calls to receive if the thread that spawned the receiving thread has terminated and no more messages exist.

PriorityMessageException
class PriorityMessageException

Thrown if a message was sent to a thread via std.concurrency.prioritySend and the receiver does not have a handler for a message of this type.

ThreadScheduler
class ThreadScheduler

An example Scheduler using kernel threads.

TidMissingException
class TidMissingException

Thrown when a Tid is missing, e.g. when ownerTid doesn't find an owner thread.

Enums

OnCrowding
enum OnCrowding

These behaviors may be specified when a mailbox is full.

Functions

initOnce
auto ref initOnce(typeof(var) init)

Initializes var with the lazy init value in a thread-safe manner.

initOnce
auto ref initOnce(typeof(var) init, Mutex mutex)

Same as above, but takes a separate mutex instead of sharing one among all initOnce instances.

locate
Tid locate(string name)

Gets the Tid associated with name.

prioritySend
void prioritySend(Tid tid, T vals)

Places the values as a message on the front of tid's message queue.

receive
void receive(T ops)

Receives a message from another thread.

receiveOnly
receiveOnlyRet!(T) receiveOnly()

Receives only messages with arguments of the specified types.

receiveTimeout
bool receiveTimeout(Duration duration, T ops)

Receives a message from another thread and gives up if no match arrives within a specified duration.

register
bool register(string name, Tid tid)

Associates name with tid.

send
void send(Tid tid, T vals)

Places the values as a message at the back of tid's message queue.

setMaxMailboxSize
void setMaxMailboxSize(Tid tid, size_t messages, OnCrowding doThis)

Sets a maximum mailbox size.

setMaxMailboxSize
void setMaxMailboxSize(Tid tid, size_t messages, bool function(Tid) onCrowdingDoThis)

Sets a maximum mailbox size.

spawn
Tid spawn(F fn, T args)

* Starts fn(args) in a new logical thread. * * Executes the supplied function in a new logical thread represented by * Tid. The calling thread is designated as the owner of the new thread. * When the owner thread terminates an OwnerTerminated message will be * sent to the new thread, causing an OwnerTerminated exception to be * thrown on receive(). * * Params: * fn = The function to execute. * args = Arguments to the function. * * Returns: * A Tid representing the new logical thread. * * Notes: * args must not have unshared aliasing. In other words, all arguments * to fn must either be shared or immutable or have no * pointer indirection. This is necessary for enforcing isolation among * threads. * * Similarly, if fn is a delegate, it must not have unshared aliases, meaning * fn must be either shared or immutable.

spawnLinked
Tid spawnLinked(F fn, T args)

Starts fn(args) in a logical thread and will receive a LinkTerminated message when the operation terminates.

unregister
bool unregister(string name)

Removes the registered name associated with a tid.

yield
void yield()

If the caller is a Fiber and is not a Generator, this function will call scheduler.yield() or Fiber.yield(), as appropriate.

yield
void yield(T value)

Yields a value of type T to the caller of the currently executing generator.

Interfaces

Scheduler
interface Scheduler

A Scheduler controls how threading is performed by spawn.

Properties

ownerTid
Tid ownerTid [@property getter]

Return the Tid of the thread which spawned the caller's thread.

thisTid
Tid thisTid [@property getter]

Static variables

scheduler
Scheduler scheduler;

Sets the Scheduler behavior within the program.

Structs

ThreadInfo
struct ThreadInfo

Encapsulates all implementation-level data needed for scheduling.

Tid
struct Tid

An opaque type used to represent a logical thread.

Meta

License

<a href="http://www.boost.org/LICENSE_1_0.txt">Boost License 1.0</a>.

Authors

Sean Kelly, Alex Rønne Petersen, Martin Nowak