TimerSleep
The TimerSleep function blocks the execution of the calling thread for a specified duration in milliseconds. This routine leverages the independent High-Resolution Timer (HRT) subsystem to provide high-precision delays tailored for time-critical loops.
Syntax
#include <mididll.h> ULONG ulDuration; /* Sleep duration in milliseconds (Input) */ ULONG ulFlag; /* Reserved flag, must be 0 (Input) */ ULONG rc; /* Return code */ rc = TimerSleep(ulDuration, ulFlag);
Parameters
- ulDuration (ULONG) - input
- The amount of time, in milliseconds, that the calling thread should be placed into a blocked wait state.
- ulFlag (ULONG) - input
- A reserved subsystem tracking modifier flag. This must be explicitly set to `0`.
Return Value
- rc (ULONG) - returns
- Returns `0` (or `TIMER_SUCCESS`) if the suspension period elapsed successfully, or one of the following diagnostic error codes:
- TIMERERR_INVALID_PARAMETER: The context modifier flag ulFlag was not explicitly configured to `0`.
- TIMERERR_INTERNAL_SYSTEM: An unrecoverable exception occurred within the core low-level subsystem or driver layer.
Remarks
- **Clock Source Independence**: TimerSleep relies directly on the system's High-Resolution Timer (HRT). Unlike the specialized virtual clock returned by MIDISetup, the HRT runs monotonically and is completely detached from external incoming synchronization lines (such as SMPTE timecode or OS/2 Multimedia Presentation Manager transport events).
- **Execution Priority Requirements**: This function is strictly engineered to be executed from within a thread assigned to the **Time-Critical** priority class. Calling this function from a normal or idle priority thread may result in scheduling drift or irregular delays because the OS/2 scheduler will prioritize higher-priority application contexts. Developers can elevate thread scheduling privileges using the native control program API `DosSetPriority`.
Example Code
The following example demonstrates how to establish a high-precision, periodic execution loop that invokes a worker routine every 4 milliseconds within a time-critical thread context:
#define INCL_DOSPROCESS
#include <os2.h>
#include <mididll.h>
int MyWorkerFunction(void);
APIRET rc; /* OS/2 system return code */
ULONG rc2; /* Subsystem timer return code */
ULONG ulSleepDuration = 4;
int fLoop;
/* Elevate the current thread's scheduling class to Time-Critical */
rc = DosSetPriority(PRTYS_THREAD, PRTYC_TIMECRITICAL, 0, 0);
if (rc == NO_ERROR) {
/* Perform periodic execution loop until the worker function signals a stop */
do {
/* Yield thread execution for exactly 4 milliseconds */
rc2 = TimerSleep(ulSleepDuration, 0);
if (rc2 == TIMER_SUCCESS) {
fLoop = MyWorkerFunction();
} else {
break; /* Terminate the loop if the timer subsystem fails */
}
} while (fLoop);
}