WaitEvent Shared Method

Thread.WaitEvent Shared Method

Wait for, test and clear events received by the current thread. Returns a mask indicating the received events.

received_events =Thread.WaitEvent(event_mask, time_out)

Prerequisites

None

Parameters

event_mask

A required numeric expression that specifies the set of events to wait for. Each bit in event_mask corresponds to a different event. Multiple events may be specified. The maximum event is 16, so the maximum value for event_mask is &HFFFF.

If event_mask is 0, no wait occurs, no events are cleared, and all received events are returned.

time_out

A required numeric expression that specifies the maximum time, in milliseconds, to wait if no matching events are received. The maximum wait time is 2147 seconds.

If 0, this method does not wait, but only tests pending events against the event_mask. If < 0, this method does not timeout and waits forever.

Remarks

The returned value is a bit mask indicating events that have been received. Bit 0 (mask value &H0001) corresponds to event 1. The mask indicates either all pending events, or only those matched by event_mask, as described below.

The behavior of this method depends on the combination of parameters as described in Table 19-107.

Table 19-107: WaitEvent Shared Method
event_mask Value	time_out Value	Description
0	N.A.	The method does not wait for or clear any events, but simply returns a bit mask indicating all received events.
<> 0	0	The method does not wait. It clears all events that match the bits in event_mask. It returns a bit mask indicating the events that were cleared. This parameter combination may be used to return and clear specific received events without waiting.
<> 0	> 0	The method waits until at least one event corresponding to a bit in event_mask has been received. If a matching event was previously received and not cleared, the method does not wait. Before returning, it clears all pending events that match the bits in event_mask, and returns a bit mask indicating the events that were cleared. If no matching event is received before the timeout period, this method returns a value of 0.
<> 0	< 0	This case is the same as "event_mask <> 0, time_out > 0" case except that it waits indefinitely for the events, and never times out.

Events are synchronization messages that are sent from one thread executing a GPL project to another thread that is executing a GPL project. Utilizing events has several advantages over setting and polling a global variable:

The thread waiting for an event uses almost no CPU time, as opposed to polling a global variable.
There is very little latency between when a message is sent and when the target thread wakes up and handles the event, as opposed to a polling method where the worst-case latency is the polling period.

Each thread can handle up to 16 different events. These 16 events are independent of the events for all other threads. An event is specified by the target thread and a bit within the thread’s event_mask.

Events handled by WaitEvent are automatically cleared, except for the special case when event_mask = 0. A receiving thread can simply loop waiting for events, checking the returned bit mask, and servicing whatever events bits are set. If the WaitEventevent_mask specifies more than one event, be sure to check all possible events, since more than one event may be returned simultaneously and be cleared.

In a client-server situation, a client thread can place a command in a global variable, and then send an event to the server. When the server receives the event, it can examine the global variable to determine the detailed command.

Examples

Public main_thread As Thread
 
Public Sub Main
    Dim t1 As New Thread("Testthread") 
    main_thread = Thread.CurrentThread
    t1.Start 
    t1.SendEvent(&H10)                  ' Send event 5 to thread 
    Thread.WaitEvent(&H8, -1)           ' Wait for event 4, clear it 
    Console.Writeline ("Main thread event received") 
End Sub 
 
Public Sub Testthread 
    Dim events As Integer
    events = Thread.WaitEvent(&H10,100) ' Wait with timeout 
    If events = 0 Then
        Console.Writeline ("Testthread event timeout") 
    Else 
        Console.Writeline ("Testthread event received") 
    End If 
    main_thread.SendEvent(&H8)          ' Send event 4 back to main thread 
End Sub