summaryrefslogtreecommitdiff
path: root/ace/File_Lock.h
blob: aaa9ac67699078bd63390b7ce839a0c2bcd5ffe2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
// -*- C++ -*-

//=============================================================================
/**
 *  @file    File_Lock.h
 *
 *  $Id$
 *
 *  @author Douglas C. Schmidt <schmidt@cs.wustl.edu>
 */
//=============================================================================

#ifndef ACE_FILE_LOCK_H
#define ACE_FILE_LOCK_H
#include /**/ "ace/pre.h"

#ifdef ACE_THREADS_BUILD_DLL
# include "ace/ACE_Threads_export.h"
#else
# include "ace/ACE_export.h"
# define ACE_Threads_Export ACE_Export
#endif  /* ACE_THREADS_BUILD_DLL */

#if !defined (ACE_LACKS_PRAGMA_ONCE)
# pragma once
#endif /* ACE_LACKS_PRAGMA_ONCE */

#include "ace/OS_NS_stdio.h"

ACE_BEGIN_VERSIONED_NAMESPACE_DECL

/**
 * @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_Threads_Export ACE_File_Lock
{
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> 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>.
   */
  ACE_File_Lock (ACE_HANDLE handle = ACE_INVALID_HANDLE,
                 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>.
  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_>.
  int open (const ACE_TCHAR *filename,
            int flags,
            mode_t mode = 0);

  /// 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_>.  If <unlink_file> is non-0 then we unlink the file.
  int remove (int unlink_file = 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...
   */
  int acquire (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>.
   */
  int tryacquire (short whence = 0, off_t start = 0, off_t len = 1);

  /// Unlock a readers/writer lock.
  int release (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.
  int acquire_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>.
   */
  int tryacquire_write (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>.
   */
  int tryacquire_write_upgrade (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>.
   */
  int acquire_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>.
   */
  int tryacquire_read (short whence = 0, off_t start = 0, off_t len = 1);

  /// Get underlying <ACE_HANDLE> for the file.
  ACE_HANDLE get_handle (void) const;

  /**
   * 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);

  /// Dump state of the object.
  void dump (void) const;

  /// Declare the dynamic allocation hooks.
  ACE_ALLOC_HOOK_DECLARE;

protected:
  /// Locking structure for OS record locks.
  ACE_OS::ace_flock_t lock_;

  /// 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...
  int removed_;

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

private:
  // = Prevent assignment and initialization.
  void operator= (const ACE_File_Lock &);
  ACE_File_Lock (const ACE_File_Lock &);
};

ACE_END_VERSIONED_NAMESPACE_DECL

#if defined (__ACE_INLINE__)
#include "ace/File_Lock.inl"
#endif /* __ACE_INLINE__ */

#include /**/ "ace/post.h"
#endif /* ACE_FILE_LOCK_H */