ACE/ace/Event_Base.h

   1 // -*- C++ -*-
   2
   3 //==========================================================================
   4 /**
   5  *  @file    Event_Base.h
   6  *
   7  *  @author Martin Corino <mcorino@remedy.nl>
   8  */
   9 //==========================================================================
  10
  11 #ifndef ACE_EVENT_BASE_H
  12 #define ACE_EVENT_BASE_H
  13 #include /**/ "ace/pre.h"
  14
  15 #include /**/ "ace/ACE_export.h"
  16
  17 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  18 # pragma once
  19 #endif /* ACE_LACKS_PRAGMA_ONCE */
  20
  21 #include "ace/OS_NS_Thread.h"
  22 #include "ace/Time_Value.h"
  23
  24 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  25
  26 /**
  27  * @class ACE_Event_Base
  28  *
  29  * @brief A base class for wrappers around the Win32 event locking
  30  *        mechanism.
  31  *
  32  * Portable implementation of an Event mechanism, which is native to
  33  * Win32, but must be emulated on UNIX.  All platforms support
  34  * process-scope locking support.  However, only Win32 platforms
  35  * support global naming and system-scope locking support.
  36  */
  37 class ACE_Export ACE_Event_Base
  38 {
  39 public:
  40   /// Implicitly destroy the event variable.
  41   virtual ~ACE_Event_Base ();
  42
  43   /**
  44    * Explicitly destroy the event variable.  Note that only one thread
  45    * should call this method since it doesn't protect against race
  46    * conditions.
  47    */
  48   int remove ();
  49
  50   /// Underlying handle to event.
  51   ACE_event_t handle () const;
  52
  53   /**
  54    * Set the underlying handle to event. Note that this method assumes
  55    * ownership of the <handle> and will close it down in <remove>.  If
  56    * you want the <handle> to stay open when <remove> is called make
  57    * sure to call <dup> on the <handle> before closing it.  You are
  58    * responsible for the closing the existing <handle> before
  59    * overwriting it.
  60    */
  61   void handle (ACE_event_t new_handle);
  62
  63   /**
  64    * if MANUAL reset
  65    *    sleep till the event becomes signaled
  66    *    event remains signaled after wait() completes.
  67    * else AUTO reset
  68    *    sleep till the event becomes signaled
  69    *    event resets wait() completes.
  70    */
  71   int wait ();
  72
  73   /// Same as wait() above, but this one can be timed
  74   /// @a abstime is absolute time-of-day if if @a use_absolute_time
  75   /// is non-0, else it is relative time.
  76   int wait (const ACE_Time_Value *abstime,
  77             int use_absolute_time = 1);
  78
  79   /**
  80    * if MANUAL reset
  81    *    wake up all waiting threads
  82    *    set to signaled state
  83    * else AUTO reset
  84    *    if no thread is waiting, set to signaled state
  85    *    if thread(s) are waiting, wake up one waiting thread and
  86    *    reset event
  87    */
  88   int signal ();
  89
  90   /**
  91    * if MANUAL reset
  92    *    wakeup all waiting threads and
  93    *    reset event
  94    * else AUTO reset
  95    *    wakeup one waiting thread (if present) and
  96    *    reset event
  97    */
  98   int pulse ();
  99
 100   /// Set to nonsignaled state.
 101   int reset ();
 102
 103   /// Dump the state of an object.
 104   void dump () const;
 105
 106   /// Declare the dynamic allocation hooks
 107   ACE_ALLOC_HOOK_DECLARE;
 108
 109 protected:
 110   /// Only derived classes allowed to construct event.
 111   ACE_Event_Base ();
 112
 113
 114   /// The underlying handle.
 115   ACE_event_t handle_;
 116
 117   /// Keeps track of whether <remove> has been called yet to avoid
 118   /// multiple <remove> calls, e.g., explicitly and implicitly in the
 119   /// destructor.  This flag isn't protected by a lock, so make sure
 120   /// that you don't have multiple threads simultaneously calling
 121   /// <remove> on the same object, which is a bad idea anyway...
 122   bool removed_;
 123
 124 private:
 125   ACE_Event_Base (const ACE_Event_Base& event) = delete;
 126   const ACE_Event_Base &operator= (const ACE_Event_Base &rhs) = delete;
 127 };
 128
 129 ACE_END_VERSIONED_NAMESPACE_DECL
 130
 131 #if defined (__ACE_INLINE__)
 132 #include "ace/Event_Base.inl"
 133 #endif /* __ACE_INLINE__ */
 134
 135 #include /**/ "ace/post.h"
 136 #endif /* ACE_EVENT_BASE_H */