ACE/ace/Reverse_Lock_T.h

   1 // -*- C++ -*-
   2
   3 //==========================================================================
   4 /**
   5  *  @file    Reverse_Lock_T.h
   6  *
   7  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
   8  */
   9 //==========================================================================
  10
  11 #ifndef ACE_REVERSE_LOCK_T_H
  12 #define ACE_REVERSE_LOCK_T_H
  13 #include /**/ "ace/pre.h"
  14
  15 #include "ace/Lock.h"
  16
  17 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  18 # pragma once
  19 #endif /* ACE_LACKS_PRAGMA_ONCE */
  20
  21 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  22
  23 /**
  24  * @namespace ACE_Acquire_Method
  25  *
  26  * @brief An enum namespace.
  27  *
  28  * These enums should have been inside the reverse lock class, but
  29  * some lame compilers cannot handle enums inside template classes.
  30  *
  31  * The METHOD_TYPE is used to indicate which acquire() method will be
  32  * called on the real lock when the release() method is called on the
  33  * reverse lock. REGULAR indicated the acquire() method, READ
  34  * indicates the acquire_read() method, and WRITE indicates the
  35  * acquire_write() method.  Note that the try_*() methods are not
  36  * represented here because we have to make sure that the release()
  37  * method on the reverse lock acquires a lock on the real lock.
  38  **/
  39 namespace ACE_Acquire_Method
  40 {
  41   enum METHOD_TYPE
  42   {
  43     ACE_REGULAR,
  44     ACE_READ,
  45     ACE_WRITE
  46   };
  47 }
  48
  49 /**
  50  * @class ACE_Reverse_Lock
  51  *
  52  * @brief A reverse (or anti) lock.
  53  *
  54  * This is an interesting adapter class that changes a lock into
  55  * a reverse lock, i.e., <acquire> on this class calls <release>
  56  * on the lock, and <release> on this class calls <acquire> on
  57  * the lock.
  58  * One motivation for this class is when we temporarily want to
  59  * release a lock (which we have already acquired) but then
  60  * reacquire it soon after.  An alternative design would be to
  61  * add a Anti_Guard or Reverse_Guard class which would <release>
  62  * on construction and <acquire> destruction.  However, there
  63  * are *many* varieties of the Guard class and this design
  64  * choice would lead to at least 6 new classes.  One new
  65  * ACE_Reverse_Lock class seemed more reasonable.
  66  */
  67 template <class ACE_LOCKING_MECHANISM>
  68 class ACE_Reverse_Lock : public ACE_Lock
  69 {
  70 public:
  71   typedef ACE_LOCKING_MECHANISM ACE_LOCK;
  72
  73   // = Initialization/Finalization methods.
  74
  75   /// Constructor. All locking requests will be forwarded to @a lock.
  76   ACE_Reverse_Lock (ACE_LOCKING_MECHANISM &lock,
  77                     ACE_Acquire_Method::METHOD_TYPE acquire_method = ACE_Acquire_Method::ACE_REGULAR);
  78
  79   /// Destructor. If <lock_> was not passed in by the user, it will be
  80   /// deleted.
  81   virtual ~ACE_Reverse_Lock () = default;
  82
  83   // = Lock accessors.
  84   /// Release the lock.
  85   virtual int acquire ();
  86
  87   /// Release the lock.
  88   virtual int tryacquire ();
  89
  90   /// Acquire the lock.
  91   virtual int release ();
  92
  93   /// Release the lock.
  94   virtual int acquire_read ();
  95
  96   /// Release the lock.
  97   virtual int acquire_write ();
  98
  99   /// Release the lock.
 100   virtual int tryacquire_read ();
 101
 102   /// Release the lock.
 103   virtual int tryacquire_write ();
 104
 105   /// Release the lock.
 106   virtual int tryacquire_write_upgrade ();
 107
 108   /// Explicitly destroy the lock.
 109   virtual int remove ();
 110
 111 private:
 112   /// The concrete locking mechanism that all the methods delegate to.
 113   ACE_LOCKING_MECHANISM &lock_;
 114
 115   /// This indicates what kind of acquire method will be called.
 116   ACE_Acquire_Method::METHOD_TYPE acquire_method_;
 117 };
 118
 119 ACE_END_VERSIONED_NAMESPACE_DECL
 120
 121 #if defined (__ACE_INLINE__)
 122 #include "ace/Reverse_Lock_T.inl"
 123 #endif /* __ACE_INLINE__ */
 124
 125 #include "ace/Reverse_Lock_T.cpp"
 126
 127 #include /**/ "ace/post.h"
 128 #endif /* ACE_REVERSE_LOCK_T_H */