View source code Display the source code in std/concurrency.d from which this page was generated on github. 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. Page wiki View or edit the community-maintained wiki page associated with this page.

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.

Synposis

import std.stdio;
import std.concurrency;

void spawnedFunc(Tid ownerTid)
{
    // Receive a message from the owner thread.
    receive(
        (int i) { writeln("Received the number ", i);}
    );

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

void main()
{
    // 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("Successfully printed number.");
}

Functions

Name Description
initOnce Same as above, but takes a separate mutex instead of sharing one among all initOnce instances.
initOnce Initializes var with the lazy init value in a thread-safe manner.
locate Gets the Tid associated with name.
ownerTid Return the Tid of the thread which spawned the caller's thread.
prioritySend Places the values as a message on the front of tid's message queue.
receive Receives a message from another thread.
receiveOnly Receives only messages with arguments of types T.
receiveTimeout Tries to receive but will give up if no matches arrive within duration.
register Associates name with tid.
send Places the values as a message at the back of tid's message queue.
setMaxMailboxSize Sets a maximum mailbox size.
setMaxMailboxSize Sets a maximum mailbox size.
spawn Starts fn(args) in a new logical thread.
spawnLinked Starts fn(args) in a logical thread and will receive a LinkTerminated message when the operation terminates.
thisTid Returns the caller's Tid.
unregister 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 Yields a value of type T to the caller of the currently executing generator.

Interfaces

Name Description
Scheduler A Scheduler controls how threading is performed by spawn.

Classes

Name Description
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 std.concurrency.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

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

Enums

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

Global variables

Name Type Description
scheduler Scheduler Sets the Scheduler behavior within the program.

Authors

Sean Kelly, Alex Rønne Petersen, Martin Nowak

License

Boost License 1.0.

Comments