ACE/ace/Guard_T.h

   1 // -*- C++ -*-
   2
   3 //==========================================================================
   4 /**
   5  *  @file    Guard_T.h
   6  *
   7  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
   8  */
   9 //==========================================================================
  10
  11 #ifndef ACE_GUARD_T_H
  12 #define ACE_GUARD_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 #include "ace/Global_Macros.h"
  22 #include "ace/OS_NS_Thread.h"
  23
  24 // FUZZ: disable check_for_ACE_Guard
  25
  26 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  27
  28 /**
  29  * @class ACE_Guard
  30  *
  31  * @brief This data structure is meant to be used within a method or
  32  * function...  It performs automatic acquisition and release of
  33  * a parameterized synchronization object ACE_LOCK.
  34  *
  35  * The ACE_LOCK class given as an actual parameter must provide, at
  36  * the very least the acquire(), tryacquire(), release(), and
  37  * remove() methods.
  38  *
  39  * @warning A successfully constructed ACE_Guard does NOT mean that the
  40  * lock was acquired!  It is the caller's responsibility, after
  41  * constructing an ACE_Guard, to check whether the lock was successfully
  42  * acquired.  Code like this is dangerous:
  43  *   {
  44  *     ACE_Guard<ACE_Lock> g(lock);
  45  *     ... perform critical operation requiring lock to be held ...
  46  *   }
  47  * Instead, one must do something like this:
  48  *   {
  49  *     ACE_Guard<ACE_Lock> g(lock);
  50  *     if (! g.locked())
  51  *       {
  52  *         ... handle error ...
  53  *       }
  54  *     else
  55  *       {
  56  *         ... perform critical operation requiring lock to be held ...
  57  *       }
  58  *   }
  59  * The ACE_GUARD_RETURN() and ACE_GUARD_REACTION() macros are designed to
  60  * to help with this.
  61  */
  62 template <class ACE_LOCK>
  63 class ACE_Guard
  64 {
  65 public:
  66   ACE_Guard (ACE_LOCK &l);
  67
  68   /// Implicitly and automatically acquire (or try to acquire) the
  69   /// lock.  If @a block is non-0 then acquire() the ACE_LOCK, else
  70   /// tryacquire() it.
  71   ACE_Guard (ACE_LOCK &l, bool block);
  72
  73   /// Initialize the guard without implicitly acquiring the lock. The
  74   /// @a become_owner parameter indicates whether the guard should release
  75   /// the lock implicitly on destruction. The @a block parameter is
  76   /// ignored and is used here to disambiguate with the preceding
  77   /// constructor.
  78   ACE_Guard (ACE_LOCK &l, bool block, int become_owner);
  79
  80   /// Implicitly release the lock.
  81   ~ACE_Guard ();
  82
  83   // = Lock accessors.
  84
  85   /// Explicitly acquire the lock.
  86   int acquire ();
  87
  88   /// Conditionally acquire the lock (i.e., won't block).
  89   int tryacquire ();
  90
  91   /// Explicitly release the lock, but only if it is held!
  92   int release ();
  93
  94   /// Relinquish ownership of the lock so that it is not released
  95   /// implicitly in the destructor.
  96   void disown ();
  97
  98   // = Utility methods.
  99   /// true if locked, false if couldn't acquire the lock
 100   /// (errno will contain the reason for this).
 101   bool locked () const;
 102
 103   /// Explicitly remove the lock.
 104   int remove ();
 105
 106   /// Dump the state of an object.
 107   void dump () const;
 108
 109   // ACE_ALLOC_HOOK_DECLARE;
 110   // Declare the dynamic allocation hooks.
 111
 112 protected:
 113   /// Helper, meant for subclass only.
 114   ACE_Guard (ACE_LOCK *lock): lock_ (lock), owner_ (0) {}
 115
 116   /// Pointer to the ACE_LOCK we're guarding.
 117   ACE_LOCK *lock_;
 118
 119   /// Keeps track of whether we acquired the lock or failed.
 120   int owner_;
 121
 122 private:
 123   void operator= (const ACE_Guard<ACE_LOCK> &) = delete;
 124   ACE_Guard (const ACE_Guard<ACE_LOCK> &) = delete;
 125 };
 126
 127 /**
 128  * @class ACE_Write_Guard
 129  *
 130  * @brief This class is similar to class ACE_Guard, though it
 131  * acquires/releases a write lock automatically (naturally, the
 132  * <ACE_LOCK> it is instantiated with must support the appropriate
 133  * API).
 134  *
 135  * @warning See important "WARNING" in comments at top of ACE_Guard.
 136  */
 137 template <class ACE_LOCK>
 138 class ACE_Write_Guard : public ACE_Guard<ACE_LOCK>
 139 {
 140 public:
 141   /// Implicitly and automatically acquire a write lock.
 142   ACE_Write_Guard (ACE_LOCK &m);
 143
 144   /// Implicitly and automatically acquire (or try to acquire) a write
 145   /// lock.
 146   ACE_Write_Guard (ACE_LOCK &m, bool block);
 147
 148   // = Lock accessors.
 149
 150   /// Explicitly acquire the write lock.
 151   int acquire_write ();
 152
 153   /// Explicitly acquire the write lock.
 154   int acquire ();
 155
 156   /// Conditionally acquire the write lock (i.e., won't block).
 157   int tryacquire_write ();
 158
 159   /// Conditionally acquire the write lock (i.e., won't block).
 160   int tryacquire ();
 161
 162   // = Utility methods.
 163
 164   /// Dump the state of an object.
 165   void dump () const;
 166
 167   // ACE_ALLOC_HOOK_DECLARE;
 168   // Declare the dynamic allocation hooks.
 169 };
 170
 171 /**
 172  * @class ACE_Read_Guard
 173  *
 174  * @brief This class is similar to class ACE_Guard, though it
 175  * acquires/releases a read lock automatically (naturally, the
 176  * <ACE_LOCK> it is instantiated with must support the appropriate
 177  * API).
 178  *
 179  * @warning See important "WARNING" in comments at top of ACE_Guard.
 180  */
 181 template <class ACE_LOCK>
 182 class ACE_Read_Guard : public ACE_Guard<ACE_LOCK>
 183 {
 184 public:
 185   /// Implicitly and automatically acquire a read lock.
 186   ACE_Read_Guard (ACE_LOCK& m);
 187
 188   /// Implicitly and automatically acquire (or try to acquire) a read
 189   /// lock.
 190   ACE_Read_Guard (ACE_LOCK &m, bool block);
 191
 192   // = Lock accessors.
 193
 194   /// Explicitly acquire the read lock.
 195   int acquire_read ();
 196
 197   /// Explicitly acquire the read lock.
 198   int acquire ();
 199
 200   /// Conditionally acquire the read lock (i.e., won't block).
 201   int tryacquire_read ();
 202
 203   /// Conditionally acquire the read lock (i.e., won't block).
 204   int tryacquire ();
 205
 206   // = Utility methods.
 207
 208   /// Dump the state of an object.
 209   void dump () const;
 210
 211   // ACE_ALLOC_HOOK_DECLARE;
 212   // Declare the dynamic allocation hooks.
 213 };
 214
 215 #if !(defined (ACE_HAS_THREADS) && (defined (ACE_HAS_THREAD_SPECIFIC_STORAGE) || defined (ACE_HAS_TSS_EMULATION)))
 216
 217 #define ACE_TSS_Guard ACE_Guard
 218 #define ACE_TSS_Write_GUARD ACE_Write_Guard
 219 #define ACE_TSS_Read_GUARD ACE_Read_Guard
 220
 221 #else
 222  /* ACE platform supports some form of threading and
 223   thread-specific storage. */
 224
 225 /**
 226  * @class ACE_TSS_Guard
 227  *
 228  * @brief This data structure is meant to be used within a method or
 229  * function...  It performs automatic aquisition and release of
 230  * a synchronization object.  Moreover, it ensures that the lock
 231  * is released even if a thread exits via <thr_exit>!
 232  */
 233 template <class ACE_LOCK>
 234 class ACE_TSS_Guard
 235 {
 236 public:
 237   /// Implicitly and automatically acquire the thread-specific lock.
 238   ACE_TSS_Guard (ACE_LOCK &lock, bool block = true);
 239
 240   /// Implicitly release the thread-specific lock.
 241   ~ACE_TSS_Guard ();
 242
 243   // = Lock accessors.
 244
 245   /// Explicitly acquire the thread-specific lock.
 246   int acquire ();
 247
 248   /// Conditionally acquire the thread-specific lock (i.e., won't
 249   /// block).
 250   int tryacquire ();
 251
 252   /// Explicitly release the thread-specific lock.
 253   int release ();
 254
 255   // = Utility methods.
 256   /// Explicitly release the thread-specific lock.
 257   int remove ();
 258
 259   /// Dump the state of an object.
 260   void dump () const;
 261
 262   /// Declare the dynamic allocation hooks.
 263   ACE_ALLOC_HOOK_DECLARE;
 264
 265 protected:
 266   /// Helper, meant for subclass only.
 267   ACE_TSS_Guard ();
 268
 269   /// Initialize the key.
 270   void init_key ();
 271
 272   /// Called when thread exits to clean up the lock.
 273   static void cleanup (void *ptr);
 274
 275   /// Thread-specific key...
 276   ACE_thread_key_t key_;
 277
 278 private:
 279   // FUZZ: disable check_for_ACE_Guard
 280   typedef ACE_Guard<ACE_LOCK> Guard_Type;
 281   // FUZZ: enable check_for_ACE_Guard
 282
 283   void operator= (const ACE_TSS_Guard<ACE_LOCK> &) = delete;
 284   ACE_TSS_Guard (const ACE_TSS_Guard<ACE_LOCK> &) = delete;
 285 };
 286
 287 /**
 288  * @class ACE_TSS_Write_Guard
 289  *
 290  * @brief This class is similar to class ACE_TSS_Guard, though it
 291  * acquires/releases a write-lock automatically (naturally, the
 292  * ACE_LOCK it is instantiated with must support the appropriate
 293  * API).
 294  */
 295 template <class ACE_LOCK>
 296 class ACE_TSS_Write_Guard : public ACE_TSS_Guard<ACE_LOCK>
 297 {
 298 public:
 299   /// Implicitly and automatically acquire the thread-specific write lock.
 300   ACE_TSS_Write_Guard (ACE_LOCK &lock, bool block = true);
 301
 302   // = Lock accessors.
 303
 304   /// Explicitly acquire the thread-specific write lock.
 305   int acquire_write ();
 306
 307   /// Explicitly acquire the thread-specific write lock.
 308   int acquire ();
 309
 310   /// Conditionally acquire the thread-specific write lock (i.e., won't block).
 311   int tryacquire_write ();
 312
 313   /// Conditionally acquire the thread-specific write lock (i.e., won't block).
 314   int tryacquire ();
 315
 316   // = Utility methods.
 317
 318   /// Dump the state of an object.
 319   void dump () const;
 320
 321   // ACE_ALLOC_HOOK_DECLARE;
 322   // Declare the dynamic allocation hooks.
 323 private:
 324   // FUZZ: disable check_for_ACE_Guard
 325   typedef ACE_Guard<ACE_LOCK> Guard_Type;
 326   typedef ACE_Write_Guard<ACE_LOCK> Write_Guard_Type;
 327   // FUZZ: enable check_for_ACE_Guard
 328 };
 329
 330 /**
 331  * @class ACE_TSS_Read_Guard
 332  *
 333  * @brief This class is similar to class <ACE_TSS_Guard>, though it
 334  * acquires/releases a read lock automatically (naturally, the
 335  * <ACE_LOCK> it is instantiated with must support the
 336  * appropriate API).
 337  */
 338 template <class ACE_LOCK>
 339 class ACE_TSS_Read_Guard : public ACE_TSS_Guard<ACE_LOCK>
 340 {
 341 public:
 342   /// Implicitly and automatically acquire the thread-specific read lock.
 343   ACE_TSS_Read_Guard (ACE_LOCK &lock, bool block = true);
 344
 345   // = Lock accessors.
 346   /// Explicitly acquire the thread-specific read lock.
 347   int acquire_read ();
 348
 349   /// Explicitly acquire the thread-specific read lock.
 350   int acquire ();
 351
 352   /// Conditionally acquire the thread-specific read lock (i.e., won't
 353   /// block).
 354   int tryacquire_read ();
 355
 356   /// Conditionally acquire the thread-specific read lock (i.e., won't
 357   /// block).
 358   int tryacquire ();
 359
 360   // = Utility methods.
 361   /// Dump the state of an object.
 362   void dump () const;
 363
 364   // ACE_ALLOC_HOOK_DECLARE;
 365   // Declare the dynamic allocation hooks.
 366 private:
 367   // FUZZ: disable check_for_ACE_Guard
 368   typedef ACE_Guard<ACE_LOCK> Guard_Type;
 369   typedef ACE_Read_Guard<ACE_LOCK> Read_Guard_Type;
 370   // FUZZ: enable check_for_ACE_Guard
 371 };
 372
 373 #endif /* !(defined (ACE_HAS_THREADS) && (defined (ACE_HAS_THREAD_SPECIFIC_STORAGE) || defined (ACE_HAS_TSS_EMULATION))) */
 374
 375 ACE_END_VERSIONED_NAMESPACE_DECL
 376
 377 #if defined (__ACE_INLINE__)
 378 #include "ace/Guard_T.inl"
 379 #endif /* __ACE_INLINE__ */
 380
 381 #include "ace/Guard_T.cpp"
 382
 383 #include /**/ "ace/post.h"
 384 #endif /* ACE_GUARD_T_H */