File_Lock.h

Go to the documentation of this file.
00001 // -*- C++ -*-
00002 
00003 //=============================================================================
00004 /**
00005  *  @file    File_Lock.h
00006  *
00007  *  File_Lock.h,v 4.10 2006/02/10 09:53:14 jwillemsen Exp
00008  *
00009  *  @author Douglas C. Schmidt <schmidt@cs.wustl.edu>
00010  */
00011 //=============================================================================
00012 
00013 #ifndef ACE_FILE_LOCK_H
00014 #define ACE_FILE_LOCK_H
00015 #include /**/ "ace/pre.h"
00016 
00017 #include "ace/ACE_export.h"
00018 
00019 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00020 # pragma once
00021 #endif /* ACE_LACKS_PRAGMA_ONCE */
00022 
00023 #include "ace/OS_NS_stdio.h"
00024 
00025 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
00026 
00027 /**
00028  * @class ACE_File_Lock
00029  *
00030  * @brief A wrapper around the UNIX file locking mechanism.
00031  *
00032  * Allows us to "adapt" the UNIX file locking mechanisms to work
00033  * with all of our Guard stuff...
00034  */
00035 class ACE_Export ACE_File_Lock
00036 {
00037 public:
00038   /**
00039    * Set the <handle_> of the File_Lock to <handle>.  Note that this
00040    * constructor assumes ownership of the <handle> and will close it
00041    * down in <remove>.  If you want the <handle> to stay open when
00042    * <remove> is called make sure to call <dup> on the <handle>.
00043    * If you don't want the file unlinked in the destructor pass a
00044    * zero value for <unlink_in_destructor>.
00045    */
00046   ACE_File_Lock (ACE_HANDLE handle = ACE_INVALID_HANDLE,
00047                  int unlink_in_destructor = 1);
00048 
00049   /// Open the <filename> with <flags> and <mode> and set the result
00050   /// to <handle_>.  If you don't want the file unlinked in the
00051   /// destructor pass a zero value for <unlink_in_destructor>.
00052   ACE_File_Lock (const ACE_TCHAR *filename,
00053                  int flags,
00054                  mode_t mode = 0,
00055                  int unlink_in_destructor = 1);
00056 
00057   /// Open the <filename> with <flags> and <mode> and set the result to
00058   /// <handle_>.
00059   int open (const ACE_TCHAR *filename,
00060             int flags,
00061             mode_t mode = 0);
00062 
00063   /// Remove a File lock by releasing it and closing down the <handle_>.
00064   ~ACE_File_Lock (void);
00065 
00066   /// Remove a File lock by releasing it and closing down the
00067   /// <handle_>.  If <unlink_file> is non-0 then we unlink the file.
00068   int remove (int unlink_file = 1);
00069 
00070   /**
00071    * Note, for interface uniformity with other synchronization
00072    * wrappers we include the <acquire> method.  This is implemented as
00073    * a write-lock to be on the safe-side...
00074    */
00075   int acquire (short whence = 0, off_t start = 0, off_t len = 1);
00076 
00077   /**
00078    * Note, for interface uniformity with other synchronization
00079    * wrappers we include the <tryacquire> method.  This is implemented
00080    * as a write-lock to be on the safe-side...  Returns -1 on failure.
00081    * If we "failed" because someone else already had the lock, <errno>
00082    * is set to <EBUSY>.
00083    */
00084   int tryacquire (short whence = 0, off_t start = 0, off_t len = 1);
00085 
00086   /// Unlock a readers/writer lock.
00087   int release (short whence = 0, off_t start = 0, off_t len = 1);
00088 
00089   /// Acquire a write lock, but block if any readers or a
00090   /// writer hold the lock.
00091   int acquire_write (short whence = 0, off_t start = 0, off_t len = 1);
00092 
00093   /**
00094    * Conditionally acquire a write lock (i.e., won't block).  Returns
00095    * -1 on failure.  If we "failed" because someone else already had
00096    * the lock, <errno> is set to <EBUSY>.
00097    */
00098   int tryacquire_write (short whence = 0, off_t start = 0, off_t len = 1);
00099 
00100   /**
00101    * Conditionally upgrade to a write lock (i.e., won't block).  Returns
00102    * -1 on failure.  If we "failed" because someone else already had
00103    * the lock, <errno> is set to <EBUSY>.
00104    */
00105   int tryacquire_write_upgrade (short whence = 0,
00106                                 off_t start = 0,
00107                                 off_t len = 1);
00108 
00109   /**
00110    * Acquire a read lock, but block if a writer hold the lock.
00111    * Returns -1 on failure.  If we "failed" because someone else
00112    * already had the lock, <errno> is set to <EBUSY>.
00113    */
00114   int acquire_read (short whence = 0, off_t start = 0, off_t len = 1);
00115 
00116   /**
00117    * Conditionally acquire a read lock (i.e., won't block).  Returns
00118    * -1 on failure.  If we "failed" because someone else already had
00119    * the lock, <errno> is set to <EBUSY>.
00120    */
00121   int tryacquire_read (short whence = 0, off_t start = 0, off_t len = 1);
00122 
00123   /// Get underlying ACE_HANDLE for the file.
00124   ACE_HANDLE get_handle (void) const;
00125 
00126   /**
00127    * Set underlying ACE_HANDLE.  Note that this method assumes
00128    * ownership of the <handle> and will close it down in <remove>.  If
00129    * you want the <handle> to stay open when <remove> is called make
00130    * sure to call <dup> on the <handle> before closing it. You are
00131    * responsible for the closing the existing <handle> before
00132    * overwriting it.
00133    */
00134   void set_handle (ACE_HANDLE);
00135 
00136   /// Dump state of the object.
00137   void dump (void) const;
00138 
00139   /// Declare the dynamic allocation hooks.
00140   ACE_ALLOC_HOOK_DECLARE;
00141 
00142 protected:
00143   /// Locking structure for OS record locks.
00144   ACE_OS::ace_flock_t lock_;
00145 
00146   /// Keeps track of whether <remove> has been called yet to avoid
00147   /// multiple <remove> calls, e.g., explicitly and implicitly in the
00148   /// destructor.  This flag isn't protected by a lock, so make sure
00149   /// that you don't have multiple threads simultaneously calling
00150   /// <remove> on the same object, which is a bad idea anyway...
00151   int removed_;
00152 
00153   /// Keeps track of whether to unlink the underlying file in the
00154   /// destructor.
00155   int unlink_in_destructor_;
00156 
00157 private:
00158   // = Prevent assignment and initialization.
00159   void operator= (const ACE_File_Lock &);
00160   ACE_File_Lock (const ACE_File_Lock &);
00161 };
00162 
00163 ACE_END_VERSIONED_NAMESPACE_DECL
00164 
00165 #if defined (__ACE_INLINE__)
00166 #include "ace/File_Lock.inl"
00167 #endif /* __ACE_INLINE__ */
00168 
00169 #include /**/ "ace/post.h"
00170 #endif /* ACE_FILE_LOCK_H */

Generated on Thu Nov 9 09:41:51 2006 for ACE by doxygen 1.3.6