10.2 Programming threads

To start a new thread, the BeginThread function should be used. It has one mandatory argument: the function which will be executed in the new thread. The result of the function is the exit result of the thread. The thread function can be passed a pointer, which can be used to access initialization data: The programmer must make sure that the data is accessible from the thread and does not go out of scope before the thread has accessed it.

Type  
  TThreadFunc = function(parameter : pointer) : ptrint;  
 
function BeginThread(sa : Pointer;  
                     stacksize : SizeUInt;  
                     ThreadFunction : tthreadfunc;  
                     p : pointer;  
                     creationFlags : dword;  
                     var ThreadId : TThreadID) : TThreadID;

This rather complicated full form of the function also comes in more simplified forms:

function BeginThread(ThreadFunction : tthreadfunc) : TThreadID;  
 
function BeginThread(ThreadFunction : tthreadfunc;  
                     p : pointer) : TThreadID;  
 
function BeginThread(ThreadFunction : tthreadfunc;  
                     p : pointer;  
                     var ThreadId : TThreadID) : TThreadID;  
 
function BeginThread(ThreadFunction : tthreadfunc;  
                     p : pointer;  
                     var ThreadId : TThreadID;  
                     const stacksize: SizeUInt) : TThreadID;

The parameters have the following meaning:

ThreadFunction
is the function that should be executed in the thread.
p
If present, the pointer p will be passed to the thread function when it is started. If p is not specified, Nil is passed.
ThreadID
If ThreadID is present, the ID of the thread will be stored in it.
stacksize
if present, this parameter specifies the stack size used for the thread.
sa
signal action. Important for linux only.
creationflags
these are system-specific creation flags. Important for Windows and os/2 only.

The newly started thread will run until the ThreadFunction exits, or until it explicitly calls the EndThread function:

procedure EndThread(ExitCode : DWord);  
procedure EndThread;

The exitcode can be examined by the code which started the thread.

The following is a small example of how to program a thread:

{$mode objfpc}  
 
uses  
  sysutils {$ifdef unix},cthreads{$endif} ;  
 
const  
  threadcount = 100;  
  stringlen = 10000;  
 
var  
   finished : longint;  
 
threadvar  
   thri : ptrint;  
 
function f(p : pointer) : ptrint;  
 
var  
  s : ansistring;  
 
begin  
  Writeln(’thread ’,longint(p),’ started’);  
  thri:=0;  
  while (thri<stringlen) do  
    begin  
    s:=s+’1’;  
    inc(thri);  
    end;  
  Writeln(’thread ’,longint(p),’ finished’);  
  InterLockedIncrement(finished);  
  f:=0;  
end;  
 
var  
   i : longint;  
 
begin  
   finished:=0;  
   for i:=1 to threadcount do  
     BeginThread(@f,pointer(i));  
   while finished<threadcount do ;  
   Writeln(finished);  
end.  

The InterLockedIncrement is a thread-safe version of the standard Inc function.

To provide system-independent support for thread programming, some utility functions are implemented to manipulate threads. To use these functions the thread ID must have been retrieved when the thread was started, because most functions require the ID to identify the thread on which they should act:

function SuspendThread(threadHandle: TThreadID): dword;  
function ResumeThread(threadHandle: TThreadID): dword;  
function KillThread(threadHandle: TThreadID): dword;  
function WaitForThreadTerminate(threadHandle: TThreadID;  
                                TimeoutMs : longint): dword;  
function ThreadSetPriority(threadHandle: TThreadID;  
                           Prio: longint): boolean;  
function ThreadGetPriority(threadHandle: TThreadID): Integer;  
function GetCurrentThreadId: dword;  
procedure ThreadSwitch;

The meaning of these functions should be clear:

SuspendThread
Suspends the execution of the thread.
ResumeThread
Resumes execution of a suspended thread.
KillThread
Kills the thread: the thread is removed from memory.
WaitForThreadTerminate
Waits for the thread to terminate. The function returns when the thread has finished executing, or when the timeout expired.
ThreadSetPriority
Sets the execution priority of the thread. This call is not always allowed: your process may not have the necessary permissions to do this.
ThreadGetPriority
Returns the current execution priority of the thread.
GetCurrentThreadId
Returns the ID of the current thread.
ThreadSwitch
Allows other threads to execute at this point. This means that it can cause a thread switch, but this is not guaranteed, it depends on the OS and the number of processors.