diff options
Diffstat (limited to 'ace/File_Lock.h')
| -rw-r--r-- | ace/File_Lock.h | 149 |
1 files changed, 82 insertions, 67 deletions
diff --git a/ace/File_Lock.h b/ace/File_Lock.h index 1cce6e4370b..f1d438e5734 100644 --- a/ace/File_Lock.h +++ b/ace/File_Lock.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// File_Lock.h -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file File_Lock.h + * + * $Id$ + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_FILE_LOCK_H #define ACE_FILE_LOCK_H @@ -24,102 +21,120 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_File_Lock + * + * @brief A wrapper around the UNIX file locking mechanism. + * + * Allows us to "adapt" the UNIX file locking mechanisms to work + * with all of our Guard stuff... + */ class ACE_Export ACE_File_Lock { - // = TITLE - // A wrapper around the UNIX file locking mechanism. - // - // = DESCRIPTION - // Allows us to "adapt" the UNIX file locking mechanisms to work - // with all of our Guard stuff... public: + /** + * Set the <handle_> of the File_Lock to <handle>. Note that this + * constructor assumes ownership of the <handle> and will close it + * down in <remove>. If you want the <handle> stays open when + * <remove> is called make sure to call <dup> on the <handle> before + * closing it. + */ ACE_File_Lock (ACE_HANDLE handle = ACE_INVALID_HANDLE); - // Set the <handle_> of the File_Lock to <handle>. Note that this - // constructor assumes ownership of the <handle> and will close it - // down in <remove>. If you want the <handle> stays open when - // <remove> is called make sure to call <dup> on the <handle> before - // closing it. + /// Open the <filename> with <flags> and <mode> and set the result to + /// <handle_>. ACE_File_Lock (const ACE_TCHAR *filename, int flags, mode_t mode = 0); - // Open the <filename> with <flags> and <mode> and set the result to - // <handle_>. + /// Open the <filename> with <flags> and <mode> and set the result to + /// <handle_>. int open (const ACE_TCHAR *filename, int flags, mode_t mode = 0); - // Open the <filename> with <flags> and <mode> and set the result to - // <handle_>. + /// Remove a File lock by releasing it and closing down the <handle_>. ~ACE_File_Lock (void); - // Remove a File lock by releasing it and closing down the <handle_>. + /// Remove a File lock by releasing it and closing down the + /// <handle_>. If <unlink_file> is non-0 then we unlink the file. int remove (int unlink_file = 1); - // Remove a File lock by releasing it and closing down the - // <handle_>. If <unlink_file> is non-0 then we unlink the file. + /** + * Note, for interface uniformity with other synchronization + * wrappers we include the <acquire> method. This is implemented as + * a write-lock to be on the safe-side... + */ int acquire (short whence = 0, off_t start = 0, off_t len = 1); - // Note, for interface uniformity with other synchronization - // wrappers we include the <acquire> method. This is implemented as - // a write-lock to be on the safe-side... + /** + * Note, for interface uniformity with other synchronization + * wrappers we include the <tryacquire> method. This is implemented + * as a write-lock to be on the safe-side... Returns -1 on failure. + * If we "failed" because someone else already had the lock, <errno> + * is set to <EBUSY>. + */ int tryacquire (short whence = 0, off_t start = 0, off_t len = 1); - // Note, for interface uniformity with other synchronization - // wrappers we include the <tryacquire> method. This is implemented - // as a write-lock to be on the safe-side... Returns -1 on failure. - // If we "failed" because someone else already had the lock, <errno> - // is set to <EBUSY>. + /// Unlock a readers/writer lock. int release (short whence = 0, off_t start = 0, off_t len = 1); - // Unlock a readers/writer lock. + /// Acquire a write lock, but block if any readers or a + /// writer hold the lock. int acquire_write (short whence = 0, off_t start = 0, off_t len = 1); - // Acquire a write lock, but block if any readers or a - // writer hold the lock. + /** + * Conditionally acquire a write lock (i.e., won't block). Returns + * -1 on failure. If we "failed" because someone else already had + * the lock, <errno> is set to <EBUSY>. + */ int tryacquire_write (short whence = 0, off_t start = 0, off_t len = 1); - // Conditionally acquire a write lock (i.e., won't block). Returns - // -1 on failure. If we "failed" because someone else already had - // the lock, <errno> is set to <EBUSY>. + /** + * Conditionally upgrade to a write lock (i.e., won't block). Returns + * -1 on failure. If we "failed" because someone else already had + * the lock, <errno> is set to <EBUSY>. + */ int tryacquire_write_upgrade (short whence = 0, off_t start = 0, off_t len = 1); - // Conditionally upgrade to a write lock (i.e., won't block). Returns - // -1 on failure. If we "failed" because someone else already had - // the lock, <errno> is set to <EBUSY>. + /** + * Acquire a read lock, but block if a writer hold the lock. + * Returns -1 on failure. If we "failed" because someone else + * already had the lock, <errno> is set to <EBUSY>. + */ int acquire_read (short whence = 0, off_t start = 0, off_t len = 1); - // Acquire a read lock, but block if a writer hold the lock. - // Returns -1 on failure. If we "failed" because someone else - // already had the lock, <errno> is set to <EBUSY>. + /** + * Conditionally acquire a read lock (i.e., won't block). Returns + * -1 on failure. If we "failed" because someone else already had + * the lock, <errno> is set to <EBUSY>. + */ int tryacquire_read (short whence = 0, off_t start = 0, off_t len = 1); - // Conditionally acquire a read lock (i.e., won't block). Returns - // -1 on failure. If we "failed" because someone else already had - // the lock, <errno> is set to <EBUSY>. + /// Get underlying <ACE_HANDLE> for the file. ACE_HANDLE get_handle (void); - // Get underlying <ACE_HANDLE> for the file. + /** + * Set underlying <ACE_HANDLE>. Note that this method assumes + * ownership of the <handle> and will close it down in <remove>. If + * you want the <handle> to stay open when <remove> is called make + * sure to call <dup> on the <handle> before closing it. You are + * responsible for the closing the existing <handle> before + * overwriting it. + */ void set_handle (ACE_HANDLE); - // Set underlying <ACE_HANDLE>. Note that this method assumes - // ownership of the <handle> and will close it down in <remove>. If - // you want the <handle> to stay open when <remove> is called make - // sure to call <dup> on the <handle> before closing it. You are - // responsible for the closing the existing <handle> before - // overwriting it. + /// Dump state of the object. void dump (void) const; - // Dump state of the object. + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. protected: + /// Locking structure for OS record locks. ACE_OS::ace_flock_t lock_; - // Locking structure for OS record locks. + /// Keeps track of whether <remove> has been called yet to avoid + /// multiple <remove> calls, e.g., explicitly and implicitly in the int removed_; - // Keeps track of whether <remove> has been called yet to avoid - // multiple <remove> calls, e.g., explicitly and implicitly in the // destructor. This flag isn't protected by a lock, so make sure // that you don't have multiple threads simultaneously calling // <remove> on the same object, which is a bad idea anyway... |