std
std.array
std.atomic
std.bitarray
std.exception
std.intrinsic
std.memory
std.regexp
std.thread
std.traits
std.unicode
std.vararg
std.math.core
std.math.ieee
std.math.special
|
|
std.thread
The thread module provides support for thread creation and management.
Design Issues:
One design goal of Ares is to avoid forcing the use of a particular
programming style, so long as allowing such flexibility does not
compromise the overall API design. This goal was realized here by
allowing threads to be created in the familiar C style (ie. by
composition), or by derivation, similar to the Java style. Composition
is further supported by virtue of the thread local storage facility,
which allows for thread local data to be stored by the main thread as
well as by user threads.
Future Directions:
Support for lightwewight user threads is a long-term consideration,
though the design of this module is largely settled for now.
class ThreadError: object.Exception;
All exceptions thrown from this module derive from this class.
class Thread;
This class encapsulates all threading functionality for the D
programming language. As thread manipulation is a required facility
for garbage collection, all user threads should derive from this
class, and instances of this class should never be explicitly deleted.
A new thread may be created using either derivation or composition, as
in the following example.
Example:
class DerivedThread : Thread
{
protected:
void run()
{
printf( "Derived thread running.\n" );
}
}
void threadFunc()
{
printf( "Composed thread running.\n" );
}
// create instances of each type
Thread derived = new DerivedThread();
Thread composed = new Thread( &threadFunc );
// start both threads
derived.start();
composed.start();
// wait for the threads to complete
derived.join();
composed.join();
- this();
- Initializes a thread object which has no associated executable
function.
- this(void(* fn)());
- Initialized a thread object which is associated with a static
D function.
Params:
| void(* fn)() |
The thread function. |
- this(void delegate() dg);
- Initializes a thread object which is associated with a dynamic
D function.
Params:
| void delegate() dg |
The thread function. |
- final void start();
- Starts the thread with run() as the target method. The default
behavior of this is to run the function or delegate passed upon
construction.
In:
This routine may only be called once per thread instance.
Throws:
ThreadError if the thread fails to start.
- final void join();
- Waits for this thread to complete.
Throws:
ThreadError if the operation fails.
- final char[] name();
- Gets the user-readable label for this thread.
Returns:
The name of this thread.
- final void name(char[] n);
- Sets the user-readable label for this thread.
Params:
| char[] n |
The new name for this thread. |
- final bool isRunning();
- Tests whether this thread is running. This function should be
callable from anywhere within the application without a risk of
deadlock.
Returns:
true if the thread is running, false if not.
- static void sleep(uint milliseconds);
- Suspends the calling thread for at least the supplied time.
Params:
| uint milliseconds |
The minimum duration the calling thread should be
suspended. |
- static void yield();
- Forces a context switch to occur away from the calling thread.
- static Thread getThis();
- The calling thread.
Returns:
The thread object representing the calling thread. The result of
deleting this object is undefined.
- static Thread[] getAll();
- This function is not intended to be used by the garbage collector,
so memory allocation is allowed.
Returns:
An array containing references to all threads currently being
tracked by the system. The result of deleting any contained
objects is undefined.
- static int opApply(int delegate(inout Thread) dg);
- Operates on all threads currently tracked by the system.
Params:
| int delegate(inout Thread) dg |
The supplied code as a delegate. |
Returns:
Zero if all elemented are visited, nonzero if not.
- const uint LOCAL_MAX;
- Indicates the number of local storage pointers available at program
startup. It is recommended that this number be at least 64.
- static uint createLocal();
- Reserves a local storage pointer for use and initializes this
location to null for all running threads.
Returns:
A key representing the array offset of this memory location.
- static void deleteLocal(uint key);
- Marks the supplied key as available and sets the associated location
to null for all running threads. It is assumed that any key passed
to this function is valid. The result of calling this function for
a key which is still in use is undefined.
Params:
| uint key |
The key to delete. |
- static void* getLocal(uint key);
- Gets the data associated with the supplied key value. It is assumed
that any key passed to this function is valid.
Params:
| uint key |
The location which holds the desired data. |
Returns:
The data associated with the supplied key.
- static void* setLocal(uint key, void* val);
- Stores the supplied value in the specified location. It is assumed
that any key passed to this function is valid.
Params:
| uint key |
The location to store the supplied data. |
| void* val |
The data to store. |
Returns:
A copy of the data which has just been stored.
- protected void run();
- This is the entry point for the newly invoked thread. Default
behavior is to call the function or delegate passed on object
construction. This function may be overridden to create custom
thread objects via subclassing.
void thread_init();
Initializes the thread module. This function must be called by the
garbage collector on startup and before any other thread routines.
are called.
Please note that if thread_init itself performs any allocations then
the thread routines reserved for garbage collector use may be called
while thread_init is being processed. However, since no memory should
exist to be scanned at this point, it is sufficient for these functions
to detect the condition and return immediately.
bool thread_needLock();
This function is used to determine whether the the process is
multi-threaded. Optimizations may only be performed on this
value if the programmer can guarantee that no path from the
enclosed code will start a thread.
Returns:
True if Thread.start() has been called in this process.
void thread_suspendAll();
Suspend all threads but the calling thread for "stop the world" garbage
collection runs. This function may be called multiple times, and must
be followed by a matching number of calls to thread_resumeAll before
processing is resumed.
Throws:
ThreadException if the suspend operation fails for a running thread.
void thread_resumeAll();
Resume all threads but the calling thread for "stop the world" garbage
collection runs. This function must be called once for each preceding
call to thread_suspendAll before the threads are actually resumed.
In:
assert( suspendDepth > 0 );
Throws:
ThreadException if the resume operation fails for a running thread.
void thread_scanAll(void delegate(void*, void*) fn, void* curStackTop = null);
The main entry point for garbage collection. The supplied delegate
will be passed ranges representing both stack and register values.
Params:
| void delegate(void*, void*) fn |
The scanner function. It should scan from p1 through p2 - 1. |
| void* curStackTop |
An optional pointer to the top of the calling thread's stack. |
class ThreadGroup;
This class is intended to simplify certain common programming techniques.
- Thread create(void(* fn)());
- Creates and starts a new Thread object that executes fn and
adds it to the list of tracked threads.
Params:
| void(* fn)() |
The thread function. |
Returns:
A reference to the newly created thread.
- Thread create(void delegate() dg);
- Creates and stats a new Thread object that executes dg and
adds it to the list of tracked threads.
Params:
| void delegate() dg |
The thread function. |
Returns:
A reference to the newly created thread.
- void add(Thread t);
- Add t to the list of tracked threads if it is not already being
tracked.
Params:
| Thread t |
The thread to add. |
In:
assert( t );
- void remove(Thread t);
- Removes t from the list of tracked threads. No operation will be
performed if t is not currently being tracked by this object.
Params:
| Thread t |
The thread to remove. |
In:
assert( t );
- int opApply(int delegate(inout Thread) dg);
- Operates on all threads currently tracked by this object.
- void joinAll(bool preserve = true);
- Iteratively joins all tracked threads. This function
will block add, remove, and opApply until it completes.
Params:
| bool preserve |
Preserve thread references. |
|