MthrWaitMultiple

See also

User Guide:

Multi-threading

Reference:

MthrAlloc MthrControl MthrWait

Availability

Available in MIL-Lite

Available in MIL

Available on Windows

Available on Linux

Available on Non-Matrox computer

Available on Matrox 4Sight-X

Available on Matrox 4Sight GP/GPm

Available on Matrox Supersight

Function map

Examples

dispatcher.cpp
mpmenu.cpp
multipledatamatrixcoderead.cpp

Function Map

Parameter Associations

Table:	For specifying the wait option
+ combination:	For specifying that the thread must wait for all the events to change state
+ combination:	For events

Return value

Compilation information

Synopsis

Perform a wait operation on multiple MIL events.

Syntax

MIL_INT MthrWaitMultiple(

const MIL_ID *EventArrayIdPtr,	//in
MIL_INT EventArraySize,	//in
MIL_INT64 WaitOption,	//in
MIL_INT *StatePtr	//out

)

Description

This function allows you to synchronize the execution of threads by forcing the current thread to wait for one of the MIL events identified in a user-supplied array to change state. To force the current thread to wait for all events identified in the user-supplied array to change state, add M_ALL_OBJECTS to M_EVENT_WAIT or M_EVENT_SYNCHRONIZE when setting the WaitOption parameter.

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see if there is complementary information.

Parameters

This function is not supported on the selected boards.

Parameters

EventArrayIdPtr

Accepts the address of one of the following (see the Parameter associations section for specifics on which is expected):

array of type MIL_ID [optionally, in C++: a reference to a constant std::vector<MIL_ID> ] (and a maximum array rank for C# of 1)
Required array size:(EventArraySize)

Specifies the address of a user-supplied array that contains the identifiers of the MIL events for which to wait. All MIL event identifiers must be allocated, using MthrAlloc(), on the same system.

EventArraySize

Specifies the number of events in the user-supplied array.

When using a standard vector (std::vector) overload function in C++, you can pass M_DEFAULT to this parameter and MIL will automatically determine the size based on the number of items in the vector passed to the EventArrayIdPtr parameter.

WaitOption

Specifies the wait option.

See the Parameter associations section for possible values that can be specified.

StatePtr

Specifies the address in which to write the returned value.

Since the MthrWaitMultiple() function also returns the requested information, you can set this parameter to M_NULL.

See the Parameter associations section for possible values that can be returned.

Parameter associations

The table below lists possible values for the WaitOption parameter and possible values returned to the StatePtr parameter.

For specifying the wait option

For specifying the wait option
WaitOption		Description
	StatePtr - Possible values returned	Description
M_EVENT_SYNCHRONIZE +		Allows the current thread to continue executing while forcing its corresponding on-board thread, located on the same board as the events identified in the user-supplied array, to wait for one of the events to be in an M_SIGNALED state or for a time out to occur. If the events are allocated on a board that supports asynchronous calls, MIL issues the wait command to that board and allows the current thread to continue executing. Its corresponding thread, on that board, waits for an event identified in the array to change to a signaled state. Any subsequent calls issued on that on-board thread are executed only after an event is signaled. If the specified event is not allocated on a board that supports asynchronous calls, this value behaves like M_EVENT_WAIT in that it forces the current thread to wait until the event is signaled or timed out. MthrWaitMultiple() set to M_EVENT_SYNCHRONIZE always returns M_UNKNOWN. If the event that changes state is of the type that is reset automatically (M_AUTO_RESET), the state of the event is reset to M_NOT_SIGNALED, after the wait operation. (summarize) Allows the current thread to continue executing while forcing its corresponding on-board thread, located on the same board as the events identified in the user-supplied array, to wait for one of the events to be in an M_SIGNALED state or for a time out to occur. (more details...)
	M_UNKNOWN	Specifies that WaitOption parameter is set to M_EVENT_SYNCHRONIZE.
M_EVENT_WAIT +		Forces the current thread to wait for an event, identified in the user-supplier array, to change to the M_SIGNALED state or for the events to timeout. The current thread will not continue until one of the specified events has changed to a signaled state or timed out. If the event that changed state is of the type that is reset automatically (M_AUTO_RESET), after the wait operation, the state of the event is reset to M_NOT_SIGNALED. (summarize) Forces the current thread to wait for an event, identified in the user-supplier array, to change to the M_SIGNALED state or for the events to timeout. (more details...)
	M_TIMEOUT	Specifies that none of the events in the array have changed state before the time out interval is reached.
	Value	Specifies the index of the event that changed to the M_SIGNALED state.

Combination value for the values listed in For specifying the wait option.

You can add the following value to the above-mentioned values to specify that the current thread must wait for all events to change state or for a timeout to occur.

For specifying that the thread must wait for all the events to change state
WaitOption		Description
	StatePtr - Possible values returned	Description
M_ALL_OBJECTS		Waits for all the events identified in the user-supplied array to be in a M_SIGNALED state or for the events to time out. (summarize) Waits for all the events identified in the user-supplied array to be in a M_SIGNALED state or for the events to time out. (more details...)
	M_SIGNALED	Specifies that all the events have changed state.
	M_TIMEOUT	Specifies that the time out interval has been reached before all the events in the array have changed state.
	M_UNKNOWN	Specifies that WaitOption parameter is set to M_EVENT_SYNCHRONIZE.

Combination value for the values listed in For specifying the wait option.

You can add the following value to the above-mentioned values to set the time interval after which an event is considered to be timed out.

For events

Combination value

Description

M_EVENT_TIMEOUT(

MIL_INT EventTimeOut

)

Specifies the time interval after which an event is considered to be timed out.

(summarize)

Specifies the time interval after which an event is considered to be timed out.

(more details...)

Parameters

EventTimeOut

Sets the required timeout interval, in msecs. Set this parameter to the following:

M_INFINITE

Specifies an infinitely long timeout interval.

0	Same as M_INFINITE.

Value > 0

Sets the timeout interval to a user-defined value, in msecs.

Return value

The returned value for M_EVENT_WAIT is the index of the event that changed to the M_SIGNALED state, or M_TIMEOUT if none of the events in the array changed state before the time out interval is reached. For M_EVENT_WAIT + M_ALL_OBJECTS, the returned value is M_SIGNALED if all the events specified in the array changed state, or M_TIMEOUT if the time out interval is reached before all the events in the array have changed state. For M_EVENT_SYNCHRONIZE, the returned value is M_UNKNOWN.

Compilation information

Header	Include mil.h.
Library	Use mil.lib.
DLL	Requires mil.dll.