class sys.Thread

Overview

This class provides standard facilities for creating and managing threads. More…

import "sys_Thread.jnc"

class Thread {
    // fields

    uintptr_t readonly m_threadId;

    // construction

    construct();
    destruct();

    // methods

    bool errorcode start(void function* func());
    bool wait(uint_t timeout = -1);
    void waitAndClose(uint_t timeout = -1);
    bool terminate();
};

Detailed Documentation

This class provides standard facilities for creating and managing threads.

Each instance of sys.Thread class manages a single thread within the program. Unlike the usual approach taken in most implementations of threading frameworks, in Jancy you don’t need to subclass sys.Thread and then override some kind of run method.

Instead, you just start a new thread directly by passing a thread function to start method. You can pass arbitrary number of parameters to the newly created thread using Jancy feature of partial application for function pointers.

After a thread is created, you can wait for its completion with wait and waitAndClose methods or forcefully terminate it with terminate method.

Code sample:

import "sys_Thread.jnc"

workerThread(
    int param1,
    int param2
) {
    // ...
}

int main() {
    // ...

    sys.Thread thread1;
    sys.Thread thread2;

    thread1.start(workerThread ~(1, 2));
    thread2.start(workerThread ~(3, 4));
}

Fields

uintptr_t readonly m_threadId

Holds native TID(thread identifier) of the thread controlled by sys.Thread object. The field is updated in start method; accessing it when the thread has not been started yet or closed yields 0.

Methods

bool errorcode start(void function* func())

Attempt to start a new thread with a thread function pointed to by func argument. Pass additional arguments to the thread function using partial application.

Returns true on success. If a new thread could not be started, system error supplied by operating system is set and then the function returns false [1].

Calling this method on a non-closed thread fails immediatly.

bool wait(uint_t timeout = -1)

Waits until thread finishes. When it happens, wait returns true, but the thread remains open, so its TID is not released and can still be accessed using m_threadId field.

If timeout parameter is not -1 then it’s a wait with a time limit. If the thread does not terminate until timeout expires, wait return false. Timeout is expressed in milliseconds.

void waitAndClose(uint_t timeout = -1)

Waits until event thread finishes. When it happens, waitAndClose closes TID and returns true. Accessing m_threadId after that will yield 0.

If timeout parameter is not -1 then it’s a wait with a time limit. If the thread does not terminate until timeout expires, wait return false. Timeout is expressed in milliseconds.

bool terminate()

Forcefully terminates thread.

Returns true on success. If the thread could not be terminated, system error supplied by operating system is set and then the function returns false [1].

Note that it’s not recommended to ever call this function under normal circumstances. The preferred approach should be setting up a normal thread termination infrastructure using sys.Event (or sys.NotificationEvent).

Footnotes