Parasol Framework 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(thread);

To initialise the thread with data, call SetData() 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 A function reference that will be called when the thread is started.

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 APTR Pointer to initialisation data for the thread.

The Data field will point to a data buffer if the SetData() method has previously been called to store data in the thread object. It is paired with the DataSize field, which reflects the size of the data buffer.

DataSize INT The size of the buffer referenced in the Data field.

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 A function reference that will be called when the thread is started.

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.

StackSize INT The stack size to allocate for the thread.

The initial size of the thread's stack can be modified by setting this field. It may also be read prior to activation in order to check the default stack size. Changes to the stack size when the thread is active will have no effect.

On some platforms it may not be possible to preset the stack size and the provided value will be ignored.

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.
	Free	Remove the object and its resources.
	`ERR FreeResource(*Object)` Terminating a thread object will destroy the object unless the thread is currently active. If an attempt to free an active thread is made then it will be marked for termination so as to avoid the risk of system corruption.

Methods

The following methods are currently supported:

SetData

Attaches data to the thread.

ERR th::SetData(OBJECTPTR Object, APTR Data, INT Size)

Parameter	Description
Data	Pointer to the data buffer.
Size	Size of the data buffer. If zero, the pointer is stored directly, with no copy operation taking place.

Use the SetData() method prior to activating a thread so that it can be initialised with user data. The thread will be able to read the data from the Data field.

A copy of the provided data buffer will be stored with the thread object, so there is no need to retain the original data after this method has returned. In some cases it may be desirable to store a direct pointer value and bypass the copy operation. To do this, set the Size parameter to zero.

Error Codes

Okay	Operation successful.
Args	Invalid arguments passed to function.
AllocMemory	A call to AllocMemory() failed to create a new memory block.
NullArgs	Function call missing argument value(s)

Thread Class

Structure

Actions

Methods

THF Type