home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / threads.zip / ievntsem.hpp < prev    next >
Text File  |  1995-10-09  |  8KB  |  148 lines
  1. /* NOSHIP */
  2. #ifndef _IEVNTSEM_
  3. #define _IEVNTSEM_
  4. /*******************************************************************************
  5. * FILE NAME: IEVNTSEM.HPP
  6. *
  7. * DESCRIPTION:
  8. *   Declaration of the class(es):
  9. *     IEventSem - Provides a signaling mechanism among threads or processes.
  10. *
  11. * COPYRIGHT:
  12. *   Licensed Materials - Property of IBM
  13. *   (C) Copyright IBM Corporation 1995
  14. *   All Rights Reserved
  15. *   US Government Users Restricted Rights - Use, duplication, or disclosure
  16. *   restricted by GSA ADP Schedule Contract with IBM Corp.
  17. *
  18. *******************************************************************************/
  19. #ifndef _IBASE_
  20.   #include <ibase.hpp>
  21. #endif
  22.  
  23. // Forward declarations for other classes:
  24. class IString;
  25. class ISemaphoreHandle;
  26.  
  27. // Align classes on four byte boundary.
  28. #pragma pack(4)
  29.  
  30. class IEventSem : public IBase {
  31. /*******************************************************************************
  32. * The IEventSem class provides a signaling mechanism among threads or          *
  33. * processes.  An IEventSem instance is used by one thread to signal other      *
  34. * threads that an event has occurred.  An application can use objects of       *
  35. * this class to block a thread or process until the event has occurred.        *
  36. *                                                                              *
  37. * An IEventSem object has two states, reset and posted.  When an IEventSem     *
  38. * object is in the reset state, the operating system blocks any thread or      *
  39. * process that is waiting on this IEventSem object (or any other IEventSem     *
  40. * object with the same semaphore handle).  When an IEventSem object is in the  *
  41. * posted state, all threads or processes waiting on the event semaphore resume *
  42. * execution.                                                                   *
  43. *                                                                              *
  44. *******************************************************************************/
  45. public:
  46.  
  47. /*------------------------------- Enumerators ----------------------------------
  48. | Two enumerations are defined.                                                |
  49. |   SemOperation  - enumerator to distinguish between a global semaphore       |
  50. |                   that is being opened verses one that is being created.     |
  51. |                   createSem - create the event semaphore.                    |
  52. |                   openSem   - open the event semaphore.  The semaphore       |
  53. |                               must already exists.                           |
  54. |                                                                              |
  55. |   EventSemType  - enumerator to determine the type of semaphore              |
  56. |                   managed by this object:                                    |
  57. |                   created   - a global semaphore created by this IEventSem   |
  58. |                               object.                                        |
  59. |                   opened    - a global semaphore opened by this IEventSem    |
  60. |                               object.                                        |
  61. |                   localRam  - a private semaphore.                           |
  62. |-----------------------------------------------------------------------------*/
  63.  enum SemOperation { createSem, openSem };
  64.  enum EventSemType { created, opened, localRam };
  65.  
  66.  
  67. /*------------------------------- Constructors ---------------------------------
  68. | You can construct an object of this class in the following ways:             |
  69. |   -  Construct a private, unnamed event semaphore.                           |
  70. |      The initial state of the semaphore (on a successful                     |
  71. |      return from this constructor) is "reset".                               |
  72. |                                                                              |
  73. |   -  Construct a public, named event semaphore. The SemOperation value       |
  74. |      indicates whether the semaphore is being created or opened.             |
  75. |      For create, the initial state of the semaphore (on a                    |
  76. |      successful return from this constructor) is "reset".                    |
  77. |      The semaphore name is constructed from semName by adding                |
  78. |      the prefix '\SEM32'. For example, semName == 'CS\SIGNAL.SEM'            |
  79. |      would result in an actual semaphore name '\SEM32\CS\SIGNAL.SEM'.        |
  80. |      If the semaphore is being created and the semName argument is an        |
  81. |      empty string, an unnamed event semaphore is constructed.                |
  82. |                                                                              |
  83. |   -  Construct an IEventSem object from a previously created public          |
  84. |      semaphore.  The ISemaphoreHandle augument is used to open the           |
  85. |      semaphore for this process.                                             |
  86. |                                                                              |
  87. | The destructor closes the event semaphore.                                   |
  88. |-----------------------------------------------------------------------------*/
  89.  IEventSem( );                     /* local, unnamed semaphore */
  90.                                    /* global, named semaphore  */
  91.  IEventSem( const IString& semName,
  92.             SemOperation semOp = IEventSem::createSem);
  93.  
  94.  IEventSem( ISemaphoreHandle& handle);  /* global, unnamed semphore open */
  95.  
  96.  ~IEventSem( ) ;
  97.  
  98. /*------------------------- Implementation -------------------------------------
  99. | Use functions in this group to do event signaling and to wait for an         |
  100. | event to be signaled.                                                        |
  101. |                                                                              |
  102. |   post   - Posts the event semaphore, causing all threads that were          |
  103. |            blocked, via IEventSem::wait on this object, to execute.          |
  104. |                                                                              |
  105. |   reset  - Resets the event semaphore, causing all threads that subsequently |
  106. |            call IEventSem::wait for this semaphore object to be blocked.     |
  107. |            The number of post calls since the last reset is returned.        |
  108. |                                                                              |
  109. |   wait   - Enables a thread to wait for this semaphore to be posted.         |
  110. |            The wait times out after the specified timeOut value.  If no      |
  111. |            timeout argument is specified on the wait() call, the timeOut     |
  112. |            value defaults to forever.                                        |
  113. |                                                                              |
  114. |-----------------------------------------------------------------------------*/
  115.  IEventSem & post( );
  116.  unsigned long reset( );
  117.  IEventSem & wait( long timeOut=-1);
  118.  
  119. /*------------------------- Accessors ------------------------------------------
  120. | These functions are used to query the characteristics of an IEventSem        |
  121. | object.                                                                      |
  122. |                                                                              |
  123. |   name      - Returns the name (if any) associated with this semaphore.      |
  124. |   postCount - Returns the current post count for this object.                |
  125. |   type      - Returns the type of semaphore this object represents.          |
  126. |   handle    - Returns the handle that is associated with this semaphore.     |
  127. |                                                                              |
  128. |-----------------------------------------------------------------------------*/
  129.  const IString & name( );
  130.  unsigned long postCount( );
  131.  IEventSem::EventSemType type( );
  132.  const ISemaphoreHandle &handle( );
  133.  
  134. protected:
  135.  
  136. private:
  137.  // data
  138.  IString & szName;                 // semaphore name
  139.  ISemaphoreHandle * hndlSem;       // semaphore handle
  140.  EventSemType semType;             // type of semaphore.
  141.  
  142. };  // IEventSem
  143.  
  144. // Resume compiler default packing.
  145. #pragma pack()
  146.  
  147. #endif // _IEVNTSEM_
  148.