ACE/ace/File_Lock.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    File_Lock.h
   6  *
   7  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
   8  */
   9 //=============================================================================
  10
  11 #ifndef ACE_FILE_LOCK_H
  12 #define ACE_FILE_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 #include "ace/OS_NS_stdio.h"
  22
  23 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  24
  25 /**
  26  * @class ACE_File_Lock
  27  *
  28  * @brief A wrapper around the UNIX file locking mechanism.
  29  *
  30  * Allows us to "adapt" the UNIX file locking mechanisms to work
  31  * with all of our Guard stuff...
  32  */
  33 class ACE_Export ACE_File_Lock
  34 {
  35 public:
  36   /**
  37    * Set the <handle_> of the File_Lock to @a handle.  Note that this
  38    * constructor assumes ownership of the @a handle and will close it
  39    * down in <remove>.  If you want the @a handle to stay open when
  40    * <remove> is called make sure to call <dup> on the @a handle.
  41    * If you don't want the file unlinked in the destructor pass a
  42    * zero value for <unlink_in_destructor>.
  43    */
  44   ACE_File_Lock (ACE_HANDLE handle = ACE_INVALID_HANDLE,
  45                  bool unlink_in_destructor = true);
  46
  47   /// Open the @a filename with @a flags and @a mode and set the result
  48   /// to <handle_>.  If you don't want the file unlinked in the
  49   /// destructor pass a false value for @a unlink_in_destructor.
  50   ACE_File_Lock (const ACE_TCHAR *filename,
  51                  int flags,
  52                  mode_t mode = 0,
  53                  bool unlink_in_destructor = true);
  54
  55   /// Open the @a filename with @a flags and @a mode and set the result to
  56   /// <handle_>.
  57   int open (const ACE_TCHAR *filename,
  58             int flags,
  59             mode_t mode = 0);
  60
  61   /// Remove a File lock by releasing it and closing down the <handle_>.
  62   ~ACE_File_Lock (void);
  63
  64   /// Remove a File lock by releasing it and closing down the
  65   /// <handle_>.  If @a unlink_file is true then we unlink the file.
  66   int remove (bool unlink_file = true);
  67
  68   /**
  69    * Note, for interface uniformity with other synchronization
  70    * wrappers we include the acquire() method. This is implemented as
  71    * a write-lock to be on the safe-side...
  72    */
  73   int acquire (short whence = 0, ACE_OFF_T start = 0, ACE_OFF_T len = 1);
  74
  75   /**
  76    * Note, for interface uniformity with other synchronization
  77    * wrappers we include the <tryacquire> method.  This is implemented
  78    * as a write-lock to be on the safe-side...  Returns -1 on failure.
  79    * If we "failed" because someone else already had the lock, @c errno
  80    * is set to @c EBUSY.
  81    */
  82   int tryacquire (short whence = 0, ACE_OFF_T start = 0, ACE_OFF_T len = 1);
  83
  84   /// Unlock a readers/writer lock.
  85   int release (short whence = 0, ACE_OFF_T start = 0, ACE_OFF_T len = 1);
  86
  87   /// Acquire a write lock, but block if any readers or a
  88   /// writer hold the lock.
  89   int acquire_write (short whence = 0, ACE_OFF_T start = 0, ACE_OFF_T len = 1);
  90
  91   /**
  92    * Conditionally acquire a write lock (i.e., won't block).  Returns
  93    * -1 on failure.  If we "failed" because someone else already had
  94    * the lock, @c errno is set to @c EBUSY.
  95    */
  96   int tryacquire_write (short whence = 0, ACE_OFF_T start = 0, ACE_OFF_T len = 1);
  97
  98   /**
  99    * Conditionally upgrade to a write lock (i.e., won't block).  Returns
 100    * -1 on failure.  If we "failed" because someone else already had
 101    * the lock, @c errno is set to @c EBUSY.
 102    */
 103   int tryacquire_write_upgrade (short whence = 0,
 104                                 ACE_OFF_T start = 0,
 105                                 ACE_OFF_T len = 1);
 106
 107   /**
 108    * Acquire a read lock, but block if a writer hold the lock.
 109    * Returns -1 on failure.  If we "failed" because someone else
 110    * already had the lock, @c errno is set to @c EBUSY.
 111    */
 112   int acquire_read (short whence = 0, ACE_OFF_T start = 0, ACE_OFF_T len = 1);
 113
 114   /**
 115    * Conditionally acquire a read lock (i.e., won't block).  Returns
 116    * -1 on failure.  If we "failed" because someone else already had
 117    * the lock, @c errno is set to @c EBUSY.
 118    */
 119   int tryacquire_read (short whence = 0, ACE_OFF_T start = 0, ACE_OFF_T len = 1);
 120
 121   /// Get underlying ACE_HANDLE for the file.
 122   ACE_HANDLE get_handle (void) const;
 123
 124   /**
 125    * Set underlying ACE_HANDLE.  Note that this method assumes
 126    * ownership of the @a handle and will close it down in <remove>.  If
 127    * you want the @a handle to stay open when <remove> is called make
 128    * sure to call <dup> on the @a handle before closing it. You are
 129    * responsible for the closing the existing @a handle before
 130    * overwriting it.
 131    */
 132   void set_handle (ACE_HANDLE);
 133
 134   /// Dump state of the object.
 135   void dump (void) const;
 136
 137   /// Declare the dynamic allocation hooks.
 138   ACE_ALLOC_HOOK_DECLARE;
 139
 140 protected:
 141   /// Locking structure for OS record locks.
 142   ACE_OS::ace_flock_t lock_;
 143
 144   /// Keeps track of whether <remove> has been called yet to avoid
 145   /// multiple <remove> calls, e.g., explicitly and implicitly in the
 146   /// destructor.  This flag isn't protected by a lock, so make sure
 147   /// that you don't have multiple threads simultaneously calling
 148   /// <remove> on the same object, which is a bad idea anyway...
 149   bool removed_;
 150
 151   /// Keeps track of whether to unlink the underlying file in the
 152   /// destructor.
 153   bool const unlink_in_destructor_;
 154
 155 private:
 156   // = Prevent assignment and initialization.
 157   void operator= (const ACE_File_Lock &);
 158   ACE_File_Lock (const ACE_File_Lock &);
 159 };
 160
 161 ACE_END_VERSIONED_NAMESPACE_DECL
 162
 163 #if defined (__ACE_INLINE__)
 164 #include "ace/File_Lock.inl"
 165 #endif /* __ACE_INLINE__ */
 166
 167 #include /**/ "ace/post.h"
 168 #endif /* ACE_FILE_LOCK_H */