Kōtuku Manual

Threads are created and managed by the Thread class.

The Thread class provides the means to execute and manage threads within an application.

The following code illustrates how to create a temporary thread that is automatically destroyed after the thread_entry() function has completed:

static ERR thread_entry(objThread *Thread) {
   return ERR::Okay;
}

objThread::create thread = { fl::Routine(thread_entry), fl::Flags(THF::AUTO_FREE) };
if (thread.ok()) thread->activate();

To initialise the thread with data, set Data prior to execution and read the Data field from within the thread routine.

Structure

The Thread class consists of the following fields:

Access

Name

Type

Comment

Callback FUNCTION This function will be called when the thread finishes.

Set a function reference here to receive a notification when the thread finishes processing. The callback will be executed in the context of the main program loop to minimise resource locking issues.

The prototype for the callback routine is void Callback(objThread *Thread).

Data kt::vector<int8_t> Storage for custom client data.

The Data field is a vector of bytes that can be used to store custom data for the thread. There are no limits associated with its use, but care should be taken if both the thread and its creator can modify its content at any time. Reserving the size of the vector in advance is recommended if the data is to be actively shared.

Error ERR Reflects the error code returned by the thread routine.

Flags THF Optional flags can be defined here.

Name	Description
THF::AUTO_FREE	Automatically destroy the Thread object when the user routine has completed.

Routine FUNCTION This function will be called when the thread starts.

The routine that will be executed when the thread is activated must be specified here. The function prototype is ERR routine(objThread *Thread).

When the routine is called, a reference to the thread object is passed as a parameter. Once the routine has finished processing, the resulting error code will be stored in the thread object's Error field.

Actions

The following actions are currently supported:

	Activate	Spawn a new thread that calls the function referenced in the Routine field.
	Deactivate	Stops a thread.
	`ERR acDeactivate(*Object)` Deactivating an active thread will cause it to stop immediately. Stopping a thread in this manner is dangerous and could result in an unstable application.

Thread Class

Structure

Actions

THF Type