MthrWait

See also

User Guide:

Multi-threading Multiple cameras

Reference:

MsysAlloc MthrAlloc MthrControl

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

Function Map

Table:

For specifying the thread context or event identifier

- WaitOption

Table:	For specifying the wait option for threads
+ combination:	For threads
Table:	For specifying the wait option for events
+ combination:	For events

- StatePtr

Table:

For writing the state of the specified thread or event

Return value

Compilation information

Synopsis

Perform a wait operation on a MIL thread or event.

Syntax

MIL_INT MthrWait(

MIL_ID ThreadOrEventId,	//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 the completion of the specified thread or the change of state of the specified event.

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

ThreadOrEventId

Specifies the identifier of the MIL thread context or event with which to be synchronized. This parameter can also be set to the MIL identifier of a system.

This parameter should be set to one of the following values:

For specifying the thread context or event identifier
Value	Description
M_DEFAULT	Specifies the default MIL thread context identifier associated with the current Host thread.
MIL event identifier	Specifies the identifier of a user-allocated MIL event (MthrAlloc()).
MIL system identifier	Specifies the identifier of a valid system identifier (MsysAlloc()).
MIL thread context identifier	Specifies the identifier of a user-allocated MIL thread context (MthrAlloc()).

WaitOption

Specifies the wait option.

The following wait options are available for threads.

For specifying the wait option for threads
Value	Description
M_THREAD_END_WAIT +	Forces the current thread to wait for the end (the death) of the specified thread. The thread currently running cannot be the thread for which you are waiting. This option can only be used for a thread allocated using MthrAlloc() with M_THREAD. If the ThreadOrEventId parameter is set to a MIL system identifier, using this wait option results in an error. (summarize) Forces the current thread to wait for the end (the death) of the specified thread. (more details...)
M_THREAD_WAIT	Forces the current thread to wait for the completion of all functions that are not asynchronous grab commands, in the specified thread's command queue. If the ThreadOrEventId parameter was set to a MIL system identifier, the current thread waits for the completion of the current thread on the specified system. (summarize) Forces the current thread to wait for the completion of all functions that are not asynchronous grab commands, in the specified thread's command queue. (more details...)

Combination value for M_THREAD_END_WAIT.

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

For threads

Combination value

Description

M_THREAD_TIMEOUT(

MIL_INT ThreadTimeOut

)

Specifies the time interval after which a thread is considered to be timed out.

(summarize)

Specifies the time interval after which a thread is considered to be timed out.

(more details...)

Parameters

ThreadTimeOut

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.

The following wait options are available for events.

For specifying the wait option for events
Value	Description
M_EVENT_SYNCHRONIZE +	Allows the current thread to continue with execution while forcing its corresponding on-board thread, located on the same board as the specified event, to wait for the specified event to be in an M_SIGNALED state. If the specified event is allocated on a board that supports asynchronous calls, MIL issues the wait command to that board and allows the current thread to proceed executing while its corresponding thread on that board is waiting for the specified event to change to a signaled state. Any subsequent calls issued on that on-board thread are executed only after the 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. MthrWait() set to M_EVENT_SYNCHRONIZE always returns M_UNKNOWN. If the event 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 with execution while forcing its corresponding on-board thread, located on the same board as the specified event, to wait for the specified event to be in an M_SIGNALED state. (more details...)
M_EVENT_WAIT +	Forces the current thread to wait for the specified event to be in an M_SIGNALED state or for the event to be timed out. The current thread will not proceed with execution until the specified event has changed to a signaled state or timed out. If the event 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 the specified event to be in an M_SIGNALED state or for the event to be timed out. (more details...)

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

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.

StatePtr

Specifies the address of the variable in which to write the state of the specified thread or event.

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

For writing the state of the specified thread or event
Value	Description
M_SIGNALED	Specifies that the specified thread has successfully completed or the state of the specified event has changed. This state applies for M_THREAD_END_WAIT, M_THREAD_WAIT, and M_EVENT_WAIT. (summarize) Specifies that the specified thread has successfully completed or the state of the specified event has changed. (more details...)
M_TIMEOUT	Specifies that the thread or event on which the current thread was waiting timed out. This state applies for M_THREAD_END_WAIT and M_EVENT_WAIT. (summarize) Specifies that the thread or event on which the current thread was waiting timed out. (more details...)
M_UNKNOWN	Specifies that the specified thread is set to M_EVENT_SYNCHRONIZE.

Return value

The returned value for M_THREAD_END_WAIT, M_THREAD_WAIT, and M_EVENT_WAIT is M_SIGNALED if the specified thread has successfully completed or if the state of the specified event has changed; it is M_TIMEOUT if the thread or event on which the current thread was waiting timed out. For M_EVENT_SYNCHRONIZE, the returned value is M_UNKNOWN.

Compilation information

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