ACE/ace/Lock.h

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