xHarbour Reference Documentation > Function Reference

StopThread()

Stops a thread from outside.

Syntax

StopThread( <pThreadHandle>, [<pMutexHandle>] ) --> NIL

Arguments

<pThreadHandle>

This is the handle of the thread to stop running. A thread handle is returned from function StartThread().

<pMutexHandle>

Optionally, the handle of a Mutex owned by <pThreadHandle> can be passed. This causes NotifyAll() being called when the thread is stopped. All other threads blocked by <pMutexHandle> resume operation when the thread is terminated by the operating system.

Return

The return value is always NIL.

Description

Function StopThread() sends a thread termination request for <pThreadHandle> to the operating system, and halts the current thread until the requested second thread has finally terminated. If the second thread owns the Mutex <pMutexHandle>, all threads blocked by <pMutexHandle> are notified and resume operation when the thread represented by <pThreadHandle> has ended.

Be very cautiuos with StopThread(). This function instructs the operating system to terminate a running second thread defined with <pThreadHandle>. That means, the current thread executing StopThread() can stop a second thread from outside. The result of the second thread is undetermined, since it may be interrupted by the operating system at any programming instruction (the second thread could be terminated by the operating system within a FOR or DO WHILE loop, before a RETURN statement is executed).

It is highly recommended to use Mutexes to control the begin and end of a thread when the current thread requires the result of another thread.

Important:  StopThread() is different from KillThread(). When a thread calls StopThread(), it is suspended until the requested (second) thread has actually ended. KillThread(), in contrast, does not halt the current thread. KillThread() works asynchronously while Stopthread() works synchronously.

Info

See also:	HB_MutexCreate(), HB_MutexLock(), HB_MutexUnlock(), KillThread(), Notify(), StartThread(), StopThread()
Category:	Multi-threading functions , xHarbour extensions
Source:	vm\thread.c
LIB:	xhbmt.lib
DLL:	xhbmtdll.dll