ACE/ace/SV_Semaphore_Complex.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file   SV_Semaphore_Complex.h
   6  *
   7  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
   8  */
   9 //=============================================================================
  10
  11 #ifndef ACE_SV_SEMAPHORE_COMPLEX_H
  12 #define ACE_SV_SEMAPHORE_COMPLEX_H
  13 #include /**/ "ace/pre.h"
  14
  15 #include "ace/SV_Semaphore_Simple.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_SV_Semaphore_Complex
  25  *
  26  * @brief This is a more complex semaphore wrapper that handles race
  27  * conditions for initialization correctly...
  28  *
  29  * This code is a port to C++, inspired by: W. Richard Stevens
  30  * from his book: UNIX Network Programming (Prentice Hall, ISBN
  31  * 0-13-949876-1 - 1990).  We provide a simpler and easier to
  32  * understand interface to the System V Semaphore system calls.
  33  * We create and use a 2 + n-member set for the requested
  34  * ACE_SV_Semaphore_Complex. The first member, [0], is a
  35  * counter used to know when all processes have finished with
  36  * the ACE_SV_Semaphore_Complex.  The counter is initialized
  37  * to a large number, decremented on every create or open and
  38  * incremented on every close. This way we can use the "adjust"
  39  * feature provided by System V so that any process that exit's
  40  * without calling <close> is accounted for. It doesn't help us
  41  * if the last process does this (as we have no way of getting
  42  * control to remove the ACE_SV_Semaphore_Complex) but it
  43  * will work if any process other than the last does an exit
  44  * (intentional or unintentional).
  45  * The second member, [1], of the semaphore is used as a lock
  46  * variable to avoid any race conditions in the create() and
  47  * close() functions.
  48  * The members beyond [1] are actual semaphore values in the
  49  * array of semaphores, which may be sized by the user in the
  50  * constructor.
  51  */
  52 class ACE_Export ACE_SV_Semaphore_Complex : private ACE_SV_Semaphore_Simple
  53 {
  54 public:
  55   enum
  56   {
  57     ACE_CREATE = IPC_CREAT,
  58     ACE_OPEN   = 0
  59   };
  60
  61   ACE_SV_Semaphore_Complex ();
  62   ACE_SV_Semaphore_Complex (key_t key,
  63                             short create = ACE_SV_Semaphore_Complex::ACE_CREATE,
  64                             int initial_value = 1,
  65                             u_short nsems = 1,
  66                             mode_t perms = ACE_DEFAULT_FILE_PERMS);
  67   ACE_SV_Semaphore_Complex (const char *name,
  68                             short create = ACE_SV_Semaphore_Complex::ACE_CREATE,
  69                             int initial_value = 1,
  70                             u_short nsems = 1,
  71                             mode_t perms = ACE_DEFAULT_FILE_PERMS);
  72   ~ACE_SV_Semaphore_Complex ();
  73
  74   /// Open or create an array of SV_Semaphores.  We return 0 if all is
  75   /// OK, else -1.
  76   int open (const char *name,
  77             short flags = ACE_SV_Semaphore_Simple::ACE_CREATE,
  78             int initial_value = 1,
  79             u_short nsems = 1,
  80             mode_t perms = ACE_DEFAULT_FILE_PERMS);
  81
  82   /// Open or create an array of SV_Semaphores.  We return 0 if all is
  83   /// OK, else -1.
  84   int open (key_t key,
  85             short flags = ACE_SV_Semaphore_Simple::ACE_CREATE,
  86             int initial_value = 1,
  87             u_short nsems = 1,
  88             mode_t perms = ACE_DEFAULT_FILE_PERMS);
  89
  90   /**
  91    * Close an ACE_SV_Semaphore. Unlike the remove() method, this
  92    * method is for a process to call before it exits, when it is done
  93    * with the ACE_SV_Semaphore. We "decrement" the counter of
  94    * processes using the ACE_SV_Semaphore, and if this was the last
  95    * one, we can remove the ACE_SV_Semaphore.
  96    */
  97   int close ();
  98
  99   // = Semaphore acquire and release methods.
 100
 101   /// Acquire the semaphore.
 102   int acquire (u_short n = 0, short flags = 0) const;
 103
 104   /// Acquire a semaphore for reading.
 105   int acquire_read (u_short n = 0, short flags = 0) const;
 106
 107   /// Acquire a semaphore for writing
 108   int acquire_write (u_short n = 0, short flags = 0) const;
 109
 110   /// Try to acquire the semaphore.
 111   int tryacquire (u_short n = 0, short flags = 0) const;
 112
 113   /// Try to acquire the semaphore for reading.
 114   int tryacquire_read (u_short n = 0, short flags = 0) const;
 115
 116   /// Try to acquire the semaphore for writing.
 117   int tryacquire_write (u_short n = 0, short flags = 0) const;
 118
 119   /// Release the semaphore.
 120   int release (u_short n = 0, short flags = 0) const;
 121
 122   // = Semaphore operation methods.
 123   int op (short val, u_short n = 0, short flags = 0) const;
 124   int op (sembuf op_vec[], u_short n) const;
 125
 126   // = Semaphore control methods.
 127   int control (int cmd, semun arg, u_short n = 0) const;
 128   int control (int cmd, int value = 0, u_short n = 0) const;
 129
 130   // = Upgrade access control...
 131   using ACE_SV_Semaphore_Simple::get_id;
 132   using ACE_SV_Semaphore_Simple::remove;
 133
 134   /// Dump the state of an object.
 135   void dump () const;
 136
 137   /// Declare the dynamic allocation hooks.
 138   ACE_ALLOC_HOOK_DECLARE;
 139
 140 private:
 141   static const int BIGCOUNT_;
 142   static sembuf op_lock_[2];
 143   static sembuf op_endcreate_[2];
 144   static sembuf op_open_[1];
 145   static sembuf op_close_[3];
 146   static sembuf op_unlock_[1];
 147 };
 148
 149 ACE_END_VERSIONED_NAMESPACE_DECL
 150
 151 #if defined (__ACE_INLINE__)
 152 #include "ace/SV_Semaphore_Complex.inl"
 153 #endif /* __ACE_INLINE__ */
 154
 155 #include /**/ "ace/post.h"
 156 #endif /* ACE_SV_SEMAPHORE_COMPLEX_H */