core.thread.osthread

The osthread module provides low-level, OS-dependent code for thread creation and management.

License:

Distributed under the Boost Software License 1.0. (See accompanying file LICENSE)

Authors:

Sean Kelly, Walter Bright, Alex Rønne Petersen, Martin Nowak

Source

core/thread/osthread.d

class Thread: core.thread.threadbase.ThreadBase;

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.

pure nothrow @nogc @safe this(void function() fn, size_t sz = 0);

Initializes a thread object which is associated with a static D function.

Parameters:

void function() fn	The thread function.
size_t sz	The stack size for this thread.

In

fn must not be null.

pure nothrow @nogc @safe this(void delegate() dg, size_t sz = 0);

Initializes a thread object which is associated with a dynamic D function.

Parameters:

void delegate() dg	The thread function.
size_t sz	The stack size for this thread.

In

dg must not be null.

static nothrow @nogc @safe Thread getThis();

Provides a reference to the calling thread.

Returns:

The thread object representing the calling thread. The result of deleting this object is undefined. If the current thread is not attached to the runtime, a null reference is returned.

final nothrow Thread start();

Starts the thread and invokes the function or delegate passed upon construction.

In

This routine may only be called once per thread instance.

Throws:

ThreadException if the thread fails to start.

final Throwable join(bool rethrow = true);

Waits for this thread to complete. If the thread terminated as the result of an unhandled exception, this exception will be rethrown.

Parameters:

bool rethrow

Rethrow any unhandled exception which may have caused this thread to terminate.

Throws:

ThreadException if the operation fails. Any exception not handled by the joined thread.

Returns:

Any exception not handled by this thread if rethrow = false, null otherwise.

static pure nothrow @nogc @property @trusted int PRIORITY_MIN();

The minimum scheduling priority that may be set for a thread. On systems where multiple scheduling policies are defined, this value represents the minimum valid priority for the scheduling policy of the process.

static pure nothrow @nogc @property @trusted const(int) PRIORITY_MAX();

The maximum scheduling priority that may be set for a thread. On systems where multiple scheduling policies are defined, this value represents the maximum valid priority for the scheduling policy of the process.

static pure nothrow @nogc @property @trusted int PRIORITY_DEFAULT();

The default scheduling priority that is set for a thread. On systems where multiple scheduling policies are defined, this value represents the default priority for the scheduling policy of the process.

final @property int priority();

Gets the scheduling priority for the associated thread.

Note

Getting the priority of a thread that already terminated might return the default priority.

Returns:

The scheduling priority of this thread.

final @property void priority(int val);

Sets the scheduling priority for the associated thread.

Note

Setting the priority of a thread that already terminated might have no effect.

Parameters:

int val

The new scheduling priority of this thread.

final nothrow @nogc @property bool isRunning();

Tests whether this thread is running.

Returns:

true if the thread is running, false if not.

static nothrow @nogc void sleep(Duration val);

Suspends the calling thread for at least the supplied period. This may result in multiple OS calls if period is greater than the maximum sleep duration supported by the operating system.

Parameters:

Duration val

The minimum duration the calling thread should be suspended.

In

period must be non-negative.

Example

Thread.sleep( dur!("msecs")( 50 ) );  // sleep for 50 milliseconds
Thread.sleep( dur!("seconds")( 5 ) ); // sleep for 5 seconds

static nothrow @nogc void yield();

Forces a context switch to occur away from the calling thread.

nothrow @nogc void thread_setGCSignals(int suspendSignalNo, int resumeSignalNo);

Instruct the thread module, when initialized, to use a different set of signals besides SIGUSR1 and SIGUSR2 for suspension and resumption of threads. This function should be called at most once, prior to thread_init(). This function is Posix-only.

Thread thread_attachThis();

Registers the calling thread for use with the D Runtime. If this routine is called for a thread which is already registered, no action is performed.

NOTE

This routine does not run thread-local static constructors when called. If full functionality as a D thread is desired, the following function must be called after thread_attachThis:

extern (C) void rt_moduleTlsCtor();

alias getpid = core.sys.posix.unistd.getpid;

Returns the process ID of the calling process, which is guaranteed to be unique on the system. This call is always successful.

Example

writefln("Current process id: %s", getpid());

nothrow 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:

ThreadError if the suspend operation fails for a running thread.

@nogc 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.

@nogc void thread_term();

Terminates the thread module. No other thread routine may be called afterwards.

nothrow @nogc ThreadID createLowLevelThread(void delegate() nothrow dg, uint stacksize = 0, void delegate() nothrow cbDllUnload = null);

Create a thread not under control of the runtime, i.e. TLS module constructors are not run and the GC does not suspend it during a collection.

Parameters:

void delegate() nothrow dg	delegate to execute in the created thread.
uint stacksize	size of the stack of the created thread. The default of 0 will select the platform-specific default size.
void delegate() nothrow cbDllUnload	Windows only: if running in a dynamically loaded DLL, this delegate will be called if the DLL is supposed to be unloaded, but the thread is still running. The thread must be terminated via joinLowLevelThread by the callback.

Returns:

the platform specific thread ID of the new thread. If an error occurs, ThreadID.init is returned.

nothrow @nogc void joinLowLevelThread(ThreadID tid);

Wait for a thread created with createLowLevelThread to terminate.

Note

In a Windows DLL, if this function is called via DllMain with argument DLL_PROCESS_DETACH, the thread is terminated forcefully without proper cleanup as a deadlock would happen otherwise.

Parameters:

ThreadID tid

the thread ID returned by createLowLevelThread.