Thread

Description

sealed class Tinman.Core.Threading.Thread

Derived from

Disposable abstract
INativeHandle

The Thread represents a background thread.

To create and run a background thread, the following steps are necessary:

  1. Creates a new instance of Thread.

  2. Configure the optional Argument, Name and Priority properties.

  3. Set the thread main function with ThreadMain.

  4. Call the Start method to initialize and run the background thread.

  5. Configure the LogOnError property at any time during the thread’s lifetime.

  6. Call the Stop method to tell the background thread to terminate gracefully.

  7. Call the Join method to actually wait until the thread has terminated.

  8. Finally, dispose the thread to free up system resources. Upon disposal, the Stop and Join method will be called.

The Create method can be used as a shortcut for steps 1, 2, 3 and 5.

Public / Constructors

Create

[OwnerReturn]
public static method Create → (4)

name in : string

Name of the background thread.

main in : IThreadMain own

[not-null]
The thread main method.

argument opt : object = null

Optional parameter to pass to thread main method.

priority opt : ThreadPriority = ThreadPriority.Normal

The thread priority.

returns → Thread

The running Thread object.

Creates a background thread.

The new thread is initially suspended and must be started with Start.

Create​Wrap

[OwnerReturn]
public static method CreateWrap → (4)

name in : string

Name of the background thread.

main in : ErrorBarrierDelegate<ThreadContext>

[not-null]
The thread main method.

argument opt : object = null

Optional parameter to pass to thread main method.

priority opt : ThreadPriority = ThreadPriority.Normal

The thread priority.

returns → Thread

The running Thread object.

Creates a background thread.

The new thread is initially suspended and must be started with Start.

Thread

public constructor Thread → ()

Creates a new instance of Thread.

Public / Methods

Dispose​All

[Dispose]
public static method DisposeAll → (1)

threads in : IEnumerable<Thread> own

[not-null]
The threads.

Calls Stop on each of the given threads and then disposes them.

Join

[ThreadSafe]
public method Join → (1)

wait opt : bool = true

Wait for thread to terminate?

returns → bool

true if the thread has terminated, false if it is still running (can only happen if wait opt is false).

Waits until this thread has terminated.

If the thread has already been terminated, the method returns silently.

Single​Threaded​Mode

public static method SingleThreadedMode → (1)

enable in : bool

Enter single-threaded emulation mode (true) or regular multi-threaded mode ( false), when TinmanModule.Initialize is called?

Forces the Tinman 3D SDK to run in single-threaded mode, where the following methods emulate the semantic of multi-threading while using only the calling sole application thread:

This method must be called before the Tinman 3D library is initialized (see TinmanModule.Initialize), otherwise undefined behaviour may occur.

Single-threaded emulation mode is intended to be used in specific cases, where the runtime environment does not support threads (for example, a client-side WASM module in a browser) or when reproducible behaviour is required (when debugging). With emulation, the same code may run on both multi-threaded and single-threaded environments. However, running in single-threaded emulation mode will most likely introduce significant performance degradation as well as reduced responsiveness of the main application thread.

See also

Thread.SingleThreadedTick
IThreadMain

Single​Threaded​Tick

public static method SingleThreadedTick → (1)

wait opt : int32 = -1

The wait timeout in milliseconds to apply in order to avoid wasting CPU cycles by spinning through idle threads. If negative, this method will only return the status of the single-threaded emulation mode, without running any thread cycles.

returns → bool

true if the single-threaded emulation mode is active,
false if regular multi-threading is active (i.e., this method is a no-op).

This method runs the single-threaded emulation mode.

The Tinman 3D SDK already calls this method. Client code may perform additional calls while waiting to an asynchronous operation to finish, in order to improve responsiveness of the sole application thread.

See also

Thread.SingleThreadedMode

Sleep

public static method Sleep → (1)

milliSeconds opt : int32 = 0

[>=0]
The number of milliseconds to sleep.

Suspends the calling thread for the given amount of time.

Start

[ThreadSafe]
public method Start → ()

Starts this thread.

The method creates a new background thread which will execute the Run method of the given IThreadMain object (see ThreadMain property).

If the thread has already been started, the method silently returns.

Stop

[ThreadSafe]
public method Stop → ()

Stops the thread.

The thread will be signalled to stop. It will not have been terminated when this method returns. Use the Join method for waiting for the termination of the thread.

If the thread has already been stopped, the method returns silently.

Public / Attributes

Argument

public attribute Argument → (get,set)

value : object

The argument object.

The argument object to pass to the thread main method.

The argument object may only be set before Start is called.

Defaults to null.

See also

IThreadMain.Run

Error

public attribute Error → (get)

value : TinmanError

The TinmanError object or null.

The error info of the exception that has occurred in the Run method of the threads main method (see IThreadMain).

Is​Alive

public attribute IsAlive → (get)

value : bool

true if this thread is running, false if it is not.

Returns if this thread is running.

Log​On​Error

public attribute LogOnError → (get,set)

value : bool

true to output a log message, false to fail silently (i.e. the owning code is responsible for error processing, see Error).

Output a log message when the thread terminates due to an unhandled exception?

Defaults to true.

Name

public attribute Name → (get,set)

value : string

The thread name.

The thread name.

The thread name may only be set before Start is called.

Defaults to null.

Priority

public attribute Priority → (get,set)

value : ThreadPriority

The thread priority.

Gets or sets the thread priority.

The thread priority may only be set before Start is called.

Defaults to ThreadPriority.Normal.

Thread​Main

[OwnerValue]
public attribute ThreadMain → (get,set)

value : IThreadMain

The thread main method.

Gets or sets the thread main method.

The thread main method must be set before Start is called.

Logging

Logger

public static readonly attribute Logger → (ILogger)

The logger object of this class.