[MathJax off]

6 Thread functions

HPC-GAP has low-level functionality to support explicit creation of threads. In practice, programmers should use higher-level functionality, such as tasks, to describe concurrency. The thread functions described here exist to facilitate the construction of higher level libraries and are not meant to be used directly.

6.1 Thread functions

6.1-1 CreateThread

New threads are created with the function CreateThread. The thread takes at least one function as its argument that it will call in the newly created thread; it also accepts zero or more parameters that will be passed to that function.

The function returns a thread object describing the thread.

Only a finite number of threads can be active at a time (that limit is system-dependent). To reclaim the resources occupied by one thread, use the WaitThread (6.1-2) function.

6.1-2 WaitThread

The WaitThread function waits for the thread identified by threadID to finish; it does not return any value. When it returns, it returns all resources occupied by the thread it waited for, such as thread-local memory and operating system structures, to the system.

6.1-3 CurrentThread

The CurrentThread function returns the thread object for the current thread.

6.1-4 ThreadID

The ThreadID function returns a numeric thread id for the given thread. The thread id of the main thread is always 0.

gap> CurrentThread();
<thread #0: running>
gap> ThreadID(CurrentThread());
0

6.1-5 KillThread

The KillThread function terminates the given thread. Any region locks that the thread currently holds will be unlocked. The thread can be specified as a thread object or via its numeric id.

The implementation for KillThread is dependent on the interpreter actually executing statements. Threads performing system calls, for example, will not be terminated until the system call returns. Similarly, long-running kernel functions will delay termination until the kernel function returns.

Use of CALL_WITH_CATCH will not prevent a thread from being terminated. If you wish to make sure that catch handlers will be visited, use InterruptThread (6.1-8) instead. KillThread should be used for threads that cannot be controlled anymore in any other way but still eat system resources.

6.1-6 PauseThread

The PauseThread function suspends execution for the given thread. The thread can be specified as a thread object or via its numeric id.

The implementation for PauseThread is dependent on the interpreter actually executing statements. Threads performing system calls, for example, will not pause until the system call returns. Similarly, long-running kernel functions will not pause until the kernel function returns.

While a thread is paused, the thread that initiated the pause can access the paused thread's thread-local region.

gap> loop := function() while true do Sleep(1); od; end;;
gap> x := fail;;
gap> th := CreateThread(function() x := [1, 2, 3]; loop(); end);;
gap> PauseThread(th);
gap> x;
[ 1, 2, 3 ]

6.1-7 ResumeThread

The ResumeThread function resumes execution for the given thread that was paused with PauseThread (6.1-6). The thread can be specified as a thread object or via its numeric id.

If the thread isn't paused, ResumeThread is a no-op.

6.1-8 InterruptThread

The InterruptThread function calls an interrupt handler for the given thread. The thread can be specified as a thread object or via its numeric id. The interrupt is specified as an integer between 0 and MAX_INTERRUPT (6.1-11).

An interrupt number of zero (or an interrupt number for which no interrupt handler has been set up with SetInterruptHandler (6.1-9) will cause the thread to enter a break loop. Otherwise, the respective interrupt handler that has been created with SetInterruptHandler (6.1-9) will be called.

The implementation for InterruptThread is dependent on the interpreter actually executing statements. Threads performing system calls, for example, will not call interrupt handlers until the system call returns. Similarly, long-running kernel functions will delay invocation of the interrupt handler until the kernel function returns.

6.1-9 SetInterruptHandler

The SetInterruptHandler function allows the programmer to set up interrupt handlers for the current thread. The interrupt number must be in the range from 1 to MAX_INTERRUPT (6.1-11) (inclusive); the handler must be a parameterless function (or fail to remove a handler).

6.1-10 NewInterruptID

The NewInterruptID function returns a previously unused number (starting at 1). These numbers can be used to globally coordinate interrupt numbers.

gap> StopTaskInterrupt := NewInterruptID();
1
gap> SetInterruptHandler(StopTaskInterrupt, StopTaskHandler);

6.1-11 MAX_INTERRUPT

The global variable MAX_INTERRUPT is an integer containing the maximum value for the interrupt arguments to InterruptThread (6.1-8) and SetInterruptHandler (6.1-9).

generated by GAPDoc2HTML