www.digitalmars.com

D Programming Language 2.0

Last update Thu May 12 16:55:03 2011

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 Cid in this implementation), which allows messages to be sent to in-process threads, on-host processes, and foreign-host 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.

Right now, only in-process threads are supported and referenced by a more specialized handle called a Tid. It is effectively a subclass of Cid, with additional features specific to in-process messaging.

License:
Boost License 1.0.

Authors:
Sean Kelly

Source:
std/concurrency.d

class MessageMismatch: object.Exception;

class OwnerTerminated: object.Exception;

class LinkTerminated: object.Exception;

class PriorityMessageException: object.Exception;

class MailboxFull: object.Exception;

struct Tid;
An opaque type used to represent a logical local process.

Tid thisTid();
Returns the caller's Tid.

Tid spawn(T...)(void function(T) fn, T args);
Executes the supplied function in a new context represented by Tid. The calling context is designated as the owner of the new context. When the owner context terminated an OwnerTerminated message will be sent to the new context, causing an OwnerTerminated exception to be thrown on receive().

Parameters:
fn The function to execute.
args Arguments to the function.

Returns:
A Tid representing the new context.

Tid spawnLinked(T...)(void function(T) fn, T args);
Executes the supplied function in a new context represented by Tid. This new context is linked to the calling context so that if either it or the calling context terminates a LinkTerminated message will be sent to the other, causing a LinkTerminated exception to be thrown on receive(). The owner relationship from spawn() is preserved as well, so if the link between threads is broken, owner termination will still result in an OwnerTerminated exception to be thrown on receive().

Parameters:
fn The function to execute.
args Arguments to the function.

Returns:
A Tid representing the new context.

void send(T...)(Tid tid, T vals);
Sends the supplied value to the context represented by tid.

void prioritySend(T...)(Tid tid, T vals);

void receive(T...)(T ops);

receiveOnlyRet!(T) receiveOnly(T...)();

bool receiveTimeout(T...)(long ms, T ops);
bool receiveTimeout(T...)(Duration duration, T ops);

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

block
Wait until room is available.

throwException
Throw a MailboxFull exception.

ignore
Abort the send and return.

void setMaxMailboxSize(Tid tid, size_t messages, OnCrowding doThis);
Sets a limit on the maximum number of user messages allowed in the mailbox. If this limit is reached, the caller attempting to add a new message will execute the behavior specified by doThis. If messages is zero, the mailbox is unbounded.

Parameters:
Tid tid The Tid of the thread for which this limit should be set.
size_t messages The maximum number of messages or zero if no limit.
OnCrowding doThis The behavior executed when a message is sent to a full mailbox.

void setMaxMailboxSize(Tid tid, size_t messages, bool function(Tid) onCrowdingDoThis);
Sets a limit on the maximum number of user messages allowed in the mailbox. If this limit is reached, the caller attempting to add a new message will execute onCrowdingDoThis. If messages is zero, the mailbox is unbounded.

Parameters:
Tid tid The Tid of the thread for which this limit should be set.
size_t messages The maximum number of messages or zero if no limit.
bool function(Tid) onCrowdingDoThis The routine called when a message is sent to a full mailbox.

bool register(string name, Tid tid);
Associates name with tid in a process-local map. When the thread represented by tid termiantes, any names associated with it will be automatically unregistered.

Parameters:
string name The name to associate with tid.
Tid tid The tid register by name.

Returns:
true if the name is available and tid is not known to represent a defunct thread.

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

Parameters:
string name The name to unregister.

Returns:
true if the name is registered, false if not.

Tid locate(string name);
Gets the Tid associated with name.

Parameters:
string name The name to locate within the registry.

Returns:
The associated Tid or Tid.init if name is not registered.

struct List(T);