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
| Name | Description |
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 types T.
|
receiveTimeout(duration, ops)
|
Tries to receive but will give up if no matches arrive within duration.
Won't wait at all if provided Duration is negative.
|
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
| Name | Description |
Scheduler
|
A Scheduler controls how threading is performed by spawn.
|
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.
|
Authors
Sean Kelly, Alex Rønne Petersen, Martin Nowak
