Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

File_Lock.h

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

Generated on Mon Jun 16 11:19:41 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002