std.concurrency


Category	Symbols
Tid	`locate` `ownerTid` `register` `spawn` `spawnLinked` `thisTid` `Tid` `TidMissingException` `unregister`
Message passing	`prioritySend` `receive` `receiveOnly` `receiveTimeout` `send` `setMaxMailboxSize`
Message-related types	`LinkTerminated` `MailboxFull` `MessageMismatch` `OnCrowding` `OwnerTerminated` `PriorityMessageException`
Scheduler	`FiberScheduler` `Generator` `Scheduler` `scheduler` `ThreadInfo` `ThreadScheduler` `yield`
Misc	`initOnce`

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.

Copyright

License

Boost License 1.0.

Authors

Sean Kelly, Alex Rønne Petersen, Martin Nowak

Source: std/concurrency.d

var scheduler

tmpl isSpawnable receiveOnlyRet

enum OnCrowding

struct ThreadInfo Tid

class FiberScheduler Generator LinkTerminated MailboxFull MessageMismatch OwnerTerminated PriorityMessageException ThreadScheduler TidMissingException

iface Scheduler

fn initOnce locate ownerTid prioritySend receive receiveOnly receiveTimeout register send setMaxMailboxSize spawn spawnLinked thisTid unregister yield

Module Deinitializers 1

static ~this()

Types 13

classMessageMismatch : Exception

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

Constructors

this(string msg = "Unexpected message type")

classOwnerTerminated : Exception

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

Fields

Tid tid

Constructors

this(Tid t, string msg = "Owner terminated")

classLinkTerminated : Exception

Thrown if a linked thread has terminated.

Fields

Tid tid

Constructors

this(Tid t, string msg = "Link terminated")

classPriorityMessageException : Exception

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

Fields

Variant messageThe message that was sent.

Constructors

this(Variant vals)

classMailboxFull : Exception

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

Fields

Tid tid

Constructors

this(Tid t, string msg = "Mailbox full")

classTidMissingException : Exception

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

structTid

An opaque type used to represent a logical thread.

Methods

void toString(W)(ref W w) constGenerate a convenient string for identifying this `Tid`. This is only useful to see if `Tid`'s that are currently executing are the same or different, e.g. for logging and debugging. It is potent...

Constructors

this(MessageBox m)

enumOnCrowding

These behaviors may be specified when a mailbox is full.

blockWait until room is available.

throwExceptionThrow a MailboxFull exception.

ignoreAbort the send and return.

structThreadInfo

Encapsulates all implementation-level data needed for scheduling.

When defining a Scheduler, an instance of this struct must be associated with each logical thread. It contains all implementation-level information needed by the internal API.

Fields

Tid ident

bool[Tid] links

Tid owner

Methods

static @property ref thisInfo() nothrowGets a thread-local instance of `ThreadInfo`.

void cleanup()Cleans up this ThreadInfo.

interfaceScheduler

A Scheduler controls how threading is performed by spawn.

Implementing a Scheduler allows the concurrency mechanism used by this module to be customized according to different needs. By default, a call to spawn will create a new kernel thread that executes the supplied routine and terminates when finished. But it is possible to create Schedulers that reuse threads, that multiplex Fibers (coroutines) across a single thread, or any number of other approaches. By making the choice of Scheduler a user-level option, std.concurrency may be used for far more types of application than if this behavior were predefined.

Example:

import std.concurrency;
import std.stdio;

void main()
{
    scheduler = new FiberScheduler;
    scheduler.start(
    {
        writeln("the rest of main goes here");
    });
}

Some schedulers have a dispatching loop that must run if they are to work properly, so for the sake of consistency, when using a scheduler, start() must be called within main(). This yields control to the scheduler and will ensure that any spawned threads are executed in an expected manner.

Methods

void start(void delegate() op)Spawns the supplied op and starts the `Scheduler`.

void spawn(void delegate() op)Assigns a logical thread to execute the supplied op.

void yield() nothrow;Yields execution to another logical thread.

ThreadInfo thisInfo() @property ref nothrow;Returns an appropriate `ThreadInfo` instance.

Condition newCondition(Mutex m) nothrow;Creates a `Condition` variable analog for signaling.

classThreadScheduler : Scheduler

An example Scheduler using kernel threads.

This is an example Scheduler that mirrors the default scheduling behavior of creating one kernel thread per call to spawn. It is fully functional and may be instantiated and used, but is not a necessary part of the default functioning of this module.

Methods

void start(void delegate() op)This simply runs op directly, since no real scheduling is needed by this approach.

void spawn(void delegate() op)Creates a new kernel thread and assigns it to run the supplied op.

void yield() nothrowThis scheduler does no explicit multiplexing, so this is a no-op.

ThreadInfo thisInfo() @property ref nothrowReturns `ThreadInfo.thisInfo`, since it is a thread-local instance of `ThreadInfo`, which is the correct behavior for this scheduler.

Condition newCondition(Mutex m) nothrowCreates a new `Condition` variable. No custom behavior is needed here.

classFiberScheduler : Scheduler

An example Scheduler using Fibers.

This is an example scheduler that creates a new Fiber per call to spawn and multiplexes the execution of all fibers within the main thread.

Methods

void start(void delegate() op)This creates a new `Fiber` for the supplied op and then starts the dispatcher.

void spawn(void delegate() op) nothrowThis created a new `Fiber` for the supplied op and adds it to the dispatch list.

void yield() nothrowIf the caller is a scheduled `Fiber`, this yields execution to another scheduled `Fiber`.

ThreadInfo thisInfo() @property ref nothrowReturns an appropriate `ThreadInfo` instance.

Condition newCondition(Mutex m) nothrowReturns a `Condition` analog that yields when wait or notify is called.

void create(void delegate() op) nothrowCreates a new `Fiber` which calls the given delegate.

Nested Templates

InfoFiber`Fiber` which embeds a `ThreadInfo`

FiberCondition

classGenerator(T) : Fiber, IsGenerator, InputRange!T

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

Methods

bool empty() @propertyReturns true if the generator is empty.

void popFront()Obtains the next value from the underlying function.

T front() @propertyReturns the most recently generated value by shallow copy.

T moveFront()Returns the most recently generated value without executing a copy contructor. Will not compile for element types defining a postblit, because `Generator` does not return by reference.

int opApply(scope int delegate(T) loopBody)

int opApply(scope int delegate(size_t, T) loopBody)

Constructors

this(void function() fn)Initializes a generator object which is associated with a static D function. The function will be called once to prepare the range for iteration.

this(void function() fn, size_t sz)Initializes a generator object which is associated with a static D function. The function will be called once to prepare the range for iteration.

this(void function() fn, size_t sz, size_t guardPageSize)Initializes a generator object which is associated with a static D function. The function will be called once to prepare the range for iteration.

this(void delegate() dg)Initializes a generator object which is associated with a dynamic D function. The function will be called once to prepare the range for iteration.

this(void delegate() dg, size_t sz)Initializes a generator object which is associated with a dynamic D function. The function will be called once to prepare the range for iteration.

this(void delegate() dg, size_t sz, size_t guardPageSize)Initializes a generator object which is associated with a dynamic D function. The function will be called once to prepare the range for iteration.

Functions 20

fnTid thisTid() @property @safeReturns: The `Tid` of the caller's thread.

fnTid ownerTid() @propertyReturn the `Tid` of the thread which spawned the caller's thread.

fnTid spawn(F, T...)(F fn, T args) if (isSpawnable!(F, T))Starts `fn(args)` in a new logical thread.

fnTid spawnLinked(F, T...)(F fn, T args) if (isSpawnable!(F, T))Starts `fn(args)` in a logical thread and will receive a `LinkTerminated` message when the operation terminates.

fnvoid send(T...)(Tid tid, T vals)Places the values as a message at the back of tid's message queue.

fnvoid prioritySend(T...)(Tid tid, T vals)Places the values as a message on the front of tid's message queue.

fnvoid receive(T...)( T ops )Receives a message from another thread.

fnreceiveOnlyRet!(T) receiveOnly(T...)()Receives only messages with arguments of the specified types.

fnbool receiveTimeout(T...)(Duration duration, T ops)Receives a message from another thread and gives up if no match arrives within a specified duration.

fnvoid setMaxMailboxSize(Tid tid, size_t messages, OnCrowding doThis) @safe pureSets a maximum mailbox size.

fnvoid setMaxMailboxSize(Tid tid, size_t messages, bool function(Tid) onCrowdingDoThis)Sets a maximum mailbox size.

fnbool register(string name, Tid tid)Associates name with tid.

fnbool unregister(string name)Removes the registered name associated with a tid.

fnTid locate(string name)Gets the `Tid` associated with name.

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

fnvoid yield(T)(ref T value)Yields a value of type T to the caller of the currently executing generator.

fnvoid yield(T)(T value)ditto

fnauto ref initOnce(alias var)(lazy typeof(var) init)Initializes var with the lazy init value in a thread-safe manner.

fnauto ref initOnce(alias var)(lazy typeof(var) init, shared Mutex mutex)Same as above, but takes a separate mutex instead of sharing one among all initOnce instances.

fnauto ref initOnce(alias var)(lazy typeof(var) init, Mutex mutex)ditto

Variables 1

varScheduler scheduler

Sets the Scheduler behavior within the program.

This variable sets the Scheduler behavior within this program. Typically, when setting a Scheduler, scheduler.start() should be called in main. This routine will not return until program execution is complete.

Templates 2

tmplisSpawnable(F, T...)

tmplreceiveOnlyRet(T...)