en:docs:fapi:dossleep

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
en:docs:fapi:dossleep [2018/08/26 09:04] – prokusheven:docs:fapi:dossleep [2021/09/17 08:46] (current) – prokushev
Line 1: Line 1:
-{{logos:os2.gif?35x35}} {{logos:dos.gif?35x35}}+{{page>en:templates:fapiint}} 
 ====== DosSleep ====== ====== DosSleep ======
  
 This call suspends the current thread for a specified time. If the requested interval is 0, the call gives up the remainder of the current time slice. This call suspends the current thread for a specified time. If the requested interval is 0, the call gives up the remainder of the current time slice.
  
-==Syntax== +===== Syntax =====
- DosSleep (TimeInterval)+
  
-==Parameters== +<code c> 
-  *TimeInterval (ULONG) - input : Time interval in milliseconds until the thread is awakened.+DosSleep (TimeInterval) 
 +</code> 
 + 
 +===== Parameters ===== 
 + 
 +  *TimeInterval ([[ULONG]]) - input : Time interval in milliseconds until the thread is awakened. 
 + 
 +===== Return Code ===== 
 + 
 +rc ([[USHORT]]) - return
  
-==Return Code== 
- rc (USHORT) - return 
 Return code descriptions are: Return code descriptions are:
 +
   * 0          NO_ERROR    * 0          NO_ERROR 
   * 322        ERROR_TS_WAKEUP    * 322        ERROR_TS_WAKEUP 
  
-==Remarks==+===== Remarks ===== 
 DosSleep suspends the current thread for the specified time period. The actual time it is asleep may be off by a clock tick or two, depending on the execution status of other threads running in the system. DosSleep suspends the current thread for the specified time period. The actual time it is asleep may be off by a clock tick or two, depending on the execution status of other threads running in the system.
  
Line 27: Line 36:
 For short time intervals, the rounding-up process combined with the thread priority interactions may cause a sleeping interval to be longer than requested. Also, when a process completes sleeping, it is scheduled for execution. But that execution could be delayed by hardware interrupts or by another thread running at a higher priority. A program should not use the DosSleep call as a substitute for a real-time clock because rounding of the sleep interval causes cumulative errors. For short time intervals, the rounding-up process combined with the thread priority interactions may cause a sleeping interval to be longer than requested. Also, when a process completes sleeping, it is scheduled for execution. But that execution could be delayed by hardware interrupts or by another thread running at a higher priority. A program should not use the DosSleep call as a substitute for a real-time clock because rounding of the sleep interval causes cumulative errors.
  
-Asynchronous timers can be started with DosTimerAsync and DosTimerStart. DosTimerAsync starts a one-shot asynchronous timer, and DosTimerStart starts a periodic interval timer. DosTimerStop is issued to stop these timers.+Asynchronous timers can be started with [[DosTimerAsync]] and [[DosTimerStart]]. [[DosTimerAsync]] starts a one-shot asynchronous timer, and [[DosTimerStart]] starts a periodic interval timer. [[DosTimerStop]] is issued to stop these timers.
  
-Note: To ensure optimum performance, you should not use DosSleep in a single-thread Presentation Manager application. See WinStartTimer.+Note: To ensure optimum performance, you should not use DosSleep in a single-thread Presentation Manager application. See [[WinStartTimer]].
  
- +==== Family API Considerations ====
-===Family API Considerations===+
  
 Some options operate differently in the DOS mode than in OS/2 mode. Therefore, the following restrictions apply to DosSleep when coding in DOS mode: Some options operate differently in the DOS mode than in OS/2 mode. Therefore, the following restrictions apply to DosSleep when coding in DOS mode:
Line 40: Line 48:
  
  
-==Example Code== +==== Example Code ==== 
-===C Binding===+ 
 +=== C Binding === 
 +<code c>
  
   #define INCL_DOSPROCESS   #define INCL_DOSPROCESS
Line 50: Line 60:
      
   USHORT           rc;            /* return code */   USHORT           rc;            /* return code */
 +</code>
  
-The following example illustrates how to obtain the priority of a thread and how to change the priority. The main thread creates Thread2 and allows it to begin executing. Thread2 iterates through a loop that prints a line and then sleeps, relinquishing its time slice to the main thread. After one or two iterations by Thread2, the main thread obtains Thread2's priority information and prints it. It then raises Thread2's priority to fixed-high, and increments the level by ten. Since Thread2 is now at a high priority, it immediately finishes its remaining iterations before relinquishing control on a long sleep; at this point, the main thread re-examines Thread2's priority and reports its new priority level. In this example, it is helpful to understand how the DosSleep calls are used either to relinquish control of the processor, or to keep a thread alive (see DosTimerAsync or DosTimerStart for alternatives to DosSleep).  +The following example illustrates how to obtain the priority of a thread and how to change the priority. The main thread creates Thread2 and allows it to begin executing. Thread2 iterates through a loop that prints a line and then sleeps, relinquishing its time slice to the main thread. After one or two iterations by Thread2, the main thread obtains Thread2's priority information and prints it. It then raises Thread2's priority to fixed-high, and increments the level by ten. Since Thread2 is now at a high priority, it immediately finishes its remaining iterations before relinquishing control on a long sleep; at this point, the main thread re-examines Thread2's priority and reports its new priority level. In this example, it is helpful to understand how the DosSleep calls are used either to relinquish control of the processor, or to keep a thread alive (see [[DosTimerAsync]] or [[DosTimerStart]] for alternatives to DosSleep). 
  
 +<code c>
   #define INCL_DOSPROCESS   #define INCL_DOSPROCESS
      
Line 143: Line 154:
     }     }
   }   }
 +</code>
  
 +=== MASM Binding ===
  
-===MASM Binding=== +<code asm>
   EXTRN  DosSleep:FAR   EXTRN  DosSleep:FAR
   INCL_DOSPROCESS     EQU 1   INCL_DOSPROCESS     EQU 1
Line 152: Line 164:
   PUSH   DWORD   TimeInterval  ;Interval size (in milliseconds)   PUSH   DWORD   TimeInterval  ;Interval size (in milliseconds)
   CALL   DosSleep   CALL   DosSleep
 +</code>
  
 Returns WORD Returns WORD
  
- +==== Note ====
-====== Note ======+
  
 This text based on [[http://www.edm2.com/index.php/DosSleep_(FAPI)]] This text based on [[http://www.edm2.com/index.php/DosSleep_(FAPI)]]