Synopsis
Allocate/control MIL application thread(s) or events.
Format
long MappControlThread(ControlId, ControlType, ControlValue, RetVarPtr)
| MIL_ID ControlId | Thread or Event identifier |
| long ControlType; | Type of control set on thread or event |
| long ControlValue | Value of control setting |
| long *RetVarPtr; | Storage location for returned value |
Description
This function allocates/controls MIL application threads or events.
A MIL thread is a command stream used to send MIL commands to the various allocated MIL systems. MIL automatically allocates a MIL thread for each existing HOST thread that is using MIL. MappControlThread?allows you to synchronize MIL threads running on the Host and/or various MIL systems.
A MIL event is a marker that can be inserted between commands sent to a given thread. Its state can be set to either M_SIGNALED or M_NOT_SIGNALED in a given thread and can be inquired about or waited for (MappControlThread(Event, M_EVENT_WAIT, …)), until in M_SIGNALED state, by other threads in order to monitor the execution of commands.
The event can be one of the following reset types:
| Auto-Reset: | Calling MappControlThread(Event, M_EVENT_SET, …), sets or resets the event state to M_SIGNALED or M_NOT_SIGNALED. When in M_SIGNALED state, the event is automatically reset to M_NOT_SIGNALED when a call to MappControlThread(Event, M_EVENT_WAIT, M_DEFAULT, …) returns. This type of event is useful in applications where only one thread waits on a specific event. |
| Manual-Reset: | Calling MappControlThread(Event, M_EVENT_SET, …), sets or resets the event state to M_SIGNALED or M_NOT_SIGNALED. The event state remains unchanged until an explicit call to MappControlThread(Event, M_EVENT_SET, …) is issued. This type of event is useful when multiple threads wait on a specific event. |
The ControlId parameter specifies the identifier of the thread or event to be controlled. If set to M_DEFAULT, it uses the default MIL thread/event identifier associated with the Host thread. The thread or event can be user-allocated using the M_THREAD_ALLOC or M_EVENT_ALLOC ControlType of MappControlThread.
The ControlType and ControlValue parameters specify the thread or event control operation to be performed. These parameters can be set to the following combinations:
| Thread ControlType |
ControlValue |
Result |
| M_THREAD_ALLOC | M_DEFAULT | Create a new selectable MIL thread on a multi-thread system (such as Genesis) and return its MIL_ID. Mainly useful under DOS. Under Windows NT/95, MIL automatically allocates a default MIL thread for each existing Host thread. Note, ControlId must be set to M_DEFAULT. |
| M_THREAD_FREE | M_DEFAULT | Free an existing MIL thread. Note that default MIL threads will be automatically freed. * |
| M_THREAD_SELECT | M_DEFAULT | Select the MIL thread to which subsequent MIL commands will be sent. Mainly useful under DOS.* |
| M_THREAD_WAIT | M_DEFAULT | Synchronize commands sent to a thread. Force a wait for completion of all commands currently executing in the thread. Useful for commands sent to systems allowing an immediate return (before execution is actually completed).* |
| M_THREAD_MODE | M_SYNCHRONOUS | MIL commands sent to the thread are completed (execution terminated) before returning.* |
| M_ASYNCHRONOUS | MIL commands sent to the thread return immediately (when the the system and command allow an immediate return). (default) * | |
| M_THREAD_IO_MODE | M_SYNCHRONOUS | MIL commands MbufGet…() (MbufGet, MbufGetColor, MbufGetLine, MbufGet1d, MbufGet2d) and MbufPut…() (MbufPut, MbufPutColor, MbufPutLine, MbufPut1d, MbufPut2d) sent to the thread wait, before executing, for the completion of previous MIL commands sent in the thread (default).* |
| M_ASYNCHRONOUS | MIL commands MbufGet…() (MbufGet, MbufGetColor, MbufGetLine, MbufGet1d, MbufGet2d) and MbufPut…() (MbufPut, MbufPutColor, MbufPutLine, MbufPut1d, MbufPut2d) sent to the thread execute immediately.* |
* No return value is required. ControlVarPtr should be set to M_NULL.
| Event ControlType | ControlValue |
Result |
| M_EVENT_ALLOC | (any of the values listed below) | Create a new MIL synchronization event and return its MIL ID. Note, ControlId must be set to M_DEFAULT. |
| M_DEFAULT or M_NOT_SIGNALED+M_AUTO_RESET | Event is initialized as M_NOT_SIGNALED and as an Auto-Reset type. | |
| M_SIGNALED+M_AUTO_RESET | Event is initialized as M_SIGNALED and and as an Auto-Reset type. | |
| M _NOT_SIGNALED+M_MANUAL_RESET | Event is initialized as M_NOT_SIGNALED and as an Manual-Reset type. | |
| M_SIGNALED+M_MANUAL_RESET | Event is initialized as M_SIGNALED and and as an Manual-Reset type. | |
| M_EVENT_FREE | M_DEFAULT | Free an existing MIL event.* |
| M_EVENT_SET | M_SIGNALED or M_NOT_SIGNALED |
Set a MIL event to the specified state.* |
| M_EVENT_WAIT | M_DEFAULT | Wait for the specified event to be in an M_SIGNALED state. If the event is auto-reset, resets to M_NOT_SIGNALED after the wait call is returned.* |
| M_EVENT_STATE | M_DEFAULT | Inquire the state of the MIL event. The return value can be: M_SIGNALED or M_NOT_SIGNALED. |
No return value is required. ControlVarPtr should be set to M_NULL.
The ControlVarPtr parameter specifies a pointer to the user variable where the return value is to be written. Specify M_NULL if no return value is required (see footnotes of control tables).