MthrControl

See also

User Guide:

Best practice Multi-threading Transparent multi-core use

Reference:

MobjControl MobjInquire MsysAlloc MsysControl MsysInquire MthrAlloc MthrInquire

Availability

Available in MIL-Lite

Available in MIL

Available on Windows

Available on Linux

Partially supported on:

Partially supported on Host system (a)

Partially supported on Matrox GigE Vision driver (MIL 10, Update 25, Update 54, or Update 85)* (c)

Partially supported on Matrox Morphis (g)

Partially supported on Matrox Morphis QxT (h)

Partially supported on Matrox Solios eA/XA (l)

Partially supported on Matrox Solios ecl/xcl/ev-cl (m)

Partially supported on Matrox USB3 Vision driver (Update 19) (o)

Partially supported on Matrox Iris GTR (Update 28 or Update 68) (t)

Partially supported on Matrox GenTL driver (Update 34) (v)

Partially supported on Matrox Indio (Update 53 or Update 68) (w)

Partially supported on Matrox Concord PoE with ToE (Update 82) (z)

Fully supported on:

Fully supported on Matrox Orion HD (i)

Fully supported on Matrox Radient eCL (j)

Fully supported on Matrox Radient eV-CXP (MIL 10 or Update 29)* (k)

Fully supported on Matrox RadientPro-CL (Update 7) (p)

Fully supported on Matrox Radient eV-CL (Update 27 or 74) (r)

Fully supported on Matrox Clarity UHD (Update 36 or 76) (u)

Fully supported on Matrox Rapixo CXP (Update 75 or Update 84) (y)

Fully supported on Matrox Rapixo CL Pro (Update 96) (aa)

* Refer to the MIL system-specific information
in the MIL Reference for the minimum update required.

For any information regarding a MIL system added during a MIL Update, see the MIL system’s release note

Available on Non-Matrox computer

Available on Matrox 4Sight-X

Available on Matrox 4Sight GP/GPm

Available on Matrox Supersight

Function map

Examples

c3ddisplaymanager.cpp
dispatcher.cpp
dmilobjecttracking.cpp
mapptrace.cpp
mapptrace.cs
mapptrace.vb
mdigitizer.cpp
mpmenu.cpp
mthread.cpp
mthread.cs
mthread.vb
multicameradisplay.cpp
multicastmonitor.cpp
multicastslave.cpp
multipledatamatrixcoderead.cpp

Function Map

- ThreadEventOrMutexId

Table:

For specifying the identifier of a user-allocated MIL thread context, event, or mutex

- ControlType

- ControlValue

Parameter Associations

Table:	For thread contexts
Table:	For controlling MIL events
Table:	For controlling a MIL mutex

Type-specific versions of the function when using a C compiler under 64-bit

Compilation information

Synopsis

Control a MIL thread context, MIL event, or MIL mutex setting.

Syntax

void MthrControl(

MIL_ID ThreadEventOrMutexId,	//in
MIL_INT64 ControlType,	//in
MIL_DOUBLE ControlValue	//in

)

Description

This function controls a MIL thread context, MIL event, or MIL mutex setting. Most of these control type settings can be inquired using MthrInquire().

Note that when using a C compiler (not a C++ or other compiler) in 64-bit mode, MthrControl() internally calls the MIL_INT64 version of this function (MthrControlInt64()). If you need to pass floating-point values, call the MIL_INT64 version of this function (MthrControlDouble()).

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 which MIL system’s documentation you should use in its place and any possible differences.

Parameters

This function is not supported on the selected boards.

This function reference has not been updated for the selected MIL system. To show the content of this page, choose a second MIL system; refer to the MIL system's release note to see which MIL system’s documentation to choose and any possible differences.

Parameters

ThreadEventOrMutexId

Specifies the identifier of a user-allocated MIL thread context, event, or mutex, allocated using MthrAlloc(). This parameter can also be set to the MIL identifier of a system.

For specifying the identifier of a user-allocated MIL thread context, event, or mutex
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 mutex identifier	Specifies the identifier of a user-allocated MIL mutex (MthrAlloc()).
MIL system identifier	Specifies the identifier of a valid system identifier (MsysAlloc()). When the parameter is set to the MIL identifier of a system, the function inquires about the current thread on the particular system. (summarize) Specifies the identifier of a valid system identifier (MsysAlloc()). (more details...)
MIL thread context identifier	Specifies the identifier of a user-allocated MIL thread context (MthrAlloc()).

ControlType

Specifies the type of setting to control.

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

ControlValue

Specifies the new value to assign to the setting specified by the ControlType parameter.

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

Parameter associations

The tables below list possible values for the ControlType and ControlValue parameters.

For thread contexts
For controlling MIL events
For controlling a MIL mutex

The following ControlType and corresponding ControlValue settings can be specified to control MIL thread contexts:

For thread contexts
ControlType		Description		MIL system-specific tooltip (‡)
	ControlValue	Description
M_ACCELERATOR		Sets whether the thread uses hardware acceleration. Hardware acceleration speeds up the execution of certain functions in a thread. Use MsysInquire() with M_ACCELERATOR_PRESENT to learn if your Matrox imaging board has an accelerator. INQ (summarize) Sets whether the thread uses hardware acceleration. INQ (more details...)																						‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	w U53	y U75	z	aa
	M_DISABLE	Specifies not to use hardware acceleration.		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	w U53	y U75	z	aa
	M_ENABLE	Specifies to use hardware acceleration. This is the default value. (summarize) Specifies to use hardware acceleration. (more details...)		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	w U53	y U75	z	aa
M_BUS_MASTER_COPY_MODE		Sets the synchronization mode for copy operations when they are driven by your imaging board (bus master). In this case, the current setting for M_THREAD_MODE does not effect the synchronization mode. INQ (summarize) Sets the synchronization mode for copy operations when they are driven by your imaging board (bus master). INQ (more details...)		‡			g	h	i	j	k M10	l	m		p	r U27		u U36			y U75		aa
	M_DEFAULT	Same as M_SYNCHRONOUS.		‡			g	h	i	j	k M10	l	m		p	r U27		u U36			y U75		aa
	M_ASYNCHRONOUS	Specifies that when possible, control will be returned to the imaging board (bus master) immediately after a copy operation is launched.		‡			g	h	i	j	k M10	l	m		p	r U27		u U36			y U75		aa
	M_SYNCHRONOUS	Specifies that the execution of a copy operation must be completed before returning control to the imaging board (bus master).		‡			g	h	i	j	k M10	l	m		p	r U27		u U36			y U75		aa
M_NODE_SELECT		Sets the MIL system where MIL functions will run in the thread, when running multiple systems in DMIL. (summarize) Sets the MIL system where MIL functions will run in the thread, when running multiple systems in DMIL. (more details...)		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	w U53	y U75	z	aa
	M_DEFAULT	Specifies that the MIL system on which the MIL functions will run is selected automatically.		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	w U53	y U75	z	aa
	MIL system identifier	Specifies a valid system identifier, which forces all MIL functions to run on this system. When running a monitoring model DMIL setup, to specify that MIL functions must run on a monitored computer, the monitored computer must first publish its system identifier, using MobjControl(). Once the system identifier is published, the monitoring computer must inquire it, using MobjInquire(), before using it with this control value. (summarize) Specifies a valid system identifier, which forces all MIL functions to run on this system. (more details...)		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	w U53	y U75	z	aa
M_THREAD_COMMANDS_ABORT		Cancels all calls queued in the thread. The remainder of the application is executed. (summarize) Cancels all calls queued in the thread. (more details...)		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	w U53	y U75	z	aa
	M_DEFAULT	Implements the default behavior.		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	w U53	y U75	z	aa
M_THREAD_MODE		Sets the execution mode of the thread. Note that a thread can only work in asynchronous mode if threads allocated on the same system can execute in asynchronous mode (MsysControl() with M_THREAD_MODE). If they can only execute in synchronous mode, the specified thread will work in synchronous mode regardless of this setting. INQ (summarize) Sets the execution mode of the thread. INQ (more details...)		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	w U53	y U75	z	aa
			MIL system specific
			Note that the specified synchronization mode does not affect copy operations. Use M_BUS_MASTER_COPY_MODE to specify the required mode for copying.	‡			g	h				l	m
	M_DEFAULT	Same as M_ASYNCHRONOUS.		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	w U53	y U75	z	aa
	M_ASYNCHRONOUS	Specifies that the thread will execute in asynchronous mode, if possible. In this mode, control is returned to the Host immediately after a MIL function is sent to the processor of the thread's associated system (when the system and function allow an immediate return). (summarize) Specifies that the thread will execute in asynchronous mode, if possible. (more details...)		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	w U53	y U75	z	aa
	M_SYNCHRONOUS	Specifies that the thread will execute in synchronous mode. In this mode, the execution of a MIL function sent to the processor of the thread's associated system must be completed (execution terminated) before returning control to the Host. (summarize) Specifies that the thread will execute in synchronous mode. (more details...)		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	w U53	y U75	z	aa
M_THREAD_PRIORITY		Sets the priority status of the thread. INQ (summarize) Sets the priority status of the thread. INQ (more details...)		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	w U53	y U75	z	aa
	M_ABOVE_NORMAL	Specifies that the thread is above normal priority. Only time critical threads will be executed before it. (summarize) Specifies that the thread is above normal priority. (more details...)		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	w U53	y U75	z	aa
	M_BELOW_NORMAL	Specifies that the thread is below normal priority. Threads of normal, above normal, and time critical priority will be executed before it. (summarize) Specifies that the thread is below normal priority. (more details...)		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	w U53	y U75	z	aa
	M_IDLE	Specifies that the thread is idle. The thread will remain idle until its priority status is changed. (summarize) Specifies that the thread is idle. (more details...)		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	w U53	y U75	z	aa
	M_LOWEST	Specifies that the thread is of the lowest priority. All other non-idle threads will be executed before it. (summarize) Specifies that the thread is of the lowest priority. (more details...)		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	w U53	y U75	z	aa
	M_NORMAL	Specifies that the thread is of normal priority. Threads of above normal and time critical priority will be executed before it. This is the default value. (summarize) Specifies that the thread is of normal priority. (more details...)		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	w U53	y U75	z	aa
	M_TIME_CRITICAL	Specifies that the thread is time critical. Time critical threads will be executed before all other threads that are not time critical. (summarize) Specifies that the thread is time critical. (more details...)		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	w U53	y U75	z	aa
M_THREAD_SELECT		Sets the selectable thread, specified by the ThreadEventOrMutexId parameter, as the destination for subsequent MIL functions. This allows MIL functions to be executed on systems with on-board processors. Before calling MthrControl() with M_THREAD_SELECT you should inquire and save the identifier of the on-board thread that is by default associated with the Host thread, using MsysInquire() with M_CURRENT_THREAD_ID. This allows you to return control to this on-board thread. If the ThreadEventOrMutexId parameter is set to an identifier of a thread that is not selectable, changing the settings of this control will generate an error. (summarize) Sets the selectable thread, specified by the ThreadEventOrMutexId parameter, as the destination for subsequent MIL functions. (more details...)		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	w U53	y U75	z	aa
	M_DEFAULT	Implements the default behavior.		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	w U53	y U75	z	aa

The following ControlType and corresponding ControlValue setting can be specified to control MIL events:

For controlling MIL events
ControlType		Description
	ControlValue	Description
M_EVENT_SET		Sets an event to the specified state. INQ (summarize) Sets an event to the specified state. INQ (more details...)
	M_NOT_SIGNALED	Sets the event to the not-signaled state.
	M_SIGNALED	Sets the event to the signaled state.

The following ControlType and corresponding ControlValue setting can be specified to control a MIL mutex:

For controlling a MIL mutex
ControlType		Description
	ControlValue	Description
M_LOCK		Forces the current thread to wait until the specified MIL mutex is available and then locks it. Locking the mutex blocks all other threads from accessing the current critical section of code. Note that the current thread can lock the same mutex several times without an error occurring. However, the current thread must unlock (M_UNLOCK) the mutex as many times as it was locked. For example, if the current thread previously locked the mutex twice, the mutex must be unlocked twice after the critical section of code has completed. (summarize) Forces the current thread to wait until the specified MIL mutex is available and then locks it. (more details...)
	M_DEFAULT	Specifies the default behavior.
M_LOCK_TRY		Locks the specified MIL mutex if it is currently unlocked. Locking the mutex blocks all other threads from accessing the current critical section of code. If the mutex is locked by another thread, M_LOCK_TRY does not force the thread to wait for the mutex to become unlocked; the thread continues executing without executing the critical section of code protected by the mutex. To determine whether the current thread has successfully locked the mutex, use MthrInquire() with M_LOCK_TRY. (summarize) Locks the specified MIL mutex if it is currently unlocked. (more details...)
	M_DEFAULT	Implements the default behavior.
M_UNLOCK		Unlocks the specified mutex. (summarize) Unlocks the specified mutex. (more details...)
	M_DEFAULT	Implements the default behavior.

Type-specific versions of the function when using a C compiler under 64-bit

void MthrControlDouble (MIL_ID ThreadEventOrMutexId, MIL_INT64 ControlType, MIL_DOUBLE ControlValue)

Details

Parameters

ThreadEventOrMutexId

See ThreadEventOrMutexId of the main function for a description.

ControlType

See ControlType of the main function for a description.

ControlValue

See ControlValue of the main function for a description.

void MthrControlInt64 (MIL_ID ThreadEventOrMutexId, MIL_INT64 ControlType, MIL_INT64 ControlValue)

Details

Parameters

ThreadEventOrMutexId

See ThreadEventOrMutexId of the main function for a description.

ControlType

See ControlType of the main function for a description.

ControlValue

See ControlValue of the main function for a description.

Compilation information

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