iwin32 Design

API mixing
iwin32x functions
Priorities

API mixing

The two APIs each implement a separate set of object types. Although it should be perfectly feasible to code a thread exclusively with one of the two APIs, there may be different threads in the system at the same time, that use different APIs. What happens if such threads need to communicate?

We have to define the terms "pure INtime thread" and "iwin32 thread": a pure INtime thread is a thread created by the INtime function CreateRtThread; an iwin32 thread is either the main thread of a process linked with the iwin32.lib library or a thread created by one of the iwin32 functions: CreateThread, RtCreateThread, RtCreateTimer, RtAttachInterruptVector, RtAttachInterruptVectorEx, RtAttachShutdownHandler.

An iwin32 thread can use the complete iwin32 API. It can also use the INtime API without limitations; that means it can create INtime objects, lookup handles, catalog handles, send and receive units and messages and perform various wait operations.
A pure INtime thread can use only a small subset of the iwin32 API; it cannot create iwin32 objects and can not wait for iwin32 objects. The function definition will indicate whether a particular function can be used in a pure INtime thread.

iwin32x functions

For the communication between processes in the Windows environment and iwin32 processes in INtime, a set of functions is available named 'iwin32x'. These functions can only be used from C or C++ programs. The API provides a subset of the iwin32 API (for obvious reasons, a number of iwin32 functions is not available here) and also includes specific functions, for example to find an INtime node.

The iwin32x functions include:

Event handling	RtCreateEvent RtOpenEvent RtPulseEvent RtResetEvent RtSetEvent
Mutexes	RtCreateMutex RtOpenMutex RtReleaseMutex
Process handling	RtCreateProcess RtGetExitCodeProcess RtOpenProcess RtTerminateProcess
Semaphores	RtCreateSemaphore RtOpenSemaphore RtReleaseSemaphore
Shared memory	RtCreateSharedMemory RtOpenSharedMemory
General purpose	RtCloseHandle RtImportHandle RtSetNode RtWaitForSingleObject

Priorities

INtime supports three thread priority ranges. Internally the INtime range is always used: from 0 to 254, zero being the most important. Priorities between 0 and 127 influence interrupt enabling.

Iwin32 (functions such as GetThreadPriority, SetThreadPriority) has a priority range from -15 to +15, the numerically highest value is the best. These values are mapped to the INtime priorities as follows:

Note: These priorities are used when the function exists in Win32 and does not have an Rt prefix.

Note: THREAD_PRIORITY_TIME_CRITICAL, which corresponds to priority 0 in INtime, also blocks the scheduler and interrupts. Care should be taken on usage.

Iwin32 priority	INtime priority	Win32 priority name
-15 -14 -13 -12 -11 -10 -9 -8 -7 -6 -5 -4 -3 -2 -1 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15	254 246 238 230 222 214 206 198 190 182 174 166 158 150 142 134 126 117 108 99 90 81 72 63 54 45 36 27 18 9 0	THREAD_PRIORITY_IDLE THREAD_PRIORITY_ LOWEST THREAD_PRIORITY_ BELOW_NORMAL THREAD_PRIORITY_ NORMAL THREAD_PRIORITY_ ABOVE_NORMAL THREAD_PRIORITY_ HIGHEST THREAD_PRIORITY_ TIME_CRITICAL

iwin32 does not support priority classes.

RTX-compatible thread priorities (RtSetThreadPriority, RtAtttachInterruptVector etc) range from 0 to 127, with 127 being the best priority.

An RTX-compatible priority is translated into an INtime priority as follows:

prio(INtime) = 254 - 2*prio(RTX)

Note that the lowest Win prio now translates in INtime prio 254, which means time sharing with Windows in shared mode.