home *** CD-ROM | disk | FTP | other *** search
/ C/C++ User's Journal & Wi…eveloper's Journal Tools / C-C__Users_Journal_and_Windows_Developers_Journal_Tools_1997.iso / sysembed / timer.edh < prev    next >
Encoding:
Text File  |  1995-03-30  |  6.6 KB  |  194 lines
  1. [ 8. Software Timers]
  2.                      EMBEDDED DOS TIMER SERVICES
  3. ════════════════════════════════════════════════════════════════════════
  4. The timer object implements an extremely fast, centralized, method for
  5. scheduling a source of interrupt-time execution at a specific interval
  6. of time in the future.
  7.  
  8. The timer object was designed to be extremely lightweight, especially
  9. acts of starting and stopping them, so that it could be used to time
  10. very high-speed events, such as packet retransmission timeouts in LAN
  11. transports.  The design assumes that the creation of a timer can be a
  12. heavy event that is not performance critical.  Because expiration timers
  13. almost never fire compared to the number of times that they are started
  14. and stopped, the starting and stopping of timers is made extremely fast.
  15.  
  16. When a timer expiration routine executes, it must not block, because the
  17. expiration routine is executed at interrupt time, not task time.  If it
  18. is desired to block in response to a timer expiration, task-time source
  19. of control can be gained by calling AllocateThread to create a parallel
  20. task-time environment, and then simply returning.
  21.  
  22. 1.  AllocateTimer
  23.  
  24. A timer object is created with the AllocateTimer kernel function.
  25. Once the timer is allocated, it is automatically maintained by
  26. the kernel in response to service requests.
  27.  
  28. At allocation time, the caller specifies a pointer to a function
  29. to be executed when and if the timer does expire.  Additionally,
  30. a context value is specified by the caller that the kernel will
  31. pass to the expiration routine in the (BX) general register.  In
  32. the portable request form, the interface automatically passes the
  33. context as a USHORT argument on the stack.
  34.  
  35. This function returns a handle to a timer object that must be
  36. used by the caller in subsequent kernel services that operate on
  37. timers.  The kernel initializes the timer object to contain the
  38. context value and the pointer to the expiration function, so that
  39. these values need not be specified on every start/stop request.
  40.  
  41. Upon return, the macro instruction call clears the carry flag if
  42. the operation was successful, and sets it if the operation was
  43. not performed.
  44.  
  45. Assembly Language Format:
  46.  
  47.      mov  ax, <Context> ; (AX) = context supplied to exp rtn.
  48.      mov  bx, CGROUP
  49.      mov  cx, OFFSET CGROUP:ExpirationRtn ; (CX:BX) = routine.
  50.      mov  dl, SYS_ALLOCATE_TIMER
  51.      int  2dh           ; (AX) = handle to timer.
  52.      jc   Failure
  53.  
  54. Macro Instruction Format:
  55.  
  56. label     AllocateTimer  <TimerHandle>, <Context>, <ExpirationRtn>
  57.  
  58. Portable Request Format:
  59.  
  60. STATUS AllocateTimer(
  61.      OUT PHANDLE TimerHandle,
  62.      IN USHORT Context,
  63.      IN (*ExpirationRtn)(USHORT)
  64.      );
  65.  
  66. Parameters:
  67.  
  68.      TimerHandle - Specifies a 16-bit general purpose register or
  69.           a pointer to a word in memory where the kernel will
  70.           return a handle to the allocated timer.
  71.  
  72.      Context - Specifies a 16-bit general purpose register or a
  73.           word in memory containing a value to be passed to the
  74.           expiration routine when and if the timer expires.
  75.  
  76.      ExpirationRtn - Specifies a far address of a function to be
  77.           executed when the timer expires.  For the macro format
  78.           only, the 16-bit offset is assumed to be relative to
  79.           the current CS segment register.  The portable form of
  80.           the request passes a far code pointer in the format
  81.           generated by the high level language.
  82.  
  83. 2.  DeallocateTimer
  84.  
  85. A timer object is destroyed with the DeallocateTimer kernel
  86. function.  Once the timer is deallocated, it is no longer
  87. available to the caller, and the handle becomes invalid.
  88.  
  89. If a timer object is deallocated when it is still running, then
  90. the timer is stopped automatically by the kernel before
  91. destroying it.
  92.  
  93. Upon return, the macro instruction call clears the carry flag if
  94. the operation was successful, and sets it if the operation was
  95. not performed.
  96.  
  97. Assembly Language Format:
  98.  
  99.      mov  ax, <TimerHandle>        ; (AX) = handle to timer.
  100.      mov  dl, SYS_DEALLOCATE_TIMER
  101.      int  2dh
  102.      jc   Failure
  103.  
  104. Macro Instruction Format:
  105.  
  106. label     DeallocateTimer     <TimerHandle>
  107.  
  108. Portable Request Format:
  109.  
  110. STATUS DeallocateTimer(
  111.      IN HANDLE TimerHandle
  112.      );
  113.  
  114. Parameters:
  115.  
  116.      TimerHandle - Specifies a 16-bit general purpose register or
  117.           a word in memory containing a handle to the timer to be
  118.           deallocated.
  119.  
  120. 3.  StartTimer
  121.  
  122. A timer object is set to the running state with the StartTimer
  123. kernel function.  If a timer is already in the running state,
  124. then it remains in the running state, and only the expiration
  125. time is changed.  If a timer is in the stopped state, then it is
  126. moved to the running state, and the expiration time is set to the
  127. current time plus the specified number of milliseconds in
  128. DeltaTime.
  129.  
  130. Upon return, the macro instruction call clears the carry flag if
  131. the operation was successful, and sets it if the operation was
  132. not performed.
  133.  
  134. Assembly Language Format:
  135.  
  136.      mov  ax, <TimerHandle>     ; (AX) = handle to timer.
  137.      mov  cx, <DeltaTime>       ; (CX) = interval in milliseconds.
  138.      int  2dh                   ; start the timer.
  139.      jc   Failure
  140.  
  141. Macro Instruction Format:
  142.  
  143. label     StartTimer     <TimerHandle>, <DeltaTime>
  144.  
  145. Portable Request Format:
  146.  
  147. STATUS StartTimer(
  148.      IN HANDLE TimerHandle,
  149.      IN USHORT DeltaTime
  150.      );
  151.  
  152. Parameters:
  153.  
  154.      TimerHandle - Specifies a 16-bit general purpose register or
  155.           a word in memory containing a handle to the timer to be
  156.           started.
  157.  
  158.      DeltaTime - Specifies a 16-bit general purpose register or a
  159.           word in memory containing the number of milliseconds to
  160.           defer execution of the expiration routine.
  161.  
  162. 4.  StopTimer
  163.  
  164. A timer object is set to the stopped state with the StopTimer
  165. kernel function.  If a timer is already in the running state,
  166. then its state is changed to stopped.  If a timer is in the
  167. stopped state, then no operation is performed.
  168.  
  169. Upon return, the macro instruction call clears the carry flag if
  170. the operation was successful, and sets it if the operation was
  171. not performed.
  172.  
  173. Assembly Language Format:
  174.  
  175.      mov  ax, <TimerHandle>        ; (AX) = handle to timer.
  176.      mov  dl, SYS_STOP_TIMER
  177.      int  2dh
  178.      jc   Failure
  179.  
  180. Macro Instruction Format:
  181.  
  182. label     StopTimer <TimerHandle>
  183.  
  184. Portable Request Format:
  185.  
  186. STATUS StopTimer(
  187.      IN HANDLE TimerHandle
  188.      );
  189.  
  190. Parameters:
  191.  
  192.      TimerHandle - Specifies a 16-bit general purpose register or
  193.           a word in memory containing a handle to the timer to be
  194.           stopped.