GAP (hpc) - Chapter 6: Thread functions

Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 Ind
[Top of Book] [Contents] [Previous Chapter] [Next Chapter]

[MathJax off]

6 Thread functions
6.1 Thread functions
6.1-1 CreateThread
6.1-2 WaitThread
6.1-3 CurrentThread
6.1-4 ThreadID
6.1-5 KillThread
6.1-6 PauseThread
6.1-7 ResumeThread
6.1-8 InterruptThread
6.1-9 SetInterruptHandler
6.1-10 NewInterruptID
6.1-11 MAX_INTERRUPT

### 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

`‣ CreateThread`( func[, arg1, ..., argn] ) | ( function )

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

`‣ WaitThread`( threadID ) | ( function )

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

`‣ CurrentThread`( ) | ( function )

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

##### 6.1-4 ThreadID

`‣ ThreadID`( thread ) | ( function )

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

`‣ KillThread`( thread ) | ( function )

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

`‣ PauseThread`( thread ) | ( function )

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

`‣ ResumeThread`( thread ) | ( function )

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

`‣ InterruptThread`( thread, interrupt ) | ( function )

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

`‣ SetInterruptHandler`( interrupt, handler ) | ( function )

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

`‣ NewInterruptID`( ) | ( function )

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

`‣ MAX_INTERRUPT` | ( global variable )

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).

[Top of Book] [Contents] [Previous Chapter] [Next Chapter]
Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 Ind

generated by GAPDoc2HTML