View source code
Display the source code in std/concurrency.d from which this page was generated on github.
Report a bug
If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page
Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using local clone.

Module 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.

Example

__gshared string received;
static void spawnedFunc(Tid ownerTid)
{
    import std.conv : text;
    // Receive a message from the owner thread.
    receive((int i){
        received = text("Received the number ", i);

        // Send a message back to the owner thread
        // indicating success.
        send(ownerTid, true);
    });
}

// Start spawnedFunc in a new thread.
auto childTid = spawn(&spawnedFunc, thisTid);

// Send the number 42 to this new thread.
send(childTid, 42);

// Receive the result code.
auto wasSuccessful = receiveOnly!(bool);
assert(wasSuccessful);
writeln(received); // "Received the number 42"

Functions

NameDescription
initOnce(init) Initializes var with the lazy init value in a thread-safe manner.
initOnce(init, mutex) Same as above, but takes a separate mutex instead of sharing one among all initOnce instances.
locate(name) Gets the Tid associated with name.
ownerTid() Return the Tid of the thread which spawned the caller's thread.
prioritySend(tid, vals) Places the values as a message on the front of tid's message queue.
receive(ops) Receives a message from another thread.
receiveOnly() Receives only messages with arguments of the specified types.
receiveTimeout(duration, ops) Receives a message from another thread and gives up if no match arrives within a specified duration.
register(name, tid) Associates name with tid.
send(tid, vals) Places the values as a message at the back of tid's message queue.
setMaxMailboxSize(tid, messages, doThis) Sets a maximum mailbox size.
setMaxMailboxSize(tid, messages, onCrowdingDoThis) Sets a maximum mailbox size.
spawn(fn, args) Starts fn(args) in a new logical thread.
spawnLinked(fn, args) Starts fn(args) in a logical thread and will receive a LinkTerminated message when the operation terminates.
thisTid()
unregister(name) Removes the registered name associated with a tid.
yield() If the caller is a Fiber and is not a Generator, this function will call scheduler.yield() or Fiber.yield(), as appropriate.
yield(value) Yields a value of type T to the caller of the currently executing generator.

Interfaces

NameDescription
Scheduler A Scheduler controls how threading is performed by spawn.

Classes

NameDescription
FiberScheduler An example Scheduler using Fibers.
Generator A Generator is a Fiber that periodically returns values of type T to the caller via yield. This is represented as an InputRange.
LinkTerminated Thrown if a linked thread has terminated.
MailboxFull Thrown on mailbox crowding if the mailbox is configured with OnCrowding.throwException.
MessageMismatch Thrown on calls to receiveOnly if a message other than the type the receiving thread expected is sent.
OwnerTerminated Thrown on calls to receive if the thread that spawned the receiving thread has terminated and no more messages exist.
PriorityMessageException 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.
ThreadScheduler An example Scheduler using kernel threads.
TidMissingException Thrown when a Tid is missing, e.g. when ownerTid doesn't find an owner thread.

Structs

NameDescription
ThreadInfo Encapsulates all implementation-level data needed for scheduling.
Tid An opaque type used to represent a logical thread.

Enums

NameDescription
OnCrowding These behaviors may be specified when a mailbox is full.

Global variables

NameTypeDescription
scheduler Scheduler Sets the Scheduler behavior within the program.

Authors

Sean Kelly, Alex Rønne Petersen, Martin Nowak

License

Boost License 1.0.