| MIL 10 Reference
| Customize Help
| Save Settings

MthrAlloc


See also
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
Available on Matrox Supersight
function map Function map
Examples
Previous
MthrControl
Synopsis
Allocate a MIL thread context, event, or mutex.
Syntax
MIL_ID MthrAlloc(
MIL_ID SystemId, //in
MIL_INT64 ObjectType, //in
MIL_INT64 ControlFlag, //in
MIL_THREAD_FUNCTION_PTR ThreadFctPtr, //in
void *UserDataPtr, //in
MIL_ID *ThreadEventOrMutexIdPtr //out
)
Description

This function allocates a MIL thread context, event, or mutex.

Threads are function streams, used to ensure sequential execution of operations within the same thread, while allowing simultaneous yet independent execution of operations in other threads. MthrAlloc() can allocate threads using two different methods:

  • With the first method (M_THREAD), MthrAlloc() creates a MIL thread context for the new thread, and allows you to specify a pointer to a function that will be executed by the thread. When a thread contains a function call whose target processor is an on-board processor that supports multi-threading, MIL automatically creates a corresponding thread on that system's on-board processor. The functions of the Thread module allow you to synchronize threads running on the Host and/or various MIL systems.

  • With the second method, MthrAlloc() creates a selectable thread (M_SELECTABLE_THREAD). Selectable threads are threads executed on an on-board processor that supports multi-threading but can be controlled from a single corresponding thread on the Host. Use MthrControl() with M_THREAD_SELECT to send MIL functions to be executed by a selectable thread.

For more information on these two types of threads, see the Multi-threading section of Chapter 30: Multi-processing, multi-core, and multi-threading.

A MIL event is a synchronization marker that can signal the completion of a required set of functions in one thread to other threads. MthrAlloc() can allocate MIL events, or map a new MIL event to an existing MIL event.

A mutex is a mutual exclusion object that allows threads to synchronize access to shared resources. Once a mutex is allocated on the specified system, you can lock and unlock critical sections of code. Locking a critical section of code ensures that no two threads can access the same data at the same time. To lock a MIL mutex, you must call MthrControl() with M_LOCK or M_LOCK_TRY immediately preceding the section of code to lock. If you lock a mutex, you must unlock it at the end of the critical section of code using MthrControl() with M_UNLOCK. Once you are finished using the mutex object, free it using MthrFree().

To control or inquire about a MIL thread context, event, or mutex, use the MthrControl() or MthrInquire() function, respectively. To synchronize the execution of threads, use MthrWait().

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
SystemId

Specifies the identifier of the system on which to allocate a MIL thread context, event, or mutex.

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

function map For specifying the system
CollapseValue Description
Collapse MIL system identifier

Specifies the MIL identifier of the required system, previously allocated using MsysAlloc().
ObjectType

Specifies the type of object to allocate. This parameter should be set to one of the following values:

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

ControlFlag

Specifies the initialization state of the MIL thread context, event, mutex, or the identifier of an existing MIL event. This parameter should be set to one of the following values:

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

ThreadFctPtr

Specifies the address of the function that will be executed by the new thread (M_THREAD). For all other objects, this parameter should be set to M_NULL.

The function must include calls to all functions that you consider as being part of one thread, and be declared as follows:

MIL_UINT32 MFTYPE FunctionToCall(
void *UserDataPtr
)
Parameters
UserDataPtr

Specifies a pointer to user data that is passed to the UserDataPtr parameter of MthrAlloc().

UserDataPtr

Specifies the address of user data necessary to execute the FunctionToCall function of the new thread (M_THREAD). For all other objects, this parameter should be set to M_NULL.

ThreadEventOrMutexIdPtr

Specifies the address of the variable in which to write the MIL identifier of the MIL thread context, event, or mutex. Since the MthrAlloc() function also returns the requested information, you can set this parameter to M_NULL.

Parameter associations

The table below lists possible values for the ObjectType and ControlFlag parameters.

function map For specifying the type of object to allocate and its initiation state
CollapseObjectType Description
ControlFlag
Collapse M_EVENT

Allocates a new MIL synchronization event on the specified system.

(summarize)
Collapse M_NOT_SIGNALED +

Initializes the event as not signaled.


You must specify a combination value from the following table:
(summarize)
Collapse M_SIGNALED +

Initializes the event as signaled.


You must specify a combination value from the following table:
(summarize)
Collapse MIL event identifier

Specifies the identifier of the user-allocated MIL event to which to map the new M_EVENT_CREATE event.
Collapse M_EVENT_CREATE

Creates a new MIL synchronization event on the specified system, which maps to the MIL event specified by the ControlFlag parameter and is in the same state. The created event allows for multiple, individual on-board processors to change and read the state of the same event.

(summarize)
Collapse M_NOT_SIGNALED +

Initializes the event as not signaled.


You must specify a combination value from the following table:
(summarize)
Collapse M_SIGNALED +

Initializes the event as signaled.


You must specify a combination value from the following table:
(summarize)
Collapse MIL event identifier

Specifies the identifier of the user-allocated MIL event to which to map the new M_EVENT_CREATE event.
Collapse M_MUTEX

Allocates a MIL mutex on the specified system.

(summarize)
Collapse M_DEFAULT

Specifies the default initialization state. This is the only setting available for threads and mutexes. For events, M_DEFAULT is the same as M_NOT_SIGNALED + M_AUTO_RESET.

(summarize)
Collapse M_SELECTABLE_THREAD

Allocates a selectable thread on the specified multi-threaded system. This allows you to synchronize the execution of functions on an on-board processor without creating a Host thread.

Use MthrControl() with M_THREAD_SELECT to select the on-board thread to which to send the functions.

(summarize)
Collapse M_DEFAULT

Specifies the default initialization state. This is the only setting available for threads and mutexes. For events, M_DEFAULT is the same as M_NOT_SIGNALED + M_AUTO_RESET.

(summarize)
Collapse M_TRACE_LOG_DISABLE

Specifies to disable the creation of trace logs on this thread by any external program, such as Matrox Profiler or the MILConfig utility Interactive Troubleshooting.

A trace-disabled thread can still log trace information when explicitly enabled with MIL code. To enable a trace log on a trace-disabled thread, use MappControl() with M_TRACE + M_THREAD_CURRENT set to M_LOG_ENABLE. The trace log will generate trace information starting from the point in the code that the function appears. You can disable generating further trace information in this thread with M_LOG_DISABLE. This creates a trace-enabled block of code in this thread, which is otherwise not generating any trace information.

Disabling trace logs with M_TRACE_LOG_DISABLE helps to protect intellectual property because no external program will be able to generate a trace for this application. A trace-enabled block will protect sensitive intellectual property while still examining a specific section of code.

(summarize)
Collapse M_THREAD

Allocates a thread and associates it with a MIL thread context. If the target processor is an on-board processor of a system that supports multi-threading, MIL automatically creates, and eventually terminates, an on-board thread for each thread that sends commands to the board.

(summarize)
Collapse M_DEFAULT

Specifies the default initialization state. This is the only setting available for threads and mutexes. For events, M_DEFAULT is the same as M_NOT_SIGNALED + M_AUTO_RESET.

(summarize)
Collapse M_TRACE_LOG_DISABLE

Specifies to disable the creation of trace logs on this thread by any external program, such as Matrox Profiler or the MILConfig utility Interactive Troubleshooting.

A trace-disabled thread can still log trace information when explicitly enabled with MIL code. To enable a trace log on a trace-disabled thread, use MappControl() with M_TRACE + M_THREAD_CURRENT set to M_LOG_ENABLE. The trace log will generate trace information starting from the point in the code that the function appears. You can disable generating further trace information in this thread with M_LOG_DISABLE. This creates a trace-enabled block of code in this thread, which is otherwise not generating any trace information.

Disabling trace logs with M_TRACE_LOG_DISABLE helps to protect intellectual property because no external program will be able to generate a trace for this application. A trace-enabled block will protect sensitive intellectual property while still examining a specific section of code.

(summarize)
Combination constants for M_NOT_SIGNALED (when ObjectType=M_EVENT and ControlFlag=M_NOT_SIGNALED); M_NOT_SIGNALED (when ObjectType=M_EVENT_CREATE and ControlFlag=M_NOT_SIGNALED); M_SIGNALED (when ObjectType=M_EVENT and ControlFlag=M_SIGNALED); M_SIGNALED (when ObjectType=M_EVENT_CREATE and ControlFlag=M_SIGNALED).

You must add one of the following values to the above-mentioned values to set how the event is reset.

function map For M_EVENTM_SIGNALED or M_EVENTM_NOT_SIGNALED INQ
CollapseCombination value Description
Collapse M_AUTO_RESET

Specifies that the event is reset automatically.

The state of this type of event is automatically reset to M_NOT_SIGNALED upon the return of a call to MthrWait() with M_EVENT_SYNCHRONIZE or M_EVENT_WAIT.

Events that are reset automatically are useful in applications where only one thread waits on a specific event.

(summarize)
Collapse M_MANUAL_RESET

Specifies that the event is reset manually.

The state of this type of event remains unchanged until a call to MthrControl() with M_EVENT_SET is issued.

Events that are reset manually are useful when multiple threads wait on a specific event.

(summarize)
Return value
The returned value is the identifier of the MIL thread, event, or mutex if the allocation is successful. If allocation fails, M_NULL is returned.
Compilation information
Header Include mil.h.
Library Use mil.lib.
DLL Requires mil.dll.
EVENT NOT SIGNALED SIGNALED EVENT CREATE NOT SIGNALED SIGNALED MUTEX DEFAULT SELECTABLE THREAD DEFAULT TRACE LOG DISABLE THREAD DEFAULT TRACE LOG DISABLE AUTO RESET MANUAL RESET