ACE/ace/Event_Base.h

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