xHarbour Reference Documentation > Function Reference

Subscribe()

Subscribes for notifications on a Mutex.

Syntax

Subscribe( <pMutexHandle>  , ;
           <nWaitMilliSecs>, ;
           [@<lNotified>]    ) --> xReturn

Arguments

<pMutexHandle>

This is the handle of the Mutex to subscribe, or listen, to. A mutex handle is returned by HB_MutexCreate().

<nWaitMilliSecs>

A numeric value specifying the maximum period of time to wait before the function returns when there is no notification on the Mutex. The unit for this value is 1/1000th of a second. If <nWaitMilliSecs> is omitted, the current thread waits infinitely for a notification, i.e. the function does not return until a notification is received.

@<lNotified>

When this parameter is passed by reference, it is assigned .T. (true) or .F. (false). True is assigned, when the thread executing Subscribe() is notified within the timeout period of <nWaitMilliSecs> from the thread that has locked the Mutex <pMutexHandle>.

Return

The function returns NIL, unless the thread which calls Notify() on the Mutex passes a second parameter to Notify(). This second parameter is returned by Subscribe().

Description

Function Subscribe() is the counterpart of Notify(), or NotifyAll(), respectively. The functions are used to control concurrent program execution between two ore more threads. The functions Notify() and Subscribe() can only be called in two different threads and require a common Mutex to operate on.

When a thread "A" calls SubScribe() with the Mutex <pMutexHandle>, this thread "A" is suspended for a time period of <nWaitMilliSecs>. Specifying nothing for the timeout period suspends thread "A" until another thread "B" calls Notify().

When thread "B" calls Notify() or NotifyAll() during the time period of <nWaitMilliSecs> on the same Mutex <pMutexHandle>, thread "A" resumes program execution.

As a result, function Subscribe() puts the current thread on hold until a second thread notifies the Mutex <pMutexHandle>, or the timeout period has expired. The timeout never expires when <nWaitMillisecs> is omitted, i.e. the current thread resumes only if the Mutex is notified by a second thread.

The parameter <lNotified> must be passed by reference to detect if the current thread resumes as a result of a notification by a second thread (<lNotified>==.T.) or due to the expiration of the timeout period of <nWaitMilliSec> (<lNotified>==.F.).

When thread "A" calls Subscribe() and thread "B" calls Notify(), the second parameter passed to Notify() in thread "B" defines the return value of Subscribe() in thread "A". That is, thread "B" can pass a value to thread "A" via the Subscribe()/Notify() protocol. All that is required is a Mutex which is subscribed to in thread "A", and notified in thread "B".

Info

See also:	GetCurrentThread(), GetThreadID(), HB_MutexCreate(), HB_MutexLock(), Notify(), NotifyAll(), StartThread(), SubscribeNow()
Category:	Multi-threading functions , Mutex functions , xHarbour extensions
Source:	vm\thread.c
LIB:	xhbmt.lib
DLL:	xhbmtdll.dll