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 / event.edh < prev    next >
Encoding:
Text File  |  1995-03-30  |  7.6 KB  |  265 lines
  1. [ 6. Event Semaphores]
  2.                      EMBEDDED DOS EVENT SEMAPHORES
  3. ════════════════════════════════════════════════════════════════════════
  4. The event object is the basic mechanism used to control synchronous
  5. dispatching of threads.  An event is assigned a state, and must always
  6. be in either the set or cleared states.
  7.  
  8. Facilities are provided by the kernel to set, clear, and pulse events.
  9. The kernel also provides allocation and deallocation services to make
  10. event objects.  Threads may inspect the state of an event object, and
  11. may wait on an event until the event has reached the set state.
  12.  
  13. 1.  AllocateEvent
  14.  
  15. An event object is created with the AllocateEvent kernel
  16. function.  Once the event is allocated, it is automatically
  17. maintained by the kernel in response to service requests.
  18.  
  19. This function returns a handle to an event object that must be
  20. used by the caller in subsequent kernel services that operate on
  21. events.  The kernel initializes the event object to the cleared
  22. state.
  23.  
  24. Upon return, the macro instruction call clears the carry flag if
  25. the operation was successful, and sets it if the operation was
  26. not performed.
  27.  
  28. Assembly Language Format:
  29.  
  30.      mov  dl, SYS_ALLOCATE_EVENT
  31.      int  2dh                   ; (AX) = event handle.
  32.      jc   Failure
  33.  
  34. Macro Instruction Format:
  35.  
  36. label     AllocateEvent  <EventHandle>
  37.  
  38. Portable Request Format:
  39.  
  40. STATUS AllocateEvent(
  41.      OUT PHANDLE EventHandle
  42.      );
  43.  
  44. Parameters:
  45.  
  46.      EventHandle - Specifies a 16-bit general purpose register or
  47.           a pointer to a word in memory where the kernel will
  48.           return a handle to the allocated event.
  49.  
  50. 2.  DeallocateEvent
  51.  
  52. An event object is destroyed with the DeallocateEvent kernel
  53. function.  Once the event is deallocated, its corresponding
  54. handle becomes invalid and may no longer be used.
  55.  
  56. This function returns allocated resources to the system so that
  57. they may be recycled.  If any threads are blocked on the event
  58. object, then they are automatically destroyed by the kernel.
  59.  
  60. Upon return, the macro instruction call clears the carry flag if
  61. the operation was successful, and sets it if the operation was
  62. not performed.
  63.  
  64. Assembly Language Format:
  65.  
  66.      mov  ax, <EventHandle>     ; (AX) = handle to event.
  67.      mov  dl, SYS_DEALLOCATE_EVENT
  68.      int  2dh
  69.      jc   Failure
  70.  
  71. Macro Instruction Format:
  72.  
  73. label     DeallocateEvent     <EventHandle>
  74.  
  75. Portable Request Format:
  76.  
  77. STATUS DeallocateEvent(
  78.      IN HANDLE EventHandle
  79.      );
  80.  
  81. Parameters:
  82.  
  83.      EventHandle - Specifies a 16-bit general purpose register or
  84.           word in memory containing a handle to an event to be
  85.           deallocated.
  86.  
  87. 3.  SetEvent
  88.  
  89. An event object may be transfered to the set state by calling the
  90. SetEvent kernel function.  Setting an event will cause all threads
  91. blocking on the event object to be rescheduled by the kernel.
  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, <EventHandle>     ; (AX) = handle to event.
  100.      mov  dl, SYS_SET_EVENT
  101.      int  2dh
  102.      jc   Failure
  103.  
  104. Macro Instruction Format:
  105.  
  106. label     SetEvent  <EventHandle>
  107.  
  108. Portable Request Format:
  109.  
  110. STATUS SetEvent(
  111.      IN HANDLE EventHandle
  112.      );
  113.  
  114. Parameters:
  115.  
  116.      EventHandle - Specifies a 16-bit general purpose register or
  117.           word in memory containing a handle to an event to be set.
  118.  
  119. 4.  ClearEvent
  120.  
  121. An event object may be transfered to the cleared state by calling
  122. the ClearEvent kernel function.  Clearing an event will not
  123. affect the status of thread blocking on the event object.
  124.  
  125. Upon return, the macro instruction call clears the carry flag if
  126. the operation was successful, and sets it if the operation was
  127. not performed.
  128.  
  129. Assembly Language Format:
  130.  
  131.      mov  ax, <EventHandle>             ; (AX) = handle to event.
  132.      mov  dl, SYS_CLEAR_EVENT
  133.      int  2dh
  134.      jc   Failure
  135.  
  136. Macro Instruction Format:
  137.  
  138. label     ClearEvent     <EventHandle>
  139.  
  140. Portable Request Format:
  141.  
  142. STATUS ClearEvent(
  143.      IN HANDLE EventHandle
  144.      );
  145.  
  146. Parameters:
  147.  
  148.      EventHandle - Specifies a 16-bit general purpose register or
  149.           word in memory containing a handle to an event to be
  150.           cleared.
  151.  
  152. 5.  PulseEvent
  153.  
  154. An event object may be momentarily transfered to the set state by
  155. calling the PulseEvent kernel function.  Pulsing an event will
  156. cause all threads blocking on the event object to be rescheduled
  157. by the kernel, but the event's status is not changed.
  158.  
  159. Upon return, the macro instruction call clears the carry flag if
  160. the operation was successful, and sets it if the operation was
  161. not performed.
  162.  
  163. Assembly Language Format:
  164.  
  165.      mov  ax, <EventHandle>     ; (AX) = handle to event.
  166.      mov  dl, SYS_PULSE_EVENT
  167.      int  2dh
  168.      jc   Failure
  169.  
  170. Macro Instruction Format:
  171.  
  172. label     PulseEvent     <EventHandle>
  173.  
  174. Portable Request Format:
  175.  
  176. STATUS PulseEvent(
  177.      IN HANDLE EventHandle
  178.      );
  179.  
  180. Parameters:
  181.  
  182.      EventHandle - Specifies a 16-bit general purpose register or
  183.           word in memory containing a handle to an event to be
  184.           pulsed.
  185.  
  186. 6.  QueryEvent
  187.  
  188. The state of an event object may be inspected by calling the
  189. QueryEvent kernel function.  The function returns the value TRUE
  190. if the event was set at the time of the call, and FALSE
  191. otherwise.
  192.  
  193. Upon return, the macro instruction call clears the carry flag if
  194. the operation was successful, and sets it if the operation was
  195. not performed.
  196.  
  197. Assembly Language Format:
  198.  
  199.      mov  ax, <EventHandle>        ; (AX) = handle to event.
  200.      mov  dl, SYS_QUERY_EVENT
  201.      int  2dh                 ; (AX) = 0 if clear, non-zero if set.
  202.      jc   Failure
  203.  
  204. Macro Instruction Format:
  205.  
  206. label     QueryEvent     <EventHandle>, <EventStatus>
  207.  
  208. Portable Request Format:
  209.  
  210. STATUS QueryEvent(
  211.      IN HANDLE EventHandle,
  212.      OUT PUSHORT EventStatus
  213.      );
  214.  
  215. Parameters:
  216.  
  217.      EventHandle - Specifies a 16-bit general purpose register or
  218.           word in memory containing a handle to an event to be
  219.           queried.
  220.  
  221.      EventStatus - Specifies a 16-bit general purpose register or
  222.           address of a word in memory where the kernel will
  223.           return the status of the event.
  224.  
  225. 7.  WaitEvent
  226.  
  227. A thread may wait for an event to reach the set state by calling
  228. the WaitEvent kernel function.  If the event is already in the
  229. set state at the time the request is issued, the thread will
  230. continue execution without waiting.  If the event is in the
  231. cleared state at the time the request is issued, the thread will
  232. block until the event is pulsed or set, at which time the thread
  233. will resume execution.
  234.  
  235. If a thread is blocked on an event, the kernel immediately
  236. selects another thread in the system for execution.  If no
  237. threads are available for execution, then the scheduler executes
  238. an idle loop waiting for a thread to be allocated or unblocked.
  239.  
  240. Upon return, the macro instruction call clears the carry flag if
  241. the operation was successful, and sets it if the operation was
  242. not performed.
  243.  
  244. Assembly Language Format:
  245.  
  246.      mov  ax, <EventHandle>     ; (AX) = handle to event.
  247.      mov  dl, SYS_WAIT_EVENT
  248.      int  2dh                   ; wait for pulse or set status.
  249.      jc   Failure
  250.  
  251. Macro Instruction Format:
  252.  
  253. label     WaitEvent <EventHandle>
  254.  
  255. Portable Request Format:
  256.  
  257. STATUS WaitEvent(
  258.      IN HANDLE EventHandle
  259.      );
  260.  
  261. Parameters:
  262.  
  263.      EventHandle - Specifies a 16-bit general purpose register or
  264.           word in memory containing a handle to an event to be
  265.           blocked on.