DosSleep

From EDM2
Jump to: navigation, search

DosSleep causes the calling thread to be suspended for a given time.

Syntax

rc = DosSleep( ulInterval );
DosSleep(ulInterval
Current thread sleeps for n milliseconds.

Parameters

ulInterval - ULONG - input 
Time in milliseconds. The time that the calling thread will sleep. In milliseconds.


Returns

APIRET with values of:

  • NO_ERROR
  • ERROR_TS_WAKEUP

Define (C/C++)

INCL_DOSPROCESS

Calling conversion

Cdecl32

Sample Code

#define INCL_DOSDATETIME
#include <os2.h>

APIRET rc;

rc=DosSleep(2000); /* Suspend the thread for 2 seconds */

Notes

This function suspends the current thread for the specified time interval. If a time interval of 0 is specified, the thread gives up the remainder of the current time slice, allowing other ready threads of equal or higher priority to execute; the calling thread will execute again during its next scheduled time slice. If there is no other ready thread of equal or higher priority, DosSleep returns immediately; it does not give control to a thread of lower priority.

Time intervals for DosSleep (and DosAsyncTimer and DosStartTimer) are specified in milliseconds; however, it is necessary to recognize that the actual duration of the specified time interval will be affected by two factors:

First - the system clock keeps track of time as clock ticks, which are less precise. The duration of a clock tick depends on the frequency of the system-clock interrupt that is used by your computer. (To determine the duration of the clock tick on your computer, issue DosQuerySysInfo and examine the timer-interval field.)

Because clock ticks are less precise than millisecond values, any time interval that is specified in milliseconds will be rounded up to the next clock tick.

Second - The system is a priority-based, multitasking operating system, there is no guarantee that a thread will resume immediately after the timer interval expires. If a higher-priority process or thread is executing, the timed thread blocks. (To minimize the inaccuracy caused by preemptive scheduling, an application can dedicate a thread to managing time-critical tasks and then raise that thread to a higher priority.)

In addition, the time interval for DosSleep refers to execution time, not to elapsed real time. Elapsed real time will be longer and will vary, depending on the hardware and on the number and priorities of other threads executing in the system. (Elapsed real time for the asynchronous timers, started by DosAsyncTimer and DosStartTimer, will be much closer to their specified time intervals because these timers run independently of the calling thread's execution.)

Because the above factors usually cause the sleep interval to be longer than requested, DosSleep should not be used as a substitute for a real-time clock.

To ensure optimal performance, do not use DosSleep in a single-thread Presentation Manager application. (See WinStartTimer.)

If the calling thread is awakened before the time interval expires (by a system exception, for example), ERROR_TS_WAKEUP is returned.

Gotchas

Calling DosSleep with 0 as the argument will give up the rest of the threads current time-slice. The time to sleep will be rounded up by the system to the next clock tick. Note that this does not seem to work on many systems, so DosSleep(1) is safer.

OS Version Introduced

  • OS/2 1.0

See Also