xHarbour Reference Documentation > Function Reference

SubscribeNow()

Subscribes for notifications on a Mutex and discards pending notifications.

Syntax

SubscribeNow( <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 SubscribeNow() 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 of Notify() is returned by SubscribeNow().

Description

Function SubscribeNow() is used in the same way as Subscribe(). The only difference is that SubscribeNow() voids all possibly pending notifications that may have been issued on <pMutexHandle> while SubscribeNow() is being executed. This guarantees that the current thread is put on hold until another thread notifies the Mutex after SubscribeNow() has returned. Refer to Subscribe() for detailed information on the SubScribe()/Notify() protocol.

Info

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