1 //////////////////////////////////////////////////////////////////////////////
2 //
3 // (C) Copyright Ion Gaztanaga 2005-2012. Distributed under the Boost
4 // Software License, Version 1.0. (See accompanying file
5 // LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6 //
7 // See http://www.boost.org/libs/interprocess for documentation.
8 //
9 //////////////////////////////////////////////////////////////////////////////
10
11 #ifndef BOOST_INTERPROCESS_NAMED_MUTEX_HPP
12 #define BOOST_INTERPROCESS_NAMED_MUTEX_HPP
13
14 #ifndef BOOST_CONFIG_HPP
15 # include <boost/config.hpp>
16 #endif
17 #
18 #if defined(BOOST_HAS_PRAGMA_ONCE)
19 # pragma once
20 #endif
21
22 #include <boost/interprocess/detail/config_begin.hpp>
23 #include <boost/interprocess/detail/workaround.hpp>
24 #include <boost/interprocess/creation_tags.hpp>
25 #include <boost/interprocess/exceptions.hpp>
26 #include <boost/interprocess/detail/interprocess_tester.hpp>
27 #include <boost/interprocess/permissions.hpp>
28
29 #if defined(BOOST_INTERPROCESS_NAMED_MUTEX_USES_POSIX_SEMAPHORES)
30 #include <boost/interprocess/sync/posix/named_mutex.hpp>
31 #define BOOST_INTERPROCESS_NAMED_MUTEX_USE_POSIX
32 #elif !defined(BOOST_INTERPROCESS_FORCE_GENERIC_EMULATION) && defined (BOOST_INTERPROCESS_WINDOWS)
33 #include <boost/interprocess/sync/windows/named_mutex.hpp>
34 #define BOOST_INTERPROCESS_NAMED_MUTEX_USE_WINAPI
35 #else
36 #include <boost/interprocess/sync/shm/named_mutex.hpp>
37 #endif
38
39 //!\file
40 //!Describes a named mutex class for inter-process synchronization
41
42 namespace boost {
43 namespace interprocess {
44
45 class named_condition;
46
47 //!A mutex with a global name, so it can be found from different
48 //!processes. This mutex can't be placed in shared memory, and
49 //!each process should have it's own named_mutex.
50 class named_mutex
51 {
52 #if !defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
53
54 //Non-copyable
55 named_mutex();
56 named_mutex(const named_mutex &);
57 named_mutex &operator=(const named_mutex &);
58 friend class named_condition;
59 #endif //#ifndef BOOST_INTERPROCESS_DOXYGEN_INVOKED
60
61 public:
62 //!Creates a global mutex with a name.
63 //!Throws interprocess_exception on error.
64 named_mutex(create_only_t create_only, const char *name, const permissions &perm = permissions());
65
66 //!Opens or creates a global mutex with a name.
67 //!If the mutex is created, this call is equivalent to
68 //!named_mutex(create_only_t, ... )
69 //!If the mutex is already created, this call is equivalent
70 //!named_mutex(open_only_t, ... )
71 //!Does not throw
72 named_mutex(open_or_create_t open_or_create, const char *name, const permissions &perm = permissions());
73
74 //!Opens a global mutex with a name if that mutex is previously
75 //!created. If it is not previously created this function throws
76 //!interprocess_exception.
77 named_mutex(open_only_t open_only, const char *name);
78
79 #if defined(BOOST_INTERPROCESS_WCHAR_NAMED_RESOURCES) || defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
80
81 //!Creates a global mutex with a name.
82 //!Throws interprocess_exception on error.
83 //!
84 //!Note: This function is only available on operating systems with
85 //! native wchar_t APIs (e.g. Windows).
86 named_mutex(create_only_t create_only, const wchar_t *name, const permissions &perm = permissions());
87
88 //!Opens or creates a global mutex with a name.
89 //!If the mutex is created, this call is equivalent to
90 //!named_mutex(create_only_t, ... )
91 //!If the mutex is already created, this call is equivalent
92 //!named_mutex(open_only_t, ... )
93 //!Does not throw
94 //!
95 //!Note: This function is only available on operating systems with
96 //! native wchar_t APIs (e.g. Windows).
97 named_mutex(open_or_create_t open_or_create, const wchar_t *name, const permissions &perm = permissions());
98
99 //!Opens a global mutex with a name if that mutex is previously
100 //!created. If it is not previously created this function throws
101 //!interprocess_exception.
102 //!
103 //!Note: This function is only available on operating systems with
104 //! native wchar_t APIs (e.g. Windows).
105 named_mutex(open_only_t open_only, const wchar_t *name);
106
107 #endif //defined(BOOST_INTERPROCESS_WCHAR_NAMED_RESOURCES) || defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
108
109 //!Destroys *this and indicates that the calling process is finished using
110 //!the resource. The destructor function will deallocate
111 //!any system resources allocated by the system for use by this process for
112 //!this resource. The resource can still be opened again calling
113 //!the open constructor overload. To erase the resource from the system
114 //!use remove().
115 ~named_mutex();
116
117 //!Unlocks a previously locked
118 //!mutex.
119 void unlock();
120
121 //!Requires: The calling thread does not own the mutex.
122 //!
123 //!Locks the mutex, sleeps when the mutex is already locked.
124 //!Throws interprocess_exception if a severe error is found
125 //!
126 //!Note: A program may deadlock if the thread that has ownership calls
127 //! this function. If the implementation can detect the deadlock,
128 //! an exception could be thrown.
129 void lock();
130
131 //!Requires: The calling thread does not own the mutex.
132 //!
133 //!Tries to lock the mutex, returns false when the mutex
134 //!is already locked, returns true when success.
135 //!Throws interprocess_exception if a severe error is found
136 //!
137 //!Note: A program may deadlock if the thread that has ownership calls
138 //! this function. If the implementation can detect the deadlock,
139 //! an exception could be thrown.
140 bool try_lock();
141
142 //!Requires: The calling thread does not own the mutex.
143 //!
144 //!Tries to lock the the mutex until time abs_time,
145 //!Returns false when timeout expires, returns true when locks.
146 //!Throws interprocess_exception if a severe error is found
147 //!
148 //!Note: A program may deadlock if the thread that has ownership calls
149 //! this function. If the implementation can detect the deadlock,
150 //! an exception could be thrown.
151 template<class TimePoint>
152 bool timed_lock(const TimePoint &abs_time);
153
154 //!Same as `timed_lock`, but this function is modeled after the
155 //!standard library interface.
try_lock_until(const TimePoint & abs_time)156 template<class TimePoint> bool try_lock_until(const TimePoint &abs_time)
157 { return this->timed_lock(abs_time); }
158
159 //!Same as `timed_lock`, but this function is modeled after the
160 //!standard library interface.
try_lock_for(const Duration & dur)161 template<class Duration> bool try_lock_for(const Duration &dur)
162 { return this->timed_lock(ipcdetail::duration_to_ustime(dur)); }
163
164 //!Erases a named mutex from the system.
165 //!Returns false on error. Never throws.
166 static bool remove(const char *name);
167
168 #if defined(BOOST_INTERPROCESS_WCHAR_NAMED_RESOURCES) || defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
169
170 //!Erases a named mutex from the system.
171 //!Returns false on error. Never throws.
172 //!
173 //!Note: This function is only available on operating systems with
174 //! native wchar_t APIs (e.g. Windows).
175 static bool remove(const wchar_t *name);
176
177 #endif //defined(BOOST_INTERPROCESS_WCHAR_NAMED_RESOURCES) || defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
178
179 #if !defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
180 private:
181 friend class ipcdetail::interprocess_tester;
182 void dont_close_on_destruction();
183
184 public:
185 #if defined(BOOST_INTERPROCESS_NAMED_MUTEX_USE_POSIX)
186 typedef ipcdetail::posix_named_mutex internal_mutex_type;
187 #elif defined(BOOST_INTERPROCESS_NAMED_MUTEX_USE_WINAPI)
188 typedef ipcdetail::winapi_named_mutex internal_mutex_type;
189 #else
190 typedef ipcdetail::shm_named_mutex internal_mutex_type;
191 #endif
internal_mutex()192 internal_mutex_type &internal_mutex()
193 { return m_mut; }
194
195 internal_mutex_type m_mut;
196
197 #endif //#ifndef BOOST_INTERPROCESS_DOXYGEN_INVOKED
198 };
199
200 #if !defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
201
named_mutex(create_only_t,const char * name,const permissions & perm)202 inline named_mutex::named_mutex(create_only_t, const char *name, const permissions &perm)
203 : m_mut(create_only_t(), name, perm)
204 {}
205
named_mutex(open_or_create_t,const char * name,const permissions & perm)206 inline named_mutex::named_mutex(open_or_create_t, const char *name, const permissions &perm)
207 : m_mut(open_or_create_t(), name, perm)
208 {}
209
named_mutex(open_only_t,const char * name)210 inline named_mutex::named_mutex(open_only_t, const char *name)
211 : m_mut(open_only_t(), name)
212 {}
213
214 #if defined(BOOST_INTERPROCESS_WCHAR_NAMED_RESOURCES) || defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
215
named_mutex(create_only_t,const wchar_t * name,const permissions & perm)216 inline named_mutex::named_mutex(create_only_t, const wchar_t *name, const permissions &perm)
217 : m_mut(create_only_t(), name, perm)
218 {}
219
named_mutex(open_or_create_t,const wchar_t * name,const permissions & perm)220 inline named_mutex::named_mutex(open_or_create_t, const wchar_t *name, const permissions &perm)
221 : m_mut(open_or_create_t(), name, perm)
222 {}
223
named_mutex(open_only_t,const wchar_t * name)224 inline named_mutex::named_mutex(open_only_t, const wchar_t *name)
225 : m_mut(open_only_t(), name)
226 {}
227
228 #endif //defined(BOOST_INTERPROCESS_WCHAR_NAMED_RESOURCES) || defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
229
dont_close_on_destruction()230 inline void named_mutex::dont_close_on_destruction()
231 { ipcdetail::interprocess_tester::dont_close_on_destruction(m_mut); }
232
~named_mutex()233 inline named_mutex::~named_mutex()
234 {}
235
lock()236 inline void named_mutex::lock()
237 { m_mut.lock(); }
238
unlock()239 inline void named_mutex::unlock()
240 { m_mut.unlock(); }
241
try_lock()242 inline bool named_mutex::try_lock()
243 { return m_mut.try_lock(); }
244
245 template<class TimePoint>
timed_lock(const TimePoint & abs_time)246 inline bool named_mutex::timed_lock(const TimePoint &abs_time)
247 { return m_mut.timed_lock(abs_time); }
248
remove(const char * name)249 inline bool named_mutex::remove(const char *name)
250 { return internal_mutex_type::remove(name); }
251
252 #if defined(BOOST_INTERPROCESS_WCHAR_NAMED_RESOURCES) || defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
253
remove(const wchar_t * name)254 inline bool named_mutex::remove(const wchar_t *name)
255 { return internal_mutex_type::remove(name); }
256
257 #endif
258
259 #endif //#ifndef BOOST_INTERPROCESS_DOXYGEN_INVOKED
260
261 } //namespace interprocess {
262 } //namespace boost {
263
264 #include <boost/interprocess/detail/config_end.hpp>
265
266 #endif //BOOST_INTERPROCESS_NAMED_MUTEX_HPP
267