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

ACE_File_Lock Class Reference

A wrapper around the UNIX file locking mechanism. More...

#include <File_Lock.h>

Collaboration diagram for ACE_File_Lock:

Collaboration graph
[legend]
List of all members.

Public Methods

 ACE_File_Lock (ACE_HANDLE handle=ACE_INVALID_HANDLE, int unlink_in_destructor=1)
 ACE_File_Lock (const ACE_TCHAR *filename, int flags, mode_t mode=0, int unlink_in_destructor=1)
 Open the <filename> with <flags> and <mode> and set the result to <handle_>. If you don't want the file unlinked in the destructor pass a zero value for <unlink_in_destructor>. More...

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_>. More...

 ~ACE_File_Lock (void)
 Remove a File lock by releasing it and closing down the <handle_>. More...

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. More...

int acquire (short whence=0, off_t start=0, off_t len=1)
int tryacquire (short whence=0, off_t start=0, off_t len=1)
int release (short whence=0, off_t start=0, off_t len=1)
 Unlock a readers/writer lock. More...

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. More...

int tryacquire_write (short whence=0, off_t start=0, off_t len=1)
int tryacquire_write_upgrade (short whence=0, off_t start=0, off_t len=1)
int acquire_read (short whence=0, off_t start=0, off_t len=1)
int tryacquire_read (short whence=0, off_t start=0, off_t len=1)
ACE_HANDLE get_handle (void) const
 Get underlying <ACE_HANDLE> for the file. More...

void set_handle (ACE_HANDLE)
void dump (void) const
 Dump state of the object. More...


Public Attributes

 ACE_ALLOC_HOOK_DECLARE
 Declare the dynamic allocation hooks. More...


Protected Attributes

ACE_OS::ace_flock_t lock_
 Locking structure for OS record locks. More...

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... More...

int unlink_in_destructor_
 Keeps track of whether to unlink the underlying file in the destructor. More...


Private Methods

void operator= (const ACE_File_Lock &)
 ACE_File_Lock (const ACE_File_Lock &)

Detailed Description

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...

Definition at line 31 of file File_Lock.h.

Constructor & Destructor Documentation

ACE_File_Lock::ACE_File_Lock (  ACE_HANDLE    handle = ACE_INVALID_HANDLE,
int    unlink_in_destructor = 1
) 
 

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> to stay open when <remove> is called make sure to call <dup> on the <handle>. If you don't want the file unlinked in the destructor pass a zero value for <unlink_in_destructor>.

Definition at line 25 of file File_Lock.cpp.

References ACE_ERROR, ACE_LIB_TEXT, ACE_OS::flock_init, LM_ERROR, and set_handle. 

00027   : removed_ (0),
00028     unlink_in_destructor_ (unlink_in_destructor)
00029 {
00030 // ACE_TRACE ("ACE_File_Lock::ACE_File_Lock");
00031   if (ACE_OS::flock_init (&this->lock_) == -1)
00032     ACE_ERROR ((LM_ERROR,
00033                 ACE_LIB_TEXT ("%p\n"),
00034                 ACE_LIB_TEXT ("ACE_File_Lock::ACE_File_Lock")));
00035   this->set_handle (h);
00036 }

ACE_File_Lock::ACE_File_Lock (  const ACE_TCHAR *    filename,
int    flags,
mode_t    mode = 0,
int    unlink_in_destructor = 1
) 
 

Open the <filename> with <flags> and <mode> and set the result to <handle_>. If you don't want the file unlinked in the destructor pass a zero value for <unlink_in_destructor>.

Definition at line 38 of file File_Lock.cpp.

References ACE_ERROR, ACE_LIB_TEXT, ACE_TCHAR, LM_ERROR, mode_t, and open. 

00042   : unlink_in_destructor_ (unlink_in_destructor)
00043 {
00044 // ACE_TRACE ("ACE_File_Lock::ACE_File_Lock");
00045 
00046   if (this->open (name, flags, perms) == -1)
00047     ACE_ERROR ((LM_ERROR,
00048                 ACE_LIB_TEXT ("%p %s\n"),
00049                 ACE_LIB_TEXT ("ACE_File_Lock::ACE_File_Lock"),
00050                 name));
00051 }

ACE_File_Lock::~ACE_File_Lock (  void    ) 
 

Remove a File lock by releasing it and closing down the <handle_>.

Definition at line 63 of file File_Lock.cpp.

References remove. 

00064 {
00065 // ACE_TRACE ("ACE_File_Lock::~ACE_File_Lock");
00066   this->remove (this->unlink_in_destructor_);
00067 }

ACE_File_Lock::ACE_File_Lock (  const ACE_File_Lock &    )  [private]
 

Member Function Documentation

ACE_INLINE int ACE_File_Lock::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...

Definition at line 47 of file File_Lock.inl.

References acquire_write.

Referenced by ACE_RW_Process_Mutex::acquire. 

00048 {
00049 // ACE_TRACE ("ACE_File_Lock::acquire");
00050   return this->acquire_write (whence, start, len);
00051 }

ACE_INLINE int ACE_File_Lock::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>.

Definition at line 5 of file File_Lock.inl.

References ACE_OS::flock_rdlock.

Referenced by ACE_RW_Process_Mutex::acquire_read. 

00006 {
00007 // ACE_TRACE ("ACE_File_Lock::acquire_read");
00008   return ACE_OS::flock_rdlock (&this->lock_, whence, start, len);
00009 }

ACE_INLINE int ACE_File_Lock::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.

Definition at line 40 of file File_Lock.inl.

References ACE_OS::flock_wrlock.

Referenced by acquire, and ACE_RW_Process_Mutex::acquire_write. 

00041 {
00042 // ACE_TRACE ("ACE_File_Lock::acquire_write");
00043   return ACE_OS::flock_wrlock (&this->lock_, whence, start, len);
00044 }

void ACE_File_Lock::dump (  void    )  const
 

Dump state of the object.

Definition at line 16 of file File_Lock.cpp.

References ACE_BEGIN_DUMP, ACE_DEBUG, ACE_END_DUMP, ACE_OS::ace_flock_t::dump, LM_DEBUG, and lock_.

Referenced by ACE_RW_Process_Mutex::dump. 

00017 {
00018 // ACE_TRACE ("ACE_File_Lock::dump");
00019 
00020   ACE_DEBUG ((LM_DEBUG, ACE_BEGIN_DUMP, this));
00021   this->lock_.dump ();
00022   ACE_DEBUG ((LM_DEBUG, ACE_END_DUMP));
00023 }

ACE_INLINE ACE_HANDLE ACE_File_Lock::get_handle (  void    )  const
 

Get underlying <ACE_HANDLE> for the file.

Definition at line 77 of file File_Lock.inl.

References ACE_OS::ace_flock_t::handle_, and lock_. 

00078 {
00079 // ACE_TRACE ("ACE_File_Lock::get_handle");
00080   return this->lock_.handle_;
00081 }

int ACE_File_Lock::open (  const ACE_TCHAR *    filename,
int    flags,
mode_t    mode = 0
) 
 

Open the <filename> with <flags> and <mode> and set the result to <handle_>.

Definition at line 54 of file File_Lock.cpp.

References ACE_TCHAR, ACE_OS::flock_init, mode_t, and removed_.

Referenced by ACE_File_Lock. 

00057 {
00058 // ACE_TRACE ("ACE_File_Lock::open");
00059   this->removed_ = 0;
00060   return ACE_OS::flock_init (&this->lock_, flags, name, perms);
00061 }

void ACE_File_Lock::operator= (  const ACE_File_Lock &    )  [private]
 

ACE_INLINE int ACE_File_Lock::release (  short    whence = 0,
off_t    start = 0,
off_t    len = 1
) 
 

Unlock a readers/writer lock.

Definition at line 54 of file File_Lock.inl.

References ACE_OS::flock_unlock.

Referenced by ACE_RW_Process_Mutex::release. 

00055 {
00056 // ACE_TRACE ("ACE_File_Lock::release");
00057   return ACE_OS::flock_unlock (&this->lock_, whence, start, len);
00058 }

ACE_INLINE int ACE_File_Lock::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.

Definition at line 61 of file File_Lock.inl.

References ACE_OS::flock_destroy, and removed_.

Referenced by ACE_RW_Process_Mutex::remove, and ~ACE_File_Lock. 

00062 {
00063 // ACE_TRACE ("ACE_File_Lock::remove");
00064 
00065   int result = 0;
00066 
00067   if (this->removed_ == 0)
00068     {
00069       this->removed_ = 1;
00070       result = ACE_OS::flock_destroy (&this->lock_,
00071                                       unlink_file);
00072     }
00073   return result;
00074 }

ACE_INLINE void ACE_File_Lock::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.

Definition at line 84 of file File_Lock.inl.

References ACE_OS::ace_flock_t::handle_, lock_, and removed_.

Referenced by ACE_File_Lock. 

00085 {
00086 // ACE_TRACE ("ACE_File_Lock::set_handle");
00087   this->lock_.handle_ = h;
00088   this->removed_ = 0;
00089 }

ACE_INLINE int ACE_File_Lock::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>.

Definition at line 33 of file File_Lock.inl.

References tryacquire_write.

Referenced by ACE_RW_Process_Mutex::tryacquire. 

00034 {
00035 // ACE_TRACE ("ACE_File_Lock::tryacquire");
00036   return this->tryacquire_write (whence, start, len);
00037 }

ACE_INLINE int ACE_File_Lock::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>.

Definition at line 12 of file File_Lock.inl.

References ACE_OS::flock_tryrdlock.

Referenced by ACE_RW_Process_Mutex::tryacquire_read. 

00013 {
00014 // ACE_TRACE ("ACE_File_Lock::tryacquire_read");
00015   return ACE_OS::flock_tryrdlock (&this->lock_, whence, start, len);
00016 }

ACE_INLINE int ACE_File_Lock::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>.

Definition at line 19 of file File_Lock.inl.

References ACE_OS::flock_trywrlock.

Referenced by tryacquire, and ACE_RW_Process_Mutex::tryacquire_write. 

00020 {
00021 // ACE_TRACE ("ACE_File_Lock::tryacquire_write");
00022   return ACE_OS::flock_trywrlock (&this->lock_, whence, start, len);
00023 }

ACE_INLINE int ACE_File_Lock::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>.

Definition at line 26 of file File_Lock.inl.

References ACE_OS::flock_trywrlock.

Referenced by ACE_RW_Process_Mutex::tryacquire_write_upgrade. 

00027 {
00028 // ACE_TRACE ("ACE_File_Lock::tryacquire_write_upgrade");
00029   return ACE_OS::flock_trywrlock (&this->lock_, whence, start, len);
00030 }

Member Data Documentation

ACE_File_Lock::ACE_ALLOC_HOOK_DECLARE
 

Declare the dynamic allocation hooks.

Definition at line 136 of file File_Lock.h.

ACE_OS::ace_flock_t ACE_File_Lock::lock_ [protected]
 

Locking structure for OS record locks.

Definition at line 140 of file File_Lock.h.

Referenced by dump, get_handle, and set_handle.

int ACE_File_Lock::removed_ [protected]
 

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...

Definition at line 147 of file File_Lock.h.

Referenced by open, remove, and set_handle.

int ACE_File_Lock::unlink_in_destructor_ [protected]
 

Keeps track of whether to unlink the underlying file in the destructor.

Definition at line 151 of file File_Lock.h.

The documentation for this class was generated from the following files:
Generated on Mon Jun 16 12:47:55 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002