dep/ACE_wrappers/ace/File_Lock.h

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