ACE/ace/Lock.h

   1 // -*- C++ -*-
   2
   3 //==========================================================================
   4 /**
   5  *  @file    Lock.h
   6  *
   7  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
   8  */
   9 //==========================================================================
  10
  11 #ifndef ACE_LOCK_H
  12 #define ACE_LOCK_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 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  22
  23 /**
  24  * @class ACE_Lock
  25  *
  26  * @brief This is the abstract base class that contains the uniform
  27  * locking API that is supported by all the ACE synchronization
  28  * mechanisms.
  29  *
  30  * This class is typically used in conjunction with the
  31  * ACE_Lock_Adapter in order to provide a polymorphic
  32  * interface to the ACE synchronization mechanisms (e.g.,
  33  * ACE_Mutex, ACE_Semaphore, ACE_RW_Mutex, etc).  Note that
  34  * the reason that all of ACE doesn't use polymorphic locks is
  35  * that (1) they add ~20% extra overhead for virtual function
  36  * calls and (2) objects with virtual functions can't be placed
  37  * into shared memory.
  38  */
  39 class ACE_Export ACE_Lock
  40 {
  41 public:
  42   /// CE needs a default constructor here.
  43   ACE_Lock ();
  44
  45   /// Noop virtual destructor
  46   virtual ~ACE_Lock () = default;
  47
  48   /**
  49    * Explicitly destroy the lock.  Note that only one thread should
  50    * call this method since it doesn't protect against race
  51    * conditions.
  52    */
  53   virtual int remove () = 0;
  54
  55   /// Block the thread until the lock is acquired.  Returns -1 on
  56   /// failure.
  57   virtual int acquire () = 0;
  58
  59   /**
  60    * Conditionally acquire the lock (i.e., won't block).  Returns -1
  61    * on failure.  If we "failed" because someone else already had the
  62    * lock, @c errno is set to @c EBUSY.
  63    */
  64   virtual int tryacquire () = 0;
  65
  66   /// Release the lock.  Returns -1 on failure.
  67   virtual int release () = 0;
  68
  69   /**
  70    * Block until the thread acquires a read lock.  If the locking
  71    * mechanism doesn't support read locks then this just calls
  72    * acquire().  Returns -1 on failure.
  73    */
  74   virtual int acquire_read () = 0;
  75
  76   /**
  77    * Block until the thread acquires a write lock.  If the locking
  78    * mechanism doesn't support read locks then this just calls
  79    * acquire().  Returns -1 on failure.
  80    */
  81   virtual int acquire_write () = 0;
  82
  83   /**
  84    * Conditionally acquire a read lock.  If the locking mechanism
  85    * doesn't support read locks then this just calls acquire().
  86    * Returns -1 on failure.  If we "failed" because someone else
  87    * already had the lock, @c errno is set to @c EBUSY.
  88    */
  89   virtual int tryacquire_read () = 0;
  90
  91   /**
  92    * Conditionally acquire a write lock.  If the locking mechanism
  93    * doesn't support read locks then this just calls acquire().
  94    * Returns -1 on failure.  If we "failed" because someone else
  95    * already had the lock, @c errno is set to @c EBUSY.
  96    */
  97   virtual int tryacquire_write () = 0;
  98
  99   /**
 100    * Conditionally try to upgrade a lock held for read to a write lock.
 101    * If the locking mechanism doesn't support read locks then this just
 102    * calls acquire(). Returns 0 on success, -1 on failure.
 103    */
 104   virtual int tryacquire_write_upgrade () = 0;
 105 };
 106
 107 /**
 108  * @class ACE_Adaptive_Lock
 109  *
 110  * @brief An adaptive general locking class that defers the decision of
 111  * lock type to run time.
 112  *
 113  * This class, as ACE_Lock, provide a set of general locking APIs.
 114  * However, it defers our decision of what kind of lock to use
 115  * to the run time and delegates all locking operations to the actual
 116  * lock.  Users must define a constructor in their subclass to
 117  * initialize @c lock_.
 118  */
 119 class ACE_Export ACE_Adaptive_Lock : public ACE_Lock
 120 {
 121 public:
 122   /// You must also override the destructor function to match with how
 123   /// you construct the underneath @c lock_.
 124   virtual ~ACE_Adaptive_Lock () = default;
 125
 126   // = Lock/unlock operations.
 127
 128   virtual int remove ();
 129   virtual int acquire ();
 130   virtual int tryacquire ();
 131   virtual int release ();
 132   virtual int acquire_read ();
 133   virtual int acquire_write ();
 134   virtual int tryacquire_read ();
 135   virtual int tryacquire_write ();
 136   virtual int tryacquire_write_upgrade ();
 137   void dump () const;
 138
 139 protected:
 140   /**
 141    * Create and initialize create the actual lock used in the class.
 142    * The default constructor simply set the @c lock_ to 0 (null).  You
 143    * must overwrite this method for this class to work.
 144    */
 145   ACE_Adaptive_Lock () = default;
 146
 147   ACE_Lock *lock_ {};
 148 };
 149
 150 ACE_END_VERSIONED_NAMESPACE_DECL
 151
 152 #if defined (__ACE_INLINE__)
 153 #include "ace/Lock.inl"
 154 #endif /* __ACE_INLINE__ */
 155
 156 #include /**/ "ace/post.h"
 157 #endif /* ACE_LOCK_H */