|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r77660 - trunk/libs/thread/doc
From: vicente.botet_at_[hidden]
Date: 2012-03-31 03:38:01
Author: viboes
Date: 2012-03-31 03:37:59 EDT (Sat, 31 Mar 2012)
New Revision: 77660
URL: http://svn.boost.org/trac/boost/changeset/77660
Log:
Thread: Update doc with a lot of changes to follow the updated code
Added:
trunk/libs/thread/doc/emulations.qbk (contents, props changed)
Text files modified:
trunk/libs/thread/doc/changes.qbk | 51 +
trunk/libs/thread/doc/compliance.qbk | 103 ++--
trunk/libs/thread/doc/future_ref.qbk | 278 ++++++++++--
trunk/libs/thread/doc/mutex_concepts.qbk | 878 +++++++++++++++++++++++++++++++--------
trunk/libs/thread/doc/overview.qbk | 5
trunk/libs/thread/doc/shared_mutex_ref.qbk | 99 ++++
trunk/libs/thread/doc/thread.qbk | 52 ++
trunk/libs/thread/doc/thread_ref.qbk | 347 ++++++++++++---
trunk/libs/thread/doc/time.qbk | 23
9 files changed, 1447 insertions(+), 389 deletions(-)
Modified: trunk/libs/thread/doc/changes.qbk
==============================================================================
--- trunk/libs/thread/doc/changes.qbk (original)
+++ trunk/libs/thread/doc/changes.qbk 2012-03-31 03:37:59 EDT (Sat, 31 Mar 2012)
@@ -12,28 +12,40 @@
New Features:
+[/
+* [@http://svn.boost.org/trac/boost/ticket/1850 #1850] Request for unlock_guard to compliment lock_guard.
+* [@http://svn.boost.org/trac/boost/ticket/2637 #2637] Request for shared_mutex duration timed_lock and timed_lock_shared.
+]
+
* [@http://svn.boost.org/trac/boost/ticket/2741 #2741] Proposal to manage portable and non portable thread attributes.
+* [@http://svn.boost.org/trac/boost/ticket/3567 #3567] Request for shared_lock_guard.
+* [@http://svn.boost.org/trac/boost/ticket/6194 #6194] Adapt to Boost.Move.
* [@http://svn.boost.org/trac/boost/ticket/6195 #6195] c++11 compliance: Provide the standard time related interface using Boost.Chrono.
+* [@http://svn.boost.org/trac/boost/ticket/6217 #6217] Enhance Boost.Thread shared mutex interface following Howard Hinnant proposal.
* [@http://svn.boost.org/trac/boost/ticket/6224 #6224] c++11 compliance: Add the use of standard noexcept on compilers supporting them.
* [@http://svn.boost.org/trac/boost/ticket/6226 #6226] c++11 compliance: Add explicit bool conversion from locks.
* [@http://svn.boost.org/trac/boost/ticket/6230 #6230] c++11 compliance: Follows the exception reporting mechanism as defined in the c++11.
* [@http://svn.boost.org/trac/boost/ticket/6272 #6272] c++11 compliance: Add thread::id hash specialization.
* [@http://svn.boost.org/trac/boost/ticket/6273 #6273] c++11 compliance: Add cv_status enum class and use it on the conditions wait functions.
-* [@http://svn.boost.org/trac/boost/ticket/6194 #6194] Adapt to Boost.Move.
+* [@http://svn.boost.org/trac/boost/ticket/6231 #6231] Add BasicLockable requirements in the documentation to follow c++11.
+* [@http://svn.boost.org/trac/boost/ticket/6671 #6671] upgrade_lock: missing mutex and release functions.
+* [@http://svn.boost.org/trac/boost/ticket/6672 #6672] upgrade_lock:: missing constructors from time related types.
+* [@http://svn.boost.org/trac/boost/ticket/6675 #6675] upgrade_lock:: missing non-member swap.
+
Fixed Bugs:
* [@http://svn.boost.org/trac/boost/ticket/2575 #2575] Bug- Boost 1.36.0 on Itanium platform.
* [@http://svn.boost.org/trac/boost/ticket/4921 #4921] BOOST_THREAD_USE_DLL and BOOST_THREAD_USE_LIB are crucial and need to be documented.
* [@http://svn.boost.org/trac/boost/ticket/5013 #5013] documentation: boost::thread: pthreas_exit causes terminate().
-
* [@http://svn.boost.org/trac/boost/ticket/5351 #5351] interrupt a future get boost::unknown_exception.
* [@http://svn.boost.org/trac/boost/ticket/5516 #5516] Upgrade lock is not acquired when previous upgrade lock releases if another read lock is present.
* [@http://svn.boost.org/trac/boost/ticket/5990 #5990] shared_future<T>::get() has wrong return type.
* [@http://svn.boost.org/trac/boost/ticket/6174 #6174] packaged_task doesn't correctly handle moving results.
+* [@http://svn.boost.org/trac/boost/ticket/6673 #6673] shared_lock: move assign doesn't works with c++11.
+* [@http://svn.boost.org/trac/boost/ticket/6674 #6674] shared_mutex: try_lock_upgrade_until doesn't works.
[/
-
Deprecated features since boost 1.50 available only until boost 1.55:
These deprecated features will be provided by default up to boost 1.52. If you don't want to include the deprecated features you could define BOOST_THREAD_DONT_PROVIDE_DEPRECATED_FEATURES_SINCE_V2_0_0. Since 1.53 these features will not be included any more by default. Since this version, if you want to include the deprecated features yet you could define BOOST_THREAD_PROVIDE_DEPRECATED_FEATURES_SINCE_V2_0_0. These deprecated features will be only available until boost 1.55, that is you have 1 year and a half to move to the new features.
@@ -42,7 +54,7 @@
Breaking changes:
-There are some new features which share the same interface but with different behavior. These breaking features are not provided by default when BOOST_THREAD_VERSION is 2, but the user can however choose the version 1 behavior by defining the corresponding macro. As for the deprecated features, these broken features will be only available until boost 1.55.
+There are some new features which share the same interface but with different behavior. These breaking features are provided by default when BOOST_THREAD_VERSION is 2, but the user can however choose the version 1 behavior by defining the corresponding macro. As for the deprecated features, these broken features will be only available until boost 1.55.
* #6266 c++11 compliance: thread destructor should call terminate if joinable
* #6269 c++11 compliance: thread move assignment should call terminate if joinable
@@ -162,15 +174,30 @@
[section:future Future]
-The following features will be included in next releases. By order of priority:
+The following features will be included in next releases.
+
+# Complete the C++11 missing features, in particular
+
+ * [@http://svn.boost.org/trac/boost/ticket/4710 #4710] Missing async().
+ * [@http://svn.boost.org/trac/boost/ticket/6266 #6266] Breaking change: thread destructor should call terminate if joinable.
+ * [@http://svn.boost.org/trac/boost/ticket/6269 #6269] Breaking change: thread move assignment should call terminate if joinable.
+ * [@http://svn.boost.org/trac/boost/ticket/6342 #6342] Breaking change: Adapt the one_flag and call_once to the c++11 interface.
+
+ * [@http://svn.boost.org/trac/boost/ticket/6227 #6227] Use of variadic templates on Generic Locking Algorithms on compilers providing them.
+ * [@http://svn.boost.org/trac/boost/ticket/6228 #6228] Add promise and futures constructor with allocator following the standard c++11.
+ * [@http://svn.boost.org/trac/boost/ticket/6270 #6270] Add thread constructor from movable callable and movable arguments following C++11.
+
+
+# Add some complementary locks
+
+ * [@http://svn.boost.org/trac/boost/ticket/1850 #1850] Request for unlock_guard (and/or unique_unlock) to compliment lock_guard/unique_lock.
+ * [@http://svn.boost.org/trac/boost/ticket/3567 #3567] Request for shared_lock_guard.
+
+# Add the shared locking upward conversions.
+
+ * [@http://svn.boost.org/trac/boost/ticket/6217 #6217] Enhance Boost.Thread shared mutex interface following Howard Hinnant proposal.
-* [@http://svn.boost.org/trac/boost/ticket/4710 #4710] Missing async().
-* Lock guards
- * [@http://svn.boost.org/trac/boost/ticket/1850 #1850] request for unlock_guard (and/or unique_unlock) to compliment lock_guard/unique_lock
- * [@http://svn.boost.org/trac/boost/ticket/3567 #3567] Request for shared_lock_guard
-* #2880 Request for Thread scheduler support for boost ..
-* #3696 Boost Thread library lacks any way to set priority of threads
-* #5956 Add optional stack_size argument to thread::start_thread()
+# Try to fix the thread specific storage issues.
[endsect]
Modified: trunk/libs/thread/doc/compliance.qbk
==============================================================================
--- trunk/libs/thread/doc/compliance.qbk (original)
+++ trunk/libs/thread/doc/compliance.qbk 2012-03-31 03:37:59 EDT (Sat, 31 Mar 2012)
@@ -5,7 +5,7 @@
http://www.boost.org/LICENSE_1_0.txt).
]
-[section:compliance Compliance with standard]
+[section:compliance Compliance and Extension]
[section:cpp11 C++11 standard Thread library]
@@ -16,60 +16,60 @@
[[30.1] [General] [-] [-] [-]]
[[30.2] [Requirements] [-] [-] [-]]
[[30.2.1] [Template parameter names] [-] [-] [-]]
- [[30.2.2] [Exceptions] [Yes] [-] [#6230]]
+ [[30.2.2] [Exceptions] [Yes] [-] [-]]
[[30.2.3] [Native handles] [Yes] [-] [-]]
- [[30.2.4] [Timing specifications] [Yes] [-] [#6195]]
- [[30.2.5] [Requirements for Lockable types] [Partial] [-] [-]]
+ [[30.2.4] [Timing specifications] [Yes] [-] [-]]
+ [[30.2.5] [Requirements for Lockable types] [Yes] [-] [-]]
[[30.2.5.1] [In general] [-] [-] [-]]
- [[30.2.5.2] [BasicLockable requirements] [No] [-] [#6231]]
+ [[30.2.5.2] [BasicLockable requirements] [Yes] [-] [-]]
[[30.2.5.3] [Lockable requirements] [yes] [-] [-]]
- [[30.2.5.4] [TimedLockable requirements] [Yes] [-] [#6195]]
+ [[30.2.5.4] [TimedLockable requirements] [Yes] [-] [-]]
[[30.2.6] [decay_copy] [-] [-] [-]]
[[30.3] [Threads] [Partial] [-] [-]]
- [[30.3.1] [Class thread] [Partial] [move,terminate] [-]]
- [[30.3.1.1] [Class thread::id] [Yes] [-] [#6224,#6272]]
- [[30.3.1.2] [thread constructors] [Partial] [move] [#6224,#6194, #6270]]
+ [[30.3.1] [Class thread] [Partial] [move,variadic,terminate] [#zzzz,#6270,#6269]]
+ [[30.3.1.1] [Class thread::id] [Yes] [-] [-]]
+ [[30.3.1.2] [thread constructors] [Partial] [move,variadic] [#zzzz,#6270]]
[[30.3.1.3] [thread destructor] [Partial] [terminate] [#6266]]
- [[30.3.1.4] [thread assignment] [Partial] [move, terminate] [#6269]]
- [[30.3.1.5] [thread members] [Yes] [-] [#6224,#6195]]
- [[30.3.1.6] [thread static members] [Yes] [-] [#6224]]
+ [[30.3.1.4] [thread assignment] [Partial] [terminate] [#6269]]
+ [[30.3.1.5] [thread members] [Yes] [-] [-]]
+ [[30.3.1.6] [thread static members] [Yes] [-] [-]]
[[30.3.1.7] [thread specialized algorithms] [Yes] [-] [-]]
- [[30.3.2] [Namespace this_thread] [Yes] [-] [#6195]]
- [[30.4] [Mutual exclusion] [Partial] [move] [-]]
+ [[30.3.2] [Namespace this_thread] [Yes] [-] [-]]
+ [[30.4] [Mutual exclusion] [Partial] [-] [-]]
[[30.4.1] [Mutex requirements] [Yes] [-] [-]]
[[30.4.1.1] [In general] [Yes] [-] [-]]
- [[30.4.1.2] [Mutex types] [Yes] [-] [#6224,#6225]]
- [[30.4.1.2.1] [Class mutex] [Yes] [-] [#6224,#6225]]
- [[30.4.1.2.2] [Class recursive_mutex] [Yes] [-] [#6224,#6225]]
- [[30.4.1.3] [Timed mutex types] [Yes] [-] [#6224,#6195,#6225]]
- [[30.4.1.3.1] [Class timed_mutex] [Yes] [-] [#6224,#6195,#6225]]
- [[30.4.1.3.1] [Class recursive_timed_mutex] [Yes] [-] [#6224,#6195,#6225]]
- [[30.4.2] [Locks] [Partial] [move] [#6224,#6195,#6225,#6227]]
- [[30.4.2.1] [Class template lock_guard] [Yes] [-] [#6225]]
- [[30.4.2.2] [Class template unique_lock] [Yes] [move] [#6224,#6195,#6225,#6227]]
- [[30.4.2.2.1] [unique_lock constructors, destructor, and assignment] [Partial] [move] [#6224,#6195,#6225,#6227]]
- [[30.4.2.2.2] [unique_lock locking] [Yes] [-] [#6195]]
+ [[30.4.1.2] [Mutex types] [Yes] [-] [-]]
+ [[30.4.1.2.1] [Class mutex] [Yes] [-] [-]]
+ [[30.4.1.2.2] [Class recursive_mutex] [Yes] [-] [-]]
+ [[30.4.1.3] [Timed mutex types] [Yes] [-] [-]]
+ [[30.4.1.3.1] [Class timed_mutex] [Yes] [-] [-]]
+ [[30.4.1.3.1] [Class recursive_timed_mutex] [Yes] [-] [-]]
+ [[30.4.2] [Locks] [Partial] [variadic] [#6227]]
+ [[30.4.2.1] [Class template lock_guard] [Yes] [-] [-]]
+ [[30.4.2.2] [Class template unique_lock] [Yes] [-] [-]]
+ [[30.4.2.2.1] [unique_lock constructors, destructor, and assignment] [Yes] [-] [-]]
+ [[30.4.2.2.2] [unique_lock locking] [Yes] [-] [-]]
[[30.4.2.2.3] [unique_lock modifiers] [Yes] [-] [-]]
- [[30.4.2.2.4] [unique_lock observers] [Yes] [] [#6227]]
+ [[30.4.2.2.4] [unique_lock observers] [Yes] [] [-]]
[[30.4.3] [Generic locking algorithms] [Partial] [variadic] [#6227]]
- [[30.4.4] [Call once] [Partial] [move,variadic,] [#6194,#7]]
- [[30.4.4.1] [Struct once_flag] [Partial] [interface] [#xx]]
- [[30.4.4.2] [Function call_once] [Partial] [move,variadic,interface] [#xx]]
- [[30.5] [Condition variables] [Partial] [notify_all_at_thread_exit] [#6195,#6273,#9]]
- [[30.5 6-10] [Function notify_all_at_thread_exit] [No] [-] [#9]]
- [[30.5.1] [Class condition_variable] [Yes] [-] [#6195,#6273]]
- [[30.5.2] [Class condition_variable_any] [Yes] [-] [#6195,#6273]]
+ [[30.4.4] [Call once] [Partial] [The interface doesn't corresponds] [#6342]]
+ [[30.4.4.1] [Struct once_flag] [Partial] [interface] [#6342]]
+ [[30.4.4.2] [Function call_once] [Partial] [interface] [#6342]]
+ [[30.5] [Condition variables] [Partial] [notify_all_at_thread_exit] [#xxxx]]
+ [[30.5 6-10] [Function notify_all_at_thread_exit] [No] [-] [#xxxx]]
+ [[30.5.1] [Class condition_variable] [Yes] [-] [-]]
+ [[30.5.2] [Class condition_variable_any] [Yes] [-] [-]]
[[30.6] [Futures] [Partial] [-] [-]]
[[30.6.1] [Overview] [Partial] [-] [-]]
- [[30.6.2] [Error handling] [No] [-] [-]]
- [[30.6.3] [Class future_error] [No] [-] [-]]
- [[30.6.4] [Shared state] [No] [-] [-]]
- [[30.6.5] [Class template promise] [Partial] [allocator,move] [#6228,#6194,#6225]]
- [[30.6.6] [Class template future] [No] [unique_future is the closest to future] [##6229,#6228]]
- [[30.6.7] [Class template shared_future] [Partial] [allocator,move] [#6228,#6194,#6225]]
+ [[30.6.2] [Error handling] [Yes] [-] [-]]
+ [[30.6.3] [Class future_error] [Yes] [-] [-]]
+ [[30.6.4] [Shared state] [-] [-] [-]]
+ [[30.6.5] [Class template promise] [Partial] [allocator] [#6228]]
+ [[30.6.6] [Class template future] [Partial] [allocator,unique_future is the closest to future, renamed in V2] [#6228]]
+ [[30.6.7] [Class template shared_future] [Partial] [allocator] [#6228]]
[[30.6.8] [Function template async] [No] [async] [#4710]]
- [[30.6.8] [Class template packaged_task] [Partial] [move] [#6194]]
+ [[30.6.8] [Class template packaged_task] [Partial] [move] [#yyyy]]
]
[/
@@ -86,16 +86,25 @@
]
[endsect]
-[/
-[section:shared Shared Mutex library extension]
-[table Clock Requirements
- [[Section] [Description] [Status] [Comments]]
- [[XXXX] [DDDD] [SSSS] [CCCC]]
- [[XXXX] [DDDD] [SSSS] [CCCC]]
+[section:shared Shared Locking extensions]
+
+[table Compliance with Howard's Shared Locking proposal
+ [[Section] [Description] [Status] [Comments]]
+ [[X] [Shared Locking] [Partial] [Missing some upwards conversions]]
+ [[X.1] [Shared Lockables Concepts] [Partial] [ - ]]
+ [[X.1.1] [SharedLockable concept] [Yes] [ Missing some upwards ownership conversions ]]
+ [[X.1.2] [UpgradeLockable concept] [Yes] [ Missing some upwards ownership conversions ]]
+ [[X.2] [Shared Mutex Types] [Yes] [ - ]]
+ [[X.2.1] [shared_mutex class] [Partial] [ Missing some upwards ownership conversions ]]
+ [[X.2.2] [upgrade_mutex class] [Partial] [ Missing some upwards ownership conversions ]]
+ [[X.3] [Locks] [Partial] [Missing some timed conversions]]
+ [[X.3.1] [unique_lock class adaptations] [Partial] [Missing some upwards conversions]]
+ [[X.3.2] [shared_lock class] [Yes] [ - ]]
+ [[X.3.3] [upgrade_lock class] [Partial] [Missing some upwards conversions]]
]
[endsect]
-]
+
[endsect]
Added: trunk/libs/thread/doc/emulations.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/thread/doc/emulations.qbk 2012-03-31 03:37:59 EDT (Sat, 31 Mar 2012)
@@ -0,0 +1,268 @@
+[/
+ (C) Copyright 20012 Vicente J. Botet Escriba.
+ Distributed under the Boost Software License, Version 1.0.
+ (See accompanying file LICENSE_1_0.txt or copy at
+ http://www.boost.org/LICENSE_1_0.txt).
+]
+
+
+[section:emulations Emulations]
+[section:delete `=delete` emulation]
+
+C++11 allows to delete some implicitly generated functions as constructors and assignment using '= delete' as in
+
+ public:
+ thread(thread const&) = delete;
+
+On compilers not supporting this feature, Boost.Thread relays on a partial simulation, it declares the function as private without definition.
+
+ private:
+ thread(thread &);
+
+The emulation is partial as the private function can be used for overload resolution for some compilers and prefer it to other overloads that need a conversion. See below the consequences on the move semantic emulation.
+
+[endsect]
+
+[section:move Move semantics]
+
+In order to implement MovableOnly classes and move parameters and return types Boost.Thread uses the rvalue reference when the compiler support it.
+On compilers not supporting it Boost.Thread uses the emulation provided by Boost.Move.
+
+
+While Boost.Move is the best C++03 move emulation there are some limitations that impact the way the library can be used.
+For example, with the following declarations
+
+ class thread {
+ // ...
+ private:
+ thread(thread &);
+ public:
+ thread(rv<thread>&);
+ // ...
+ };
+
+This could not work on these compilers even if thread is convertible to rv<thread>
+
+ thread mkth()
+ {
+ return thread(f);
+ }
+
+On these compilers we need to use instead an explicit conversion. The library provides a move member function that allows to workaround the issue.
+
+ thread mkth()
+ {
+ return thread(f).move();
+ }
+
+Note that ::boost::move can not be used in this case as thread is not implicitly convertible to thread&.
+
+ thread mkth()
+ {
+ return ::boost::move(thread(f));
+ }
+
+To make the code portable Boost.Thread uses a macro BOOST_MOVE_RVALUE that can be used as in
+
+ thread mkth()
+ {
+ return BOOST_EXPLICIT_MOVE(thread(f));
+ }
+
+See the Boost.Move documentation for a complete description on how to declare new Movable classes and its limitations.
+
+[section:deprecated Deprecated]
+
+Previous to version 1.50, Boost.Thread make use of its own move semantic emulation which had more limitations than the provided by Boost.Move. In addition, it is of interest of the whole Boost community that Boost.Thread uses Boost.Move so that boost::thread can be stored on Movable aware containers.
+
+To preserve backward compatibility at least during some releases, Boost.Thread allows the user to use the deprecated move semantic emulation defining BOOST_THREAD_DONT_USE_MOVE.
+
+Many aspects of move semantics can be emulated for compilers not supporting rvalue references and Boost.Thread legacy offers tools for that purpose.
+
+[section:Helper Helpers class and function]
+
+Next follows the interface of the legacy move semantic helper classes and functions.
+
+ namespace boost
+ {
+ namespace detail
+ {
+ template<typename T>
+ struct thread_move_t
+ {
+ explicit thread_move_t(T& t_);
+ T& operator*() const;
+ T* operator->() const;
+ private:
+ void operator=(thread_move_t&);
+ };
+ }
+ template<typename T>
+ boost::detail::thread_move_t<T> move(boost::detail::thread_move_t<T> t);
+ }
+
+[section:movable Movable emulation]
+
+We can write a MovableOny class as follows. You just need to follow these simple steps:
+
+* Add a conversion to the detail::thread_move_t<classname>
+* Make the copy constructor private.
+* Write a constructor taking the parameter as detail::thread_move_t<classname>
+* Write an assignment taking the parameter as detail::thread_move_t<classname>
+
+
+For example the thread class defines the following:
+
+ class thread
+ {
+ // ...
+ private:
+ thread(thread&);
+ thread& operator=(thread&);
+ public:
+ detail::thread_move_t<thread> move()
+ {
+ detail::thread_move_t<thread> x(*this);
+ return x;
+ }
+ operator detail::thread_move_t<thread>()
+ {
+ return move();
+ }
+ thread(detail::thread_move_t<thread> x)
+ {
+ thread_info=x->thread_info;
+ x->thread_info.reset();
+ }
+ thread& operator=(detail::thread_move_t<thread> x)
+ {
+ thread new_thread(x);
+ swap(new_thread);
+ return *this;
+ }
+ // ...
+
+ };
+
+
+
+[endsect]
+
+[endsect]
+
+[endsect]
+
+
+[endsect]
+
+[section:bool_explicit_conversion Bool explicit conversion]
+
+Locks provide an explicit bool conversion operator when the compiler provides them.
+
+ explicit operator bool() const;
+
+The library provides un implicit conversion to an undefined type that can be used as a conditional expression.
+
+ #if defined(BOOST_NO_EXPLICIT_CONVERSION_OPERATORS)
+ operator ``['unspecified-bool-type]``() const;
+ bool operator!() const;
+ #else
+ explicit operator bool() const;
+ #endif
+
+The user should use the lock.owns_lock() when a explicit conversion is required.
+
+[section:bool_conversion `operator `['unspecified-bool-type]`() const`]
+
+[variablelist
+
+[[Returns:] [If __owns_lock_ref__ would return `true`, a value that evaluates to
+`true` in boolean contexts, otherwise a value that evaluates to `false` in
+boolean contexts.]]
+
+[[Throws:] [Nothing.]]
+
+]
+
+[endsect]
+
+
+[section:operator_not `bool operator!() const`]
+
+[variablelist
+
+[[Returns:] [`!` __owns_lock_ref__.]]
+
+[[Throws:] [Nothing.]]
+
+]
+
+[endsect]
+
+
+[endsect]
+
+[section:scoped_enums Scoped Enums]
+
+Some of the enumerations defined in the standard library are scoped enums.
+
+On compilers that don't support them, the library uses a class to wrap the underlying type. Instead of
+
+ enum class future_errc
+ {
+ broken_promise,
+ future_already_retrieved,
+ promise_already_satisfied,
+ no_state
+ };
+
+the library declare these types as
+
+ BOOST_SCOPED_ENUM_DECLARE_BEGIN(future_errc)
+ {
+ broken_promise,
+ future_already_retrieved,
+ promise_already_satisfied,
+ no_state
+ }
+ BOOST_SCOPED_ENUM_DECLARE_END(future_errc)
+
+These macros allows to use 'future_errc' in almost all the cases as an scoped enum.
+
+There are however some limitations:
+
+* The type is not a C++ enum, so 'is_enum<future_errc>' will be false_type.
+* The emulated scoped enum can not be used in switch nor in template arguments. For these cases the user needs to use some macros.
+
+Instead of
+
+ switch (ev)
+ {
+ case future_errc::broken_promise:
+ // ...
+
+use
+
+ switch (BOOST_SCOPED_ENUM_NATIVE(future_errc)(ev))
+ {
+ case future_errc::broken_promise:
+
+And instead of
+
+ #ifdef BOOST_NO_SCOPED_ENUMS
+ template <>
+ struct BOOST_SYMBOL_VISIBLE is_error_code_enum<future_errc> : public true_type { };
+ #endif
+
+use
+
+ #ifdef BOOST_NO_SCOPED_ENUMS
+ template <>
+ struct BOOST_SYMBOL_VISIBLE is_error_code_enum<future_errc::enum_type> : public true_type { };
+ #endif
+
+
+
+[endsect]
+
+[endsect]
\ No newline at end of file
Modified: trunk/libs/thread/doc/future_ref.qbk
==============================================================================
--- trunk/libs/thread/doc/future_ref.qbk (original)
+++ trunk/libs/thread/doc/future_ref.qbk 2012-03-31 03:37:59 EDT (Sat, 31 Mar 2012)
@@ -7,13 +7,152 @@
[section:reference Futures Reference]
-[section:future_state `state` enum]
+ //#include <boost/thread/futures.hpp>
+
+ namespace boost
+ {
+ namespace future_state // DEPRECATED V2
+ {
+ enum state {uninitialized, waiting, ready, moved};
+ }
+
+ enum class future_errc
+ {
+ broken_promise,
+ future_already_retrieved,
+ promise_already_satisfied,
+ no_state
+ };
+
+ namespace system
+ {
+ template <>
+ struct is_error_code_enum<future_errc> : public true_type {};
+
+ error_code make_error_code(future_errc e);
+
+ error_condition make_error_condition(future_errc e);
+ }
+
+ const system::error_category& future_category();
+
+ class future_error;
+
+ template <typename R>
+ class promise;
+
+ template <typename R>
+ void swap(promise<R>& x, promise<R>& y) noexcept;
+
+ //template <class R, class Alloc>
+ //struct uses_allocator<promise<R>, Alloc>; // NOT YET IMPLEMENTED
+
+ template <typename R>
+ class future;
+
+ template <typename R>
+ class shared_future;
+
+ template <typename R>
+ class packaged_task;
+ template <class R> void swap(packaged_task<R>&, packaged_task<R>&) noexcept;
+
+ //template <class R, class Alloc>
+ //struct uses_allocator<packaged_task <R>, Alloc>; // NOT YET IMPLEMENTED
+
+ // template <class F, class... Args>
+ // future<typename result_of<typename decay<F>::type(typename decay<Args>::type...)>::type>
+ // async(F&& f, Args&&... args); // NOT YET IMPLEMENTED
+ // template <class F, class... Args>
+ // future<typename result_of<typename decay<F>::type(typename decay<Args>::type...)>::type>
+ // async(launch policy, F&& f, Args&&... args); // NOT YET IMPLEMENTED
+
+
+ template<typename Iterator>
+ void wait_for_all(Iterator begin,Iterator end); // EXTENSION
+
+ template<typename F1,typename... FS>
+ void wait_for_all(F1& f1,Fs&... fs); // EXTENSION
+
+ template<typename Iterator>
+ Iterator wait_for_any(Iterator begin,Iterator end);
+
+ template<typename F1,typename... Fs>
+ unsigned wait_for_any(F1& f1,Fs&... fs);
+
+
+[section:future_state Enumeration `state` DEPRECATED V2]
namespace future_state
{
- enum state {uninitialized, waiting, ready};
+ enum state {uninitialized, waiting, ready, moved};
}
+
+[endsect]
+
+
+[section:future_errc Enumeration `future_errc `]
+
+ enum class future_errc
+ {
+ broken_promise,
+ future_already_retrieved,
+ promise_already_satisfied,
+ no_state
+ }
+
+[endsect]
+[section:is_error_code_enum Specialization `is_error_code_enum<future_errc>`]
+
+ namespace system
+ {
+ template <>
+ struct is_error_code_enum<future_errc> : public true_type {};
+
+ }
+
+[endsect]
+[section:make_error_code Non-member function `make_error_code()`]
+
+ namespace system
+ {
+ error_code make_error_code(future_errc e);
+ }
+
+[endsect]
+[section:make_error_condition Non-member function `make_error_condition()`]
+
+ namespace system
+ {
+ error_condition make_error_condition(future_errc e);
+ }
+
+[endsect]
+[section:future_category Non-member function `future_category()`]
+
+ const system::error_category& future_category();
+
+[endsect]
+[section:future_error Class `future_error`]
+
+ class future_error
+ : public std::logic_error
+ {
+ public:
+ future_error(system::error_code ec);
+
+ const system::error_code& code() const no_except;
+ };
+
+[endsect]
+
+[section:future_status Enumeration `future_status`]
+
+ enum class future_status {
+ ready, timeout, deferred
+ };
+
[endsect]
[section:unique_future `unique_future` class template]
@@ -21,35 +160,44 @@
template <typename R>
class unique_future
{
+
+ public:
unique_future(unique_future & rhs);// = delete;
unique_future& operator=(unique_future& rhs);// = delete;
- public:
- typedef future_state::state state;
+ typedef future_state::state state; // DEPRECATED V2
- unique_future();
+ unique_future() noexcept;
~unique_future();
// move support
- unique_future(unique_future && other);
- unique_future& operator=(unique_future && other);
+ unique_future(unique_future && other) noexcept;
+ unique_future& operator=(unique_future && other) noexcept;
+ shared_future<R> share();
- void swap(unique_future& other);
+ void swap(unique_future& other) noexcept; // EXTENSION
// retrieving the value
R&& get();
// functions to check state
- state get_state() const;
- bool is_ready() const;
- bool has_exception() const;
- bool has_value() const;
+ state get_state() const; //DEPRECATED V2
+ bool valid() const;
+ bool is_ready() const; // EXTENSION
+ bool has_exception() const; // EXTENSION
+ bool has_value() const; // EXTENSION
// waiting for the result to be ready
- void wait() const;
+ void wait() const;
+ template <class Rep, class Period>
+ future_status wait_for(const chrono::duration<Rep, Period>& rel_time) const;
+ template <class Clock, class Duration>
+ future_status wait_until(const chrono::time_point<Clock, Duration>& abs_time) const;
+
template<typename Duration>
- bool timed_wait(Duration const& rel_time) const;
- bool timed_wait_until(boost::system_time const& abs_time) const;
+ bool timed_wait(Duration const& rel_time) const; // DEPRECATED V2
+ bool timed_wait_until(boost::system_time const& abs_time) const; // DEPRECATED V2
+
};
[section:default_constructor Default Constructor]
@@ -126,7 +274,7 @@
[section:swap Member function `swap()`]
- void swap(unique_future & other);
+ void swap(unique_future & other) no_except;
[variablelist
@@ -193,7 +341,7 @@
[endsect]
-[section:timed_wait_duration Member function `timed_wait()`]
+[section:timed_wait_duration Member function `timed_wait()` DEPRECATED V2]
template<typename Duration>
bool timed_wait(Duration const& wait_duration);
@@ -220,7 +368,7 @@
[endsect]
-[section:timed_wait_absolute Member function `timed_wait()`]
+[section:timed_wait_absolute Member function `timed_wait()` DEPRECATED V2]
bool timed_wait(boost::system_time const& wait_timeout);
@@ -247,7 +395,7 @@
[endsect]
-[section:is_ready Member function `is_ready()`]
+[section:is_ready Member function `is_ready()` EXTENSION]
bool is_ready();
@@ -264,7 +412,7 @@
[endsect]
-[section:has_value Member function `has_value()`]
+[section:has_value Member function `has_value()` EXTENSION]
bool has_value();
@@ -281,7 +429,7 @@
[endsect]
-[section:has_exception Member function `has_exception()`]
+[section:has_exception Member function `has_exception()` EXTENSION]
bool has_exception();
@@ -298,7 +446,7 @@
[endsect]
-[section:get_state Member function `get_state()`]
+[section:get_state Member function `get_state()` DEPRECATED V2]
future_state::state get_state();
@@ -324,9 +472,9 @@
class shared_future
{
public:
- typedef future_state::state state;
+ typedef future_state::state state; // EXTENSION
- shared_future();
+ shared_future() noexcept;
~shared_future();
// copy support
@@ -334,10 +482,10 @@
shared_future& operator=(shared_future const& other);
// move support
- shared_future(shared_future && other);
- shared_future(unique_future<R> && other);
- shared_future& operator=(shared_future && other);
- shared_future& operator=(unique_future<R> && other);
+ shared_future(shared_future && other) noexcept;
+ shared_future(unique_future<R> && other) noexcept;
+ shared_future& operator=(shared_future && other) noexcept;
+ shared_future& operator=(unique_future<R> && other) noexcept;
void swap(shared_future& other);
@@ -345,16 +493,22 @@
R get();
// functions to check state, and wait for ready
- state get_state() const;
- bool is_ready() const;
- bool has_exception() const;
- bool has_value() const;
+ state get_state() const noexcept; // DEPRECATED V2
+ bool valid() const noexcept;
+ bool is_ready() const noexcept; // EXTENSION
+ bool has_exception() const noexcept; // EXTENSION
+ bool has_value() const noexcept; // EXTENSION
// waiting for the result to be ready
void wait() const;
+ template <class Rep, class Period>
+ future_status wait_for(const chrono::duration<Rep, Period>& rel_time) const;
+ template <class Clock, class Duration>
+ future_status wait_until(const chrono::time_point<Clock, Duration>& abs_time) const;
+
template<typename Duration>
- bool timed_wait(Duration const& rel_time) const;
- bool timed_wait_until(boost::system_time const& abs_time) const;
+ bool timed_wait(Duration const& rel_time) const; // DEPRECATED V2
+ bool timed_wait_until(boost::system_time const& abs_time) const; // DEPRECATED V2
};
[section:default_constructor Default Constructor]
@@ -417,7 +571,7 @@
[endsect]
-[section:timed_wait_duration Member function `timed_wait()`]
+[section:timed_wait_duration Member function `timed_wait()` DEPRECATED V2]
template<typename Duration>
bool timed_wait(Duration const& wait_duration);
@@ -444,7 +598,7 @@
[endsect]
-[section:timed_wait_absolute Member function `timed_wait()`]
+[section:timed_wait_absolute Member function `timed_wait()` DEPRECATED V2]
bool timed_wait(boost::system_time const& wait_timeout);
@@ -470,7 +624,7 @@
[endsect]
-[section:is_ready Member function `is_ready()`]
+[section:is_ready Member function `is_ready()` EXTENSION]
bool is_ready();
@@ -487,7 +641,7 @@
[endsect]
-[section:has_value Member function `has_value()`]
+[section:has_value Member function `has_value()` EXTENSION]
bool has_value();
@@ -504,7 +658,7 @@
[endsect]
-[section:has_exception Member function `has_exception()`]
+[section:has_exception Member function `has_exception()` EXTENSION]
bool has_exception();
@@ -521,7 +675,7 @@
[endsect]
-[section:get_state Member function `get_state()`]
+[section:get_state Member function `get_state()` DEPRECATED V2]
future_state::state get_state();
@@ -546,19 +700,19 @@
template <typename R>
class promise
{
- promise(promise & rhs);// = delete;
- promise & operator=(promise & rhs);// = delete;
public:
- // template <class Allocator> explicit promise(Allocator a);
promise();
+ // template <class Allocator> explicit promise(Allocator a); // NOT YET IMPLEMENTED
+ promise & operator=(const promise & rhs);// = delete;
+ promise(const promise & rhs);// = delete;
~promise();
// Move support
- promise(promise && rhs);
- promise & operator=(promise&& rhs);
+ promise(promise && rhs) noexcept;;
+ promise & operator=(promise&& rhs) noexcept;;
- void swap(promise& other);
+ void swap(promise& other) noexcept;
// Result retrieval
unique_future<R> get_future();
@@ -567,8 +721,13 @@
void set_value(R&& r);
void set_exception(boost::exception_ptr e);
+ // setting the result with deferred notification
+ // void set_value_at_thread_exit(const R& r); // NOT YET IMPLEMENTED
+ // void set_value_at_thread_exit(see below); // NOT YET IMPLEMENTED
+ // void set_exception_at_thread_exit(exception_ptr p); // NOT YET IMPLEMENTED
+
template<typename F>
- void set_wait_callback(F f);
+ void set_wait_callback(F f); // EXTENSION
};
[section:default_constructor Default Constructor]
@@ -718,14 +877,18 @@
[section:packaged_task `packaged_task` class template]
- template<typename R>
+ template<typename R
+ // , class... ArgTypes // NOT YET IMPLEMENTED
+ >
class packaged_task
{
+ public:
packaged_task(packaged_task&);// = delete;
packaged_task& operator=(packaged_task&);// = delete;
-
- public:
+
// construction and destruction
+ packaged_task() noexcept;
+
template <class F>
explicit packaged_task(F const& f);
@@ -735,24 +898,27 @@
explicit packaged_task(F&& f);
// template <class F, class Allocator>
- // explicit packaged_task(F const& f, Allocator a);
- // template <class F, class Allocator>
- // explicit packaged_task(F&& f, Allocator a);
+ // explicit packaged_task(allocator_arg_t, Allocator a, F&& f); // NOT YET IMPLEMENTED
~packaged_task()
{}
// move support
- packaged_task(packaged_task&& other);
- packaged_task& operator=(packaged_task&& other);
+ packaged_task(packaged_task&& other) noexcept;
+ packaged_task& operator=(packaged_task&& other) noexcept;
+
+ void swap(packaged_task& other) noexcept;
- void swap(packaged_task& other);
+ bool valid() const noexcept;
// result retrieval
unique_future<R> get_future();
// execution
void operator()();
+ // void operator()(ArgTypes... ); // NOT YET IMPLEMENTED
+ // void make_ready_at_thread_exit(ArgTypes...); // NOT YET IMPLEMENTED
+ // void reset(); // NOT YET IMPLEMENTED
template<typename F>
void set_wait_callback(F f);
};
Modified: trunk/libs/thread/doc/mutex_concepts.qbk
==============================================================================
--- trunk/libs/thread/doc/mutex_concepts.qbk (original)
+++ trunk/libs/thread/doc/mutex_concepts.qbk 2012-03-31 03:37:59 EDT (Sat, 31 Mar 2012)
@@ -18,24 +18,25 @@
__shared_lockable_concept_type__ and __upgrade_lockable_concept_type__. Each mutex type implements one or more of these concepts, as
do the various lock types.
-[section:lockable `Lockable` Concept]
+[section:basic_lockable `BasicLockable` Concept]
-The __lockable_concept__ models exclusive ownership. A type that implements the __lockable_concept__ shall provide the following
-member functions:
+The __BasicLockable concept models exclusive ownership.
+A type `L` meets the __BasicLockable requiremets if the following expressions are well-formed and have the specified semantics (`m` denotes a value of type `L`):
-* [lock_ref_link `void lock();`]
-* [try_lock_ref_link `bool try_lock();`]
-* [unlock_ref_link `void unlock();`]
+* `m.__lock();`
+* `m.__unlock();`
-Lock ownership acquired through a call to __lock_ref__ or __try_lock_ref__ must be released through a call to __unlock_ref__.
+Lock ownership acquired through a call to __lock_ref__ must be released through a call to __unlock_ref__.
-[section:lock `void lock()`]
+[section:lock `m.lock();`]
[variablelist
[[Effects:] [The current thread blocks until ownership can be obtained for the current thread.]]
-[[Postcondition:] [The current thread owns `*this`.]]
+[[Postcondition:] [The current thread owns `m`.]]
+
+[[Return type:] [`void`.]]
[[Throws:] [__thread_resource_error__ if an error occurs.]]
@@ -49,37 +50,54 @@
]]
+[[Thread safety:] [If an exception is thrown then a lock shall not have been acquired for the current thread.]]
+
]
[endsect]
-[section:try_lock `bool try_lock()`]
+[section:unlock `m.unlock();`]
[variablelist
-[[Effects:] [Attempt to obtain ownership for the current thread without blocking.]]
+[[Precondition:] [The current thread owns `m`.]]
-[[Returns:] [`true` if ownership was obtained for the current thread, `false` otherwise.]]
+[[Effects:] [Releases ownership by the current thread.]]
-[[Postcondition:] [If the call returns `true`, the current thread owns the `*this`.]]
+[[Return type:] [`void`.]]
-[[Throws:] [Nothing.]]
+[[Postcondition:] [The current thread no longer owns `m`.]]
+[[Throws:] [Nothing.]]
]
[endsect]
-[section:unlock `void unlock()`]
+
+[endsect]
+[section:lockable `Lockable` Concept]
+
+A type `L` meets the __Lockable requirements if it meets the __BasicLocable requirements and the following expressions are well-formed and have the specified semantics (`m` denotes a value of type `L`):
+
+* `m.__try_lock()`
+
+Lock ownership acquired through a call to __try_lock_ref__ must be released through a call to __unlock_ref__.
+
+[section:try_lock `m.try_lock()`]
[variablelist
-[[Precondition:] [The current thread owns `*this`.]]
+[[Effects:] [Attempt to obtain ownership for the current thread without blocking.]]
-[[Effects:] [Releases ownership by the current thread.]]
+[[Return type:] [`bool`.]]
-[[Postcondition:] [The current thread no longer owns `*this`.]]
+[[Returns:] [`true` if ownership was obtained for the current thread, `false` otherwise.]]
+
+[[Postcondition:] [If the call returns `true`, the current thread owns the `m`.]]
[[Throws:] [Nothing.]]
+
]
[endsect]
+
[endsect]
[section:timed_lockable `TimedLockable` Concept]
@@ -87,21 +105,22 @@
The __timed_lockable_concept__ refines the __lockable_concept__ to add support for
timeouts when trying to acquire the lock.
-A type that implements the __timed_lockable_concept__ shall meet the requirements
-of the __lockable_concept__. In addition, the following member functions must be
-provided:
+A type `L` meets the __TimedLockable requirements if it meets the __Lockable requirements and the following expressions are well-formed and have the specified semantics.
-* [timed_lock_ref_link `bool timed_lock(boost::system_time const& abs_time);` DEPRECATED V2]
-* [timed_lock_duration_ref_link `template<typename DurationType> bool timed_lock(DurationType const& rel_time);` DEPRECATED V2]
+[*Variables:]
- template <class Rep, class Period>
- bool try_lock_for(const chrono::duration<Rep, Period>& rel_time);
- template <class Clock, class Duration>
- bool try_lock_until(const chrono::time_point<Clock, Duration>& t);
+* `m` denotes a value of type `L`,
+* `rel_time` denotes a value of an instantiation of `chrono::duration`, and
+* `abs_time` denotes a value of an instantiation of `chrono::time_point`:
-Lock ownership acquired through a call to __timed_lock_ref__, __try_lock_for or __try_lock_until must be released through a call to __unlock_ref__.
+[*Expressions:]
-[section:timed_lock `bool timed_lock(boost::system_time const& abs_time)` DEPRECATED V2]
+* `m.__try_lock_for(rel_time)`
+* `m.__try_lock_until(abs_time)`
+
+Lock ownership acquired through a call to __try_lock_for or __try_lock_until must be released through a call to __unlock.
+
+[section:try_lock_until `m.try_lock_until(abs_time)`]
[variablelist
@@ -110,24 +129,38 @@
[[Returns:] [`true` if ownership was obtained for the current thread, `false` otherwise.]]
-[[Postcondition:] [If the call returns `true`, the current thread owns `*this`.]]
+[[Postcondition:] [If the call returns `true`, the current thread owns `m`.]]
-[[Throws:] [__thread_resource_error__ if an error occurs.]]
+[[Throws:] [Nothing.]]
]
[endsect]
-[section:timed_lock_duration `template<typename DurationType> bool
-timed_lock(DurationType const& rel_time)` DEPRECATED V2]
+[section:try_lock_for `m.try_lock_for(rel_time)`]
[variablelist
-[[Effects:] [As-if [timed_lock_ref_link
-`timed_lock(boost::get_system_time()+rel_time)`].]]
+[[Effects:] [As-if `__try_lock_until(chrono::steady_clock::now() + rel_time)`.]]
]
[endsect]
-[section:try_lock_until `template <class Clock, class Duration> bool try_lock_until(const chrono::time_point<Clock, Duration>& abs_time)`]
+[heading Deprecated V2]
+
+The following expressions were required on version 1, but are now deprecated.
+
+[*Variables:]
+
+* `rel_time` denotes a value of an instantiation of an unspecified `DurationType` arithmetic compatible with `boost::system_time`, and
+* `abs_time` denotes a value of an instantiation of `boost::system_time`:
+
+[*Expressions:]
+
+* `m.__timed_lock_duration(rel_time)` DEPRECATED V2
+* `m.__timed_lock(abs_time)` DEPRECATED V2
+
+Lock ownership acquired through a call to __timed_lock_ref__ must be released through a call to __unlock_ref__.
+
+[section:timed_lock `m.timed_lock(abs_time)` DEPRECATED V2]
[variablelist
@@ -136,18 +169,18 @@
[[Returns:] [`true` if ownership was obtained for the current thread, `false` otherwise.]]
-[[Postcondition:] [If the call returns `true`, the current thread owns `*this`.]]
+[[Postcondition:] [If the call returns `true`, the current thread owns `m`.]]
-[[Throws:] [Nothing.]]
+[[Throws:] [__thread_resource_error__ if an error occurs.]]
]
[endsect]
-[section:try_lock_for `template <class Rep, class Period> bool
-try_lock_for(const chrono::duration<Rep, Period>& rel_time)`]
+[section:timed_lock_duration `m.timed_lock(rel_time)` DEPRECATED V2]
[variablelist
-[[Effects:] [As-if `__try_lock_until(chrono::steady_clock::now() + rel_time)`.]]
+[[Effects:] [As-if [timed_lock_ref_link
+`timed_lock(boost::get_system_time()+rel_time)`].]]
]
[endsect]
@@ -164,32 +197,38 @@
can have shared or exclusive ownership. Alternatively, many threads may have
shared ownership.
-For a type to implement the __shared_lockable_concept__, as well as meeting the
-requirements of the __timed_lockable_concept__, it must also provide the following
-member functions:
-
-* [lock_shared_ref_link `void lock_shared();`]
-* [try_lock_shared_ref_link `bool try_lock_shared();`]
-* [unlock_shared_ref_link `bool unlock_shared();`]
-* [timed_lock_shared_ref_link `bool timed_lock_shared(boost::system_time const& abs_time);`]
+A type `L` meets the __SharedLockable requirements if it meets the __TimedLockable requirements and the following expressions are well-formed and have the specified semantics.
+
+[*Variables:]
+
+* `m` denotes a value of type `L`,
+* `rel_time` denotes a value of an instantiation of `chrono::duration`, and
+* `abs_time` denotes a value of an instantiation of `chrono::time_point`:
-Lock ownership acquired through a call to __lock_shared_ref__, __try_lock_shared_ref__ or __timed_lock_shared_ref__ must be released
-through a call to __unlock_shared_ref__.
+[*Expressions:]
-[section:lock_shared `void lock_shared()`]
+* `m.__lock_shared();`
+* `m.__try_lock_shared()`
+* `m.__try_lock_shared_for(rel_time)`
+* `m.__try_lock_shared_until(abs_time)`
+* `m.__unlock_shared();`
+
+Lock ownership acquired through a call to __lock_shared_ref__, __try_lock_shared_ref__, __try_lock_shared_for or __try_lock_shared_until must be released through a call to __unlock_shared_ref__.
+
+[section:lock_shared `m.lock_shared()`]
[variablelist
[[Effects:] [The current thread blocks until shared ownership can be obtained for the current thread.]]
-[[Postcondition:] [The current thread has shared ownership of `*this`.]]
+[[Postcondition:] [The current thread has shared ownership of `m`.]]
[[Throws:] [__thread_resource_error__ if an error occurs.]]
]
[endsect]
-[section:try_lock_shared `bool try_lock_shared()`]
+[section:try_lock_shared `m.try_lock_shared()`]
[variablelist
@@ -197,14 +236,31 @@
[[Returns:] [`true` if shared ownership was obtained for the current thread, `false` otherwise.]]
-[[Postcondition:] [If the call returns `true`, the current thread has shared ownership of `*this`.]]
+[[Postcondition:] [If the call returns `true`, the current thread has shared ownership of `m`.]]
+
+[[Throws:] [__thread_resource_error__ if an error occurs.]]
+
+]
+[endsect]
+
+[section:try_lock_shared_for `m.try_lock_shared_for(rel_time)`]
+
+[variablelist
+
+[[Effects:] [Attempt to obtain shared ownership for the current thread. Blocks until shared ownership can be obtained, or the
+specified duration is elapsed. If the specified duration is already elapsed, behaves as __try_lock_shared_ref__.]]
+
+[[Returns:] [`true` if shared ownership was acquired for the current thread, `false` otherwise.]]
+
+[[Postcondition:] [If the call returns `true`, the current thread has shared
+ownership of `m`.]]
[[Throws:] [__thread_resource_error__ if an error occurs.]]
]
[endsect]
-[section:timed_lock_shared `bool timed_lock_shared(boost::system_time const& abs_time)`]
+[section:try_lock_shared_until `m.try_lock_shared_until(abs_time))`]
[variablelist
@@ -214,28 +270,60 @@
[[Returns:] [`true` if shared ownership was acquired for the current thread, `false` otherwise.]]
[[Postcondition:] [If the call returns `true`, the current thread has shared
-ownership of `*this`.]]
+ownership of `m`.]]
[[Throws:] [__thread_resource_error__ if an error occurs.]]
]
[endsect]
-[section:unlock_shared `void unlock_shared()`]
+[section:unlock_shared `m.unlock_shared()`]
[variablelist
-[[Precondition:] [The current thread has shared ownership of `*this`.]]
+[[Precondition:] [The current thread has shared ownership of `m`.]]
-[[Effects:] [Releases shared ownership of `*this` by the current thread.]]
+[[Effects:] [Releases shared ownership of `m` by the current thread.]]
-[[Postcondition:] [The current thread no longer has shared ownership of `*this`.]]
+[[Postcondition:] [The current thread no longer has shared ownership of `m`.]]
[[Throws:] [Nothing]]
]
[endsect]
+[heading Deprecated V2]
+
+The following expressions were required on version 1, but are now deprecated.
+
+[*Variables:]
+
+* `abs_time` denotes a value of an instantiation of `boost::system_time`:
+
+[*Expressions:]
+
+* `m.timed_lock_shared(abs_time);` DEPRECATED V2
+
+Lock ownership acquired through a call to __timed_lock_shared_ref__ must be released through a call to __unlock_shared_ref__.
+
+[section:timed_lock_shared `m.timed_lock_shared(abs_time)` DEPRECATED V2]
+
+[variablelist
+
+[[Effects:] [Attempt to obtain shared ownership for the current thread. Blocks until shared ownership can be obtained, or the
+specified time is reached. If the specified time has already passed, behaves as __try_lock_shared_ref__.]]
+
+[[Returns:] [`true` if shared ownership was acquired for the current thread, `false` otherwise.]]
+
+[[Postcondition:] [If the call returns `true`, the current thread has shared
+ownership of `m`.]]
+
+[[Throws:] [__thread_resource_error__ if an error occurs.]]
+
+]
+[endsect]
+
+
[endsect]
@@ -255,91 +343,411 @@
__upgrade_lockable_concept__ can be downgraded to upgradable ownership or shared ownership, and upgradable ownership can be
downgraded to plain shared ownership.
-For a type to implement the __upgrade_lockable_concept__, as well as meeting the
-requirements of the __shared_lockable_concept__, it must also provide the following
-member functions:
-
-* [lock_upgrade_ref_link `void lock_upgrade();`]
-* [unlock_upgrade_ref_link `bool unlock_upgrade();`]
-* [unlock_upgrade_and_lock_ref_link `void unlock_upgrade_and_lock();`]
-* [unlock_and_lock_upgrade_ref_link `void unlock_and_lock_upgrade();`]
-* [unlock_upgrade_and_lock_shared_ref_link `void unlock_upgrade_and_lock_shared();`]
+A type `L` meets the __SharedLockable requirements if it meets the __TimedLockable requirements and the following expressions are well-formed and have the specified semantics.
+
+[*Variables:]
+
+* `m` denotes a value of type `L`,
+* `rel_time` denotes a value of an instantiation of `chrono::duration`, and
+* `abs_time` denotes a value of an instantiation of `chrono::time_point`:
+
+[*Expressions:]
+
+* `m.__lock_upgrade();`
+* `m.__unlock_upgrade()`
+* `m.__try_lock_upgrade()`
+* `m.__try_lock_upgrade_for(rel_time)`
+* `m.__try_lock_upgrade_until(abs_time)`
+* `m.__try_unlock_shared_and_lock()`
+* `m.__try_unlock_shared_and_lock_for(rel_time)`
+* `m.__try_unlock_shared_and_lock_until(abs_time)`
+* `m.__unlock_and_lock_shared()`
+* `m.__try_unlock_shared_and_lock_upgrade();`
+* `m.__try_unlock_shared_and_lock_upgrade_for(rel_time);`
+* `m.__try_unlock_shared_and_lock_upgrade_until(abs_time);`
+* `m.__unlock_and_lock_upgrade();`
+* `m.__unlock_upgrade_and_lock();`]
+* `m.__try_unlock_upgrade_and_lock()`
+* `m.__try_unlock_upgrade_and_lock_for(rel_time)`
+* `m.__try_unlock_upgrade_and_lock_until(abs_time)`
+* `m.__unlock_upgrade_and_lock_shared();`
Lock ownership acquired through a call to __lock_upgrade_ref__ must be released through a call to __unlock_upgrade_ref__. If the
ownership type is changed through a call to one of the `unlock_xxx_and_lock_yyy()` functions, ownership must be released through a
call to the unlock function corresponding to the new level of ownership.
-[section:lock_upgrade `void lock_upgrade()`]
+[section:lock_upgrade `m.lock_upgrade()`]
[variablelist
+[[Precondition:] [The calling thread has no ownership of the mutex. ]]
+
[[Effects:] [The current thread blocks until upgrade ownership can be obtained for the current thread.]]
-[[Postcondition:] [The current thread has upgrade ownership of `*this`.]]
+[[Postcondition:] [The current thread has upgrade ownership of `m`.]]
+
+[[Synchronization:] [Prior `__unlock_upgrade()` operations on the same object synchronize with this operation.]]
[[Throws:] [__thread_resource_error__ if an error occurs.]]
]
[endsect]
-[section:unlock_upgrade `void unlock_upgrade()`]
+[section:unlock_upgrade `m.unlock_upgrade()`]
[variablelist
-[[Precondition:] [The current thread has upgrade ownership of `*this`.]]
+[[Precondition:] [The current thread has upgrade ownership of `m`.]]
-[[Effects:] [Releases upgrade ownership of `*this` by the current thread.]]
+[[Effects:] [Releases upgrade ownership of `m` by the current thread.]]
-[[Postcondition:] [The current thread no longer has upgrade ownership of `*this`.]]
+[[Postcondition:] [The current thread no longer has upgrade ownership of `m`.]]
+[[Synchronization:] [This operation synchronizes with subsequent lock operations that obtain ownership on the same object.]]
+
[[Throws:] [Nothing]]
]
[endsect]
-[section:unlock_upgrade_and_lock `void unlock_upgrade_and_lock()`]
+[section:try_lock_upgrade `m.try_lock_upgrade()`]
[variablelist
-[[Precondition:] [The current thread has upgrade ownership of `*this`.]]
+[[Precondition:] [The calling thread has no ownership of the mutex. ]]
-[[Effects:] [Atomically releases upgrade ownership of `*this` by the current thread and acquires exclusive ownership of `*this`. If
-any other threads have shared ownership, blocks until exclusive ownership can be acquired.]]
+[[Effects:] [Attempts to obtain upgrade ownership of the mutex for the calling thread without blocking. If upgrade ownership is not obtained, there is no effect and try_lock_upgrade() immediately returns.]]
+
+[[Returns:] [`true` if upgrade ownership was acquired for the current thread, `false` otherwise.]]
-[[Postcondition:] [The current thread has exclusive ownership of `*this`.]]
+[[Postcondition:] [If the call returns `true`, the current thread has upgrade ownership of `m`.]]
+
+[[Synchronization:] [If `__try_lock_upgrade()` returns true, prior `__unlock_upgrade()` operations on the same object synchronize with this operation.]]
[[Throws:] [Nothing]]
]
[endsect]
-[section:unlock_upgrade_and_lock_shared `void unlock_upgrade_and_lock_shared()`]
+
+[section:try_lock_upgrade_for `m.try_lock_upgrade_for(rel_time)`]
[variablelist
-[[Precondition:] [The current thread has upgrade ownership of `*this`.]]
+[[Precondition:] [The calling thread has no ownership of the mutex. ]]
-[[Effects:] [Atomically releases upgrade ownership of `*this` by the current thread and acquires shared ownership of `*this` without
-blocking.]]
+[[Effects:] [If the tick period of `rel_time` is not exactly convertible to the native tick period, the duration shall be rounded up to the nearest native tick period.
+Attempts to obtain upgrade lock ownership for the calling thread within the relative timeout specified by `rel_time`.
+If the time specified by `rel_time` is less than or equal to `rel_time.zero()`, the function attempts to obtain ownership without blocking (as if by calling `__try_lock_upgrade()`).
+The function returns within the timeout specified by `rel_time` only if it has obtained upgrade ownership of the mutex object.]]
+
+[[Returns:] [`true` if upgrade ownership was acquired for the current thread, `false` otherwise.]]
+
+[[Postcondition:] [If the call returns `true`, the current thread has upgrade ownership of `m`.]]
-[[Postcondition:] [The current thread has shared ownership of `*this`.]]
+[[Synchronization:] [If `__try_lock_upgrade_for(rel_time)` returns true, prior `__unlock_upgrade()` operations on the same object synchronize with this operation.]]
[[Throws:] [Nothing]]
]
[endsect]
-[section:unlock_and_lock_upgrade `void unlock_and_lock_upgrade()`]
+[section:try_lock_upgrade_until `m.try_lock_upgrade_until(abs_time)`]
[variablelist
-[[Precondition:] [The current thread has exclusive ownership of `*this`.]]
+[[Precondition:] [The calling thread has no ownership of the mutex. ]]
+
+[[Effects:] [The function attempts to obtain upgrade ownership of the mutex.
+If `abs_time` has already passed, the function attempts to obtain upgrade ownership without blocking (as if by calling `__try_lock_upgrade()`).
+The function returns before the absolute timeout specified by `abs_time` only if it has obtained upgrade ownership of the mutex object.]]
+
+[[Returns:] [`true` if upgrade ownership was acquired for the current thread, `false` otherwise.]]
+
+[[Postcondition:] [If the call returns `true`, the current thread has upgrade ownership of `m`.]]
+
+[[Synchronization:] [If `__try_lock_upgrade_until(abs_time)` returns true, prior `__unlock_upgrade()` operations on the same object synchronize with this operation.]]
+
+[[Throws:] [Nothing]]
+
+]
+[endsect]
+
+
+[section:try_unlock_shared_and_lock `m.try_unlock_shared_and_lock()`]
+
+[variablelist
-[[Effects:] [Atomically releases exclusive ownership of `*this` by the current thread and acquires upgrade ownership of `*this`
+[[Precondition:] [The calling thread must hold a shared lock on the mutex.]]
+
+[[Effects:] [The function attempts to atomically convert the ownership from shared to exclusive for the calling thread without blocking.
+For this conversion to be successful, this thread must be the only thread holding any ownership of the lock.
+If the conversion is not successful, the shared ownership of m is retained.]]
+
+[[Returns:] [`true` if exclusive ownership was acquired for the current thread, `false` otherwise.]]
+
+[[Postcondition:] [If the call returns `true`, the current thread has exclusive ownership of `m`.]]
+
+[[Synchronization:] [If `__ try_unlock_shared_and_lock()` returns true, prior `__unlock()` and subsequent lock operations on the same object synchronize with this operation. ]]
+
+[[Throws:] [Nothing]]
+
+]
+[endsect]
+
+[section:try_unlock_shared_and_lock_for `m.try_unlock_shared_and_lock_for(rel_time)`]
+
+[variablelist
+
+[[Precondition:] [The calling thread shall hold a shared lock on the mutex.]]
+
+[[Effects:] [If the tick period of `rel_time` is not exactly convertible to the native tick period, the duration shall be rounded up to the nearest native tick period.
+The function attempts to atomically convert the ownership from shared to exclusive for the calling thread within the relative timeout specified by `rel_time`.
+If the time specified by `rel_time` is less than or equal to `rel_time.zero()`, the function attempts to obtain exclusive ownership without blocking (as if by calling `try_unlock_shared_and_lock()`).
+The function shall return within the timeout specified by `rel_time` only if it has obtained exclusive ownership of the mutex object.
+For this conversion to be successful, this thread must be the only thread holding any ownership of the lock at the moment of conversion.
+If the conversion is not successful, the shared ownership of the mutex is retained.]]
+
+[[Returns:] [`true` if exclusive ownership was acquired for the current thread, `false` otherwise.]]
+
+[[Postcondition:] [If the call returns `true`, the current thread has exclusive ownership of `m`.]]
+
+[[Synchronization:] [If `__try_unlock_shared_and_lock_for(rel_time)` returns true, prior `__unlock()` and subsequent lock operations on the same object synchronize with this operation. ]]
+
+[[Throws:] [Nothing]]
+
+]
+[endsect]
+
+
+[section:try_unlock_shared_and_lock_until `m.try_unlock_shared_and_lock_until(abs_time)`]
+
+[variablelist
+
+[[Precondition:] [The calling thread shall hold a shared lock on the mutex.]]
+
+[[Effects:] [The function attempts to atomically convert the ownership from shared to exclusive for the calling thread within the absolute timeout specified by `abs_time`.
+If `abs_time` has already passed, the function attempts to obtain exclusive ownership without blocking (as if by calling `try_unlock_shared_and_lock()`).
+The function shall return before the absolute timeout specified by `abs_time` only if it has obtained exclusive ownership of the mutex object.
+For this conversion to be successful, this thread must be the only thread holding any ownership of the lock at the moment of conversion.
+If the conversion is not successful, the shared ownership of the mutex is retained.]]
+
+[[Returns:] [`true` if exclusive ownership was acquired for the current thread, `false` otherwise.]]
+
+[[Postcondition:] [If the call returns `true`, the current thread has exclusive ownership of `m`.]]
+
+[[Synchronization:] [If `__try_unlock_shared_and_lock_until(rel_time)` returns true, prior `__unlock()` and subsequent lock operations on the same object synchronize with this operation. ]]
+
+[[Throws:] [Nothing]]
+
+]
+[endsect]
+
+[section:unlock_and_lock_shared `m.unlock_and_lock_shared()`]
+
+[variablelist
+
+[[Precondition:] [The calling thread shall hold an exclusive lock on `m`.]]
+
+[[Effects:] [Atomically converts the ownership from exclusive to shared for the calling thread.]]
+
+[[Postcondition:] [The current thread has shared ownership of `m`.]]
+
+[[Synchronization:] [This operation synchronizes with subsequent lock operations that obtain ownership of the same object.]]
+
+[[Throws:] [Nothing]]
+
+]
+[endsect]
+
+[section:try_unlock_shared_and_lock_upgrade `m.try_unlock_shared_and_lock_upgrade()`]
+
+[variablelist
+
+[[Precondition:] [The calling thread shall hold a shared lock on the mutex.]]
+
+[[Effects:] [The function attempts to atomically convert the ownership from shared to upgrade for the calling thread without blocking.
+For this conversion to be successful, there must be no thread holding upgrade ownership of this object.
+If the conversion is not successful, the shared ownership of the mutex is retained.]]
+
+[[Returns:] [`true` if upgrade ownership was acquired for the current thread, `false` otherwise.]]
+
+[[Postcondition:] [If the call returns `true`, the current thread has upgrade ownership of `m`.]]
+
+[[Synchronization:] [If `__try_unlock_shared_and_lock_upgrade()` returns true, prior `__unlock_upgrade()` and subsequent lock operations on the same object synchronize with this operation. ]]
+
+[[Throws:] [Nothing]]
+
+]
+[endsect]
+
+
+[section:try_unlock_shared_and_lock_upgrade_for `m.try_unlock_shared_and_lock_upgrade_for(rel_time)`]
+
+[variablelist
+
+[[Precondition:] [The calling thread shall hold a shared lock on the mutex.]]
+
+[[Effects:] [If the tick period of `rel_time` is not exactly convertible to the native tick period, the duration shall be rounded up to the nearest native tick period.
+The function attempts to atomically convert the ownership from shared to upgrade for the calling thread within the relative timeout specified by `rel_time`.
+If the time specified by `rel_time` is less than or equal to `rel_time.zero()`, the function attempts to obtain upgrade ownership without blocking (as if by calling `__try_unlock_shared_and_lock_upgrade()`).
+The function shall return within the timeout specified by `rel_time` only if it has obtained exclusive ownership of the mutex object.
+For this conversion to be successful, there must be no thread holding upgrade ownership of this object at the moment of conversion.
+If the conversion is not successful, the shared ownership of m is retained.]]
+
+[[Returns:] [`true` if upgrade ownership was acquired for the current thread, `false` otherwise.]]
+
+[[Postcondition:] [If the call returns `true`, the current thread has upgrade ownership of `m`.]]
+
+[[Synchronization:] [If `__try_unlock_shared_and_lock_upgrade_for(rel_time)` returns true, prior `__unlock_upgrade()` and subsequent lock operations on the same object synchronize with this operation. ]]
+
+[[Throws:] [Nothing]]
+
+]
+[endsect]
+
+[section:try_unlock_shared_and_lock_upgrade_until `m.try_unlock_shared_and_lock_upgrade_until(abs_time)`]
+
+[variablelist
+
+[[Precondition:] [The calling thread shall hold a shared lock on the mutex.]]
+
+[[Effects:] [The function attempts to atomically convert the ownership from shared to upgrade for the calling thread within the absolute timeout specified by `abs_time`.
+If `abs_time` has already passed, the function attempts to obtain upgrade ownership without blocking (as if by calling `__try_unlock_shared_and_lock_upgrade()`).
+The function shall return before the absolute timeout specified by `abs_time` only if it has obtained upgrade ownership of the mutex object.
+For this conversion to be successful, there must be no thread holding upgrade ownership of this object at the moment of conversion.
+If the conversion is not successful, the shared ownership of the mutex is retained.]]
+
+[[Returns:] [`true` if upgrade ownership was acquired for the current thread, `false` otherwise.]]
+
+[[Postcondition:] [If the call returns `true`, the current thread has upgrade ownership of `m`.]]
+
+[[Synchronization:] [If `__try_unlock_shared_and_lock_upgrade_until(rel_time)` returns true, prior `__unlock_upgrade()` and subsequent lock operations on the same object synchronize with this operation. ]]
+
+[[Throws:] [Nothing]]
+
+]
+[endsect]
+
+[section:unlock_and_lock_upgrade `m.unlock_and_lock_upgrade()`]
+
+[variablelist
+
+[[Precondition:] [The current thread has exclusive ownership of `m`.]]
+
+[[Effects:] [Atomically releases exclusive ownership of `m` by the current thread and acquires upgrade ownership of `m`
without blocking.]]
-[[Postcondition:] [The current thread has upgrade ownership of `*this`.]]
+[[Postcondition:] [The current thread has upgrade ownership of `m`.]]
+
+[[Synchronization:] [This operation synchronizes with subsequent lock operations that obtain ownership of the same object.]]
+
+[[Throws:] [Nothing]]
+
+]
+[endsect]
+
+
+[section:unlock_upgrade_and_lock `m.unlock_upgrade_and_lock()`]
+
+[variablelist
+
+[[Precondition:] [The current thread has upgrade ownership of `m`.]]
+
+[[Effects:] [Atomically releases upgrade ownership of `m` by the current thread and acquires exclusive ownership of `m`. If
+any other threads have shared ownership, blocks until exclusive ownership can be acquired.]]
+
+[[Postcondition:] [The current thread has exclusive ownership of `m`.]]
+
+[[Synchronization:] [This operation synchronizes with prior `__unlock_shared()` and subsequent lock operations that obtain ownership of the same object.]]
+
+[[Throws:] [Nothing]]
+
+]
+[endsect]
+
+[section:try_unlock_upgrade_and_lock `m.try_unlock_upgrade_and_lock()`]
+
+[variablelist
+
+[[Precondition:] [The calling thread shall hold a upgrade lock on the mutex.]]
+
+[[Effects:] [The function attempts to atomically convert the ownership from upgrade to exclusive for the calling thread without blocking.
+For this conversion to be successful, this thread must be the only thread holding any ownership of the lock.
+If the conversion is not successful, the upgrade ownership of m is retained.]]
+
+[[Returns:] [`true` if exclusive ownership was acquired for the current thread, `false` otherwise.]]
+
+[[Postcondition:] [If the call returns `true`, the current thread has exclusive ownership of `m`.]]
+
+[[Synchronization:] [If `__try_unlock_upgrade_and_lock()` returns true, prior `__unlock()` and subsequent lock operations on the same object synchronize with this operation. ]]
+
+[[Throws:] [Nothing]]
+
+]
+[endsect]
+
+[section:try_unlock_upgrade_and_lock_for `m.try_unlock_upgrade_and_lock_for(rel_time)`]
+
+[variablelist
+
+[[Precondition:] [The calling thread shall hold a upgrade lock on the mutex.]]
+
+[[Effects:] [If the tick period of `rel_time` is not exactly convertible to the native tick period, the duration shall be rounded up to the nearest native tick period.
+The function attempts to atomically convert the ownership from upgrade to exclusive for the calling thread within the relative timeout specified by `rel_time`.
+If the time specified by `rel_time` is less than or equal to `rel_time.zero()`, the function attempts to obtain exclusive ownership without blocking (as if by calling `__try_unlock_upgrade_and_lock()`).
+The function shall return within the timeout specified by `rel_time` only if it has obtained exclusive ownership of the mutex object.
+For this conversion to be successful, this thread shall be the only thread holding any ownership of the lock at the moment of conversion.
+If the conversion is not successful, the upgrade ownership of m is retained.]]
+
+[[Returns:] [`true` if exclusive ownership was acquired for the current thread, `false` otherwise.]]
+
+[[Postcondition:] [If the call returns `true`, the current thread has exclusive ownership of `m`.]]
+
+[[Synchronization:] [If `__try_unlock_upgrade_and_lock_for(rel_time)` returns true, prior `__unlock()` and subsequent lock operations on the same object synchronize with this operation. ]]
+
+[[Throws:] [Nothing]]
+
+]
+[endsect]
+
+[section:try_unlock_upgrade_and_lock_until `m.try_unlock_upgrade_and_lock_until(abs_time)`]
+
+[variablelist
+
+[[Precondition:] [The calling thread shall hold a upgrade lock on the mutex.]]
+
+[[Effects:] [The function attempts to atomically convert the ownership from upgrade to exclusive for the calling thread within the absolute timeout specified by `abs_time`.
+If `abs_time` has already passed, the function attempts to obtain exclusive ownership without blocking (as if by calling `__try_unlock_upgrade_and_lock()`).
+The function shall return before the absolute timeout specified by `abs_time` only if it has obtained exclusive ownership of the mutex object.
+For this conversion to be successful, this thread shall be the only thread holding any ownership of the lock at the moment of conversion.
+If the conversion is not successful, the upgrade ownership of m is retained.]]
+
+[[Returns:] [`true` if exclusive ownership was acquired for the current thread, `false` otherwise.]]
+
+[[Postcondition:] [If the call returns `true`, the current thread has exclusive ownership of `m`.]]
+
+[[Synchronization:] [If `__try_unlock_upgrade_and_lock_for(rel_time)` returns true, prior `__unlock()` and subsequent lock operations on the same object synchronize with this operation. ]]
+
+[[Throws:] [Nothing]]
+
+]
+[endsect]
+
+
+[section:unlock_upgrade_and_lock_shared `m.unlock_upgrade_and_lock_shared()`]
+
+[variablelist
+
+[[Precondition:] [The current thread has upgrade ownership of `m`.]]
+
+[[Effects:] [Atomically releases upgrade ownership of `m` by the current thread and acquires shared ownership of `m` without
+blocking.]]
+
+[[Postcondition:] [The current thread has shared ownership of `m`.]]
+
+[[Synchronization:] [This operation synchronizes with prior `unlock_shared()` and subsequent lock operations that obtain ownership of the same object.]]
[[Throws:] [Nothing]]
@@ -352,6 +760,32 @@
[section:locks Lock Types]
+ #include <boost/thread/locks.hpp>
+
+ struct defer_lock_t {};
+ struct try_to_lock_t {};
+ struct adopt_lock_t {};
+ const defer_lock_t defer_lock;
+ const try_to_lock_t try_to_lock;
+ const adopt_lock_t adopt_lock;
+
+ template<typename Lockable>
+ class lock_guard
+ template<typename Lockable>
+ class unique_lock;
+ template<typename Mutex>
+ void swap(unique_lock <Mutex>& lhs, unique_lock <Mutex>& rhs);
+ template<typename Lockable>
+ class shared_lock;
+ template<typename Mutex>
+ void swap(shared_lock<Mutex>& lhs,shared_lock<Mutex>& rhs);
+ template<typename Lockable>
+ class upgrade_lock;
+ template<typename Mutex>
+ void swap(upgrade_lock <Mutex>& lhs, upgrade_lock <Mutex>& rhs);
+ template <class Mutex>
+ class upgrade_to_unique_lock;
+
[section:lock_tags Lock option tags]
#include <boost/thread/locks.hpp>
@@ -462,10 +896,9 @@
unique_lock(unique_lock const&) = delete;
unique_lock& operator=(unique_lock const&) = delete;
unique_lock(unique_lock<Lockable>&& other) noexcept;
- unique_lock(upgrade_lock<Lockable>&& other) noexcept;
+ explicit unique_lock(upgrade_lock<Lockable>&& other) noexcept;
unique_lock& operator=(unique_lock<Lockable>&& other) noexcept;
- unique_lock& operator=(upgrade_lock<Lockable>&& other) noexcept;
void swap(unique_lock& other) noexcept;
Lockable* release() noexcept;
@@ -483,13 +916,8 @@
void unlock();
- bool owns_lock() const noexcept;
- #if defined(BOOST_NO_EXPLICIT_CONVERSION_OPERATORS)
- operator ``['unspecified-bool-type]``() const noexcept;
- bool operator!() const noexcept;
- #else
explicit operator bool() const noexcept;
- #endif
+ bool owns_lock() const noexcept;
Lockable* mutex() const noexcept;
};
@@ -499,9 +927,10 @@
fashion, or with a timeout. Consequently, __unlock_ref__ is only called in the destructor if the lock object has locked the
__lockable_concept_type__ object, or otherwise adopted a lock on the __lockable_concept_type__ object.
-Specializations of __unique_lock__ model the __timed_lockable_concept__ if the supplied Lockable type itself models
-__timed_lockable_concept__ (e.g. `boost::unique_lock<boost::timed_mutex>`), or the __lockable_concept__ otherwise
-(e.g. `boost::unique_lock<boost::mutex>`).
+Specializations of __unique_lock__ model the __TimedLockable concept if the supplied `Lockable` type itself models
+__TimedLockable concept (e.g. `boost::unique_lock<boost::timed_mutex>`), or the __Lockable concept if the supplied `Lockable` type itself models
+__Lockable concept (e.g. `boost::unique_lock<boost::mutex>`), or the __BasicLockable concept if the supplied `Lockable` type itself models
+__BasicLockable concept.
An instance of __unique_lock__ is said to ['own] the lock state of a __lockable_concept_type__ `m` if __mutex_func_ref__ returns a
pointer to `m` and __owns_lock_ref__ returns `true`. If an object that ['owns] the lock state of a __lockable_concept_type__ object
@@ -607,10 +1036,6 @@
[section:constructor_time_point `template <class Clock, class Duration> unique_lock(Lockable & m,const chrono::time_point<Clock, Duration>& abs_time)`]
- template <class Rep, class Period>
- unique_lock(Mutex& mtx, const chrono::duration<Rep, Period>& d);
-
-
[variablelist
[[Effects:] [Stores a reference to `m`. Invokes
@@ -697,32 +1122,6 @@
[endsect]
-[section:bool_conversion `operator unspecified-bool-type() const`]
-
-[variablelist
-
-[[Returns:] [If __owns_lock_ref__ would return `true`, a value that evaluates to
-`true` in boolean contexts, otherwise a value that evaluates to `false` in
-boolean contexts.]]
-
-[[Throws:] [Nothing.]]
-
-]
-
-[endsect]
-
-
-[section:operator_not `bool operator!() const`]
-
-[variablelist
-
-[[Returns:] [`!` __owns_lock_ref__.]]
-
-[[Throws:] [Nothing.]]
-
-]
-
-[endsect]
[section:release `Lockable* release()`]
@@ -760,32 +1159,33 @@
shared_lock(Lockable& m_,adopt_lock_t);
shared_lock(Lockable& m_,defer_lock_t);
shared_lock(Lockable& m_,try_to_lock_t);
- shared_lock(Lockable& m_,system_time const& target_time);
+ shared_lock(Lockable& m_,system_time const& target_time); // DEPRECATED V2
+ template <class Clock, class Duration>
+ shared_lock(Mutex& mtx, const chrono::time_point<Clock, Duration>& t);
+ template <class Rep, class Period>
+ shared_lock(Mutex& mtx, const chrono::duration<Rep, Period>& d);
~shared_lock();
shared_lock(shared_lock const&) = delete;
shared_lock& operator=(shared_lock const&) = delete;
shared_lock(shared_lock<Lockable> && other);
- shared_lock(unique_lock<Lockable> && other);
- shared_lock(upgrade_lock<Lockable> && other);
+ explicit shared_lock(unique_lock<Lockable> && other);
+ explicit shared_lock(upgrade_lock<Lockable> && other);
shared_lock& operator=(shared_lock<Lockable> && other);
- shared_lock& operator=(unique_lock<Lockable> && other);
- shared_lock& operator=(upgrade_lock<Lockable> && other);
void swap(shared_lock& other);
void lock();
bool try_lock();
- bool timed_lock(boost::system_time const& target_time);
+ bool timed_lock(boost::system_time const& target_time); // DEPRECATED V2
+ template <class Rep, class Period>
+ bool try_lock_for(const chrono::duration<Rep, Period>& rel_time);
+ template <class Clock, class Duration>
+ bool try_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
void unlock();
- #if defined(BOOST_NO_EXPLICIT_CONVERSION_OPERATORS)
- operator ``['unspecified-bool-type]``() const;
- bool operator!() const;
- #else
explicit operator bool() const;
- #endif
bool owns_lock() const;
};
@@ -938,31 +1338,6 @@
[endsect]
-[section:bool_conversion `operator unspecified-bool-type() const`]
-
-[variablelist
-
-[[Returns:] [If __owns_lock_shared_ref__ would return `true`, a value that evaluates to
-`true` in boolean contexts, otherwise a value that evaluates to `false` in
-boolean contexts.]]
-
-[[Throws:] [Nothing.]]
-
-]
-
-[endsect]
-
-[section:operator_not `bool operator!() const`]
-
-[variablelist
-
-[[Returns:] [`!` __owns_lock_shared_ref__.]]
-
-[[Throws:] [Nothing.]]
-
-]
-
-[endsect]
[section:explicit_operator_bool `explicit operator bool() const`]
@@ -1010,7 +1385,7 @@
explicit upgrade_lock(Lockable& m_);
upgrade_lock(upgrade_lock<Lockable> && other);
- upgrade_lock(unique_lock<Lockable> && other);
+ explicit upgrade_lock(unique_lock<Lockable> && other);
~upgrade_lock();
@@ -1018,19 +1393,18 @@
upgrade_lock& operator=(const upgrade_lock<Lockable> & other) = delete;
upgrade_lock& operator=(upgrade_lock<Lockable> && other);
- upgrade_lock& operator=(unique_lock<Lockable> && other);
void swap(upgrade_lock& other);
void lock();
+ bool try_lock();
+ template <class Rep, class Period>
+ bool try_lock_for(const chrono::duration<Rep, Period>& rel_time);
+ template <class Clock, class Duration>
+ bool try_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
void unlock();
- #if defined(BOOST_NO_EXPLICIT_CONVERSION_OPERATORS)
- operator ``['unspecified-bool-type]``() const;
- bool operator!() const;
- #else
explicit operator bool() const;
- #endif
bool owns_lock() const;
};
@@ -1072,12 +1446,7 @@
void swap(upgrade_to_unique_lock& other);
- #if defined(BOOST_NO_EXPLICIT_CONVERSION_OPERATORS)
- operator ``['unspecified-bool-type]``() const;
- bool operator!() const;
- #else
explicit operator bool() const;
- #endif
bool owns_lock() const;
};
@@ -1110,17 +1479,12 @@
void lock();
bool try_lock();
void unlock();
- bool owns_lock() const;
MutexType* mutex() const;
MutexType* release();
- #if defined(BOOST_NO_EXPLICIT_CONVERSION_OPERATORS)
- operator ``['unspecified-bool-type]``() const;
- bool operator!() const;
- #else
explicit operator bool() const;
- #endif
+ bool owns_lock() const;
};
The member typedef `scoped_try_lock` is provided for each distinct
@@ -1130,11 +1494,155 @@
that the constructor that takes a single reference to a mutex will
call [try_lock_ref_link `m.try_lock()`] rather than `m.lock()`.
+[endsect]
+[endsect]
+[/
+[section:other_mutex Other Mutex Types]
+
+[section: reverse_mutex Class template `reverse_mutex`]
+
+ #include <boost/thread/reverse_mutex.hpp>
+
+ template<typename BasicLockable>
+ class reverse_mutex
+ {
+ public:
+ typedef BasicLockable mutex_type;
+ reverse_mutex(reverse_mutex const&) = delete;
+ reverse_mutex& operator=(reverse_mutex const&) = delete;
+
+ explicit reverse_mutex(mutex_type& m_);
+ ~reverse_mutex();
+
+ void lock();
+ void unlock();
+ };
+
+__reverse_mutex reverse the operations of a __BasicLockable, that unlocks the lockable when `lock()` is called and locks it when `unlock()` is called.
+
+[endsect]
[endsect]
+[section:other_locks Other Lock Types]
+
+
+[section:shared_lock_guard Class template `shared_lock_guard`]
+
+ #include <boost/thread/shared_lock_guard.hpp>
+
+ template<typename SharedLockable>
+ class shared_lock_guard
+ {
+ public:
+ explicit shared_lock_guard(SharedLockable& m_);
+ shared_lock_guard(SharedLockable& m_,boost::adopt_lock_t);
+
+ ~shared_lock_guard();
+ };
+
+__shared_lock_guard is very simple: on construction it
+acquires shared ownership of the implementation of the __shared_lockable_concept__ supplied as
+the constructor parameter. On destruction, the ownership is released. This
+provides simple RAII-style locking of a __shared_lockable_concept_type__ object, to facilitate exception-safe
+shared locking and unlocking.
+In addition, the `__shared_lock_guard_ca(SharedLockable &m, boost::adopt_lock_t)` constructor allows the __shared_lock_guard object to
+take shared ownership of a lock already held by the current thread.
+
+[section:constructor `shared_lock_guard(SharedLockable & m)`]
+
+[variablelist
+
+[[Effects:] [Stores a reference to `m`. Invokes `m.__lock_shared()`.]]
+
+[[Throws:] [Any exception thrown by the call to `m.__lock_shared()`.]]
+
+]
+
[endsect]
+[section:constructor_adopt `shared_lock_guard(SharedLockable & m,boost::adopt_lock_t)`]
+
+[variablelist
+
+[[Precondition:] [The current thread owns a lock on `m` equivalent to one
+obtained by a call to `m.__lock_shared()`.]]
+
+[[Effects:] [Stores a reference to `m`. Takes ownership of the lock state of
+`m`.]]
+
+[[Throws:] [Nothing.]]
+
+]
+
+[endsect]
+
+[section:destructor `~shared_lock_guard()`]
+
+[variablelist
+
+[[Effects:] [Invokes `m.__unlock_shared()` on the __shared_lockable_concept_type__ object passed to the constructor.]]
+
+[[Throws:] [Nothing.]]
+
+]
+
+[endsect]
+
+[endsect]
+
+[section:reverse_lock Class template `reverse_lock`]
+
+ #include <boost/thread/reverse_lock.hpp>
+
+ template<typename Lock>
+ class reverse_lock
+ {
+ public:
+ reverse_lock(reverse_lock const&) = delete;
+ reverse_lock& operator=(reverse_lock const&) = delete;
+
+ explicit reverse_lock(Lock& m_);
+ ~reverse_lock();
+ };
+
+__reverse_lock reverse the operations of a lock: it provide for RAII-style, that unlocks the lock at construction time and lock it at destruction time. In addition, it transfer ownership temporarily, so that the mutex can not be locked using the Lock.
+
+An instance of __reverse_lock doesn't ['own] the lock never.
+
+[section:constructor `reverse_lock(Lock & m)`]
+
+[variablelist
+
+[[Effects:] [Stores a reference to `m`. Invokes `m.__unlock()` if `m` owns his lock and then stores the mutex by calling `m.__release()`.]]
+
+[[Postcondition:] [`!m.__owns_lock() && m.__mutex()==0`.]]
+
+[[Throws:] [Any exception thrown by the call to `m.__unlock()`.]]
+
+]
+
+[endsect]
+
+
+[section:destructor `~reverse_lock()`]
+
+[variablelist
+
+[[Effects:] [Let be mtx the stored mutex*. If not 0 Invokes `mtx->__lock()` and gives again the `mtx` to the `Lock` using the `adopt_lock_t` overload.]]
+
+[[Throws:] [Nothing.]]
+
+]
+
+[endsect]
+
+
+[endsect]
+
+[endsect]
+]
+
[section:lock_functions Lock functions]
[section:lock_multiple Non-member function `lock(Lockable1,Lockable2,...)`]
Modified: trunk/libs/thread/doc/overview.qbk
==============================================================================
--- trunk/libs/thread/doc/overview.qbk (original)
+++ trunk/libs/thread/doc/overview.qbk 2012-03-31 03:37:59 EDT (Sat, 31 Mar 2012)
@@ -19,7 +19,10 @@
[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2184.html N2184],
[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2139.html N2139], and
[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2094.html N2094]
-Vicente J. Botet Escriba started in version 2 the adaptation to comply with the accepted Thread C++11 library.
+
+Vicente J. Botet Escriba started in version 2 the adaptation to comply with the accepted Thread C++11 library (Make use of Boost.Chrono and Boost.Move) and the [@http://home.roadrunner.com/~hinnant/bloomington/shared_mutex.html Shared Locking] Howard Hinnant proposal except for the upward conversions.
+
+[/ as some new features as thread attributes, unlock_guard, shared_guard, ]
In order to use the classes and functions described here, you can
either include the specific headers specified by the descriptions of
Modified: trunk/libs/thread/doc/shared_mutex_ref.qbk
==============================================================================
--- trunk/libs/thread/doc/shared_mutex_ref.qbk (original)
+++ trunk/libs/thread/doc/shared_mutex_ref.qbk 2012-03-31 03:37:59 EDT (Sat, 31 Mar 2012)
@@ -12,33 +12,118 @@
class shared_mutex
{
public:
+ shared_mutex(shared_mutex const&) = delete;
+ shared_mutex& operator=(shared_mutex const&) = delete;
+
shared_mutex();
~shared_mutex();
void lock_shared();
bool try_lock_shared();
- bool timed_lock_shared(system_time const& timeout);
+ template <class Rep, class Period>
+ bool try_lock_shared_for(const chrono::duration<Rep, Period>& rel_time);
+ template <class Clock, class Duration>
+ bool try_lock_shared_until(const chrono::time_point<Clock, Duration>& abs_time);
+ bool timed_lock_shared(system_time const& timeout); // DEPRECATED V2
+ void unlock_shared();
+
+ void lock();
+ bool try_lock();
+ template <class Rep, class Period>
+ bool try_lock_for(const chrono::duration<Rep, Period>& rel_time);
+ template <class Clock, class Duration>
+ bool try_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
+ bool timed_lock(system_time const& timeout); // DEPRECATED V2
+ void unlock();
+
+ void lock_upgrade(); // DEPRECATED V2
+ void unlock_upgrade(); // DEPRECATED V2
+
+ void unlock_upgrade_and_lock(); // DEPRECATED V2
+ void unlock_and_lock_upgrade(); // DEPRECATED V2
+ void unlock_and_lock_shared(); // DEPRECATED V2
+ void unlock_upgrade_and_lock_shared(); // DEPRECATED V2
+ };
+
+The class `boost::shared_mutex` provides an implementation of a multiple-reader / single-writer mutex. It implements the
+__shared_lockable_concept__.
+
+Multiple concurrent calls to __lock_ref__, __try_lock_ref__, `__try_lock_for()`, `__try_lock_until()`, __timed_lock_ref__, __lock_shared_ref__,
+`__try_lock_shared_for()`, `__try_lock_shared_until()`, __try_lock_shared_ref__ and __timed_lock_shared_ref__ are permitted.
+
+
+[endsect]
+
+[section:upgrade_mutex Class `upgrade_mutex`]
+
+ #include <boost/thread/shared_mutex.hpp>
+
+ class upgrade_mutex
+ {
+ public:
+ upgrade_mutex(upgrade_mutex const&) = delete;
+ upgrade_mutex& operator=(upgrade_mutex const&) = delete;
+
+ upgrade_mutex();
+ ~upgrade_mutex();
+
+ void lock_shared();
+ bool try_lock_shared();
+ template <class Rep, class Period>
+ bool try_lock_shared_for(const chrono::duration<Rep, Period>& rel_time);
+ template <class Clock, class Duration>
+ bool try_lock_shared_until(const chrono::time_point<Clock, Duration>& abs_time);
void unlock_shared();
void lock();
bool try_lock();
- bool timed_lock(system_time const& timeout);
+ template <class Rep, class Period>
+ bool try_lock_for(const chrono::duration<Rep, Period>& rel_time);
+ template <class Clock, class Duration>
+ bool try_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
void unlock();
void lock_upgrade();
+ template <class Rep, class Period>
+ bool try_lock_upgrade_for(const chrono::duration<Rep, Period>& rel_time);
+ template <class Clock, class Duration>
+ bool try_lock_upgrade_until(const chrono::time_point<Clock, Duration>& abs_time);
void unlock_upgrade();
- void unlock_upgrade_and_lock();
- void unlock_and_lock_upgrade();
+ // Shared <-> Exclusive
+
+ bool try_unlock_shared_and_lock();
+ template <class Rep, class Period>
+ bool try_unlock_shared_and_lock_for(const chrono::duration<Rep, Period>& rel_time);
+ template <class Clock, class Duration>
+ bool try_unlock_shared_and_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
void unlock_and_lock_shared();
+
+ // Shared <-> Upgrade
+
+ bool try_unlock_shared_and_lock_upgrade();
+ template <class Rep, class Period>
+ bool try_unlock_shared_and_lock_upgrade_for(const chrono::duration<Rep, Period>& rel_time);
+ template <class Clock, class Duration>
+ bool try_unlock_shared_and_lock_upgrade_until(const chrono::time_point<Clock, Duration>& abs_time);
void unlock_upgrade_and_lock_shared();
+
+ // Upgrade <-> Exclusive
+
+ void unlock_upgrade_and_lock();
+ bool try_unlock_upgrade_and_lock();
+ template <class Rep, class Period>
+ bool try_unlock_upgrade_and_lock_for(const chrono::duration<Rep, Period>& rel_time);
+ template <class Clock, class Duration>
+ bool try_unlock_upgrade_and_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
+ void unlock_and_lock_upgrade();
};
-The class `boost::shared_mutex` provides an implementation of a multiple-reader / single-writer mutex. It implements the
+The class `boost::upgrade_mutex` provides an implementation of a multiple-reader / single-writer mutex. It implements the
__upgrade_lockable_concept__.
-Multiple concurrent calls to __lock_ref__, __try_lock_ref__, __timed_lock_ref__, __lock_shared_ref__, __try_lock_shared_ref__ and
-__timed_lock_shared_ref__ shall be permitted.
+Multiple concurrent calls to __lock_ref__, __try_lock_ref__, `__try_lock_for()`, `__try_lock_until()`, __timed_lock_ref__, __lock_shared_ref__,
+`__try_lock_shared_for()`, `__try_lock_shared_until()`, __try_lock_shared_ref__ and __timed_lock_shared_ref__ are permitted.
[endsect]
Modified: trunk/libs/thread/doc/thread.qbk
==============================================================================
--- trunk/libs/thread/doc/thread.qbk (original)
+++ trunk/libs/thread/doc/thread.qbk 2012-03-31 03:37:59 EDT (Sat, 31 Mar 2012)
@@ -8,6 +8,7 @@
[article Thread
[quickbook 1.5]
+ [version 2.0.0]
[authors [Williams, Anthony] [Botet Escriba, Vicente J.]]
[copyright 2007-11 Anthony Williams]
[copyright 2011-12 Vicente J. Botet Escriba]
@@ -23,6 +24,11 @@
[template lockable_concept_link[link_text] [link thread.synchronization.mutex_concepts.lockable [link_text]]]
[def __lockable_concept__ [lockable_concept_link `Lockable` concept]]
[def __lockable_concept_type__ [lockable_concept_link `Lockable`]]
+[def __BasicLockable [link thread.synchronization.mutex_concepts.basic_lockable `BasicLockable`]]
+[def __Lockable [link thread.synchronization.mutex_concepts.lockable `Lockable`]]
+[def __TimedLockable [link thread.synchronization.mutex_concepts.timed_lockable `TimedLockable `]]
+[def __SharedLockable [link thread.synchronization.mutex_concepts.shared_lockable `SharedLockable `]]
+[def __UpgradeLockable [link thread.synchronization.mutex_concepts.upgrade_lockable `UpgradeLockable `]]
[template timed_lockable_concept_link[link_text] [link thread.synchronization.mutex_concepts.timed_lockable [link_text]]]
[def __timed_lockable_concept__ [timed_lockable_concept_link `TimedLockable` concept]]
@@ -37,8 +43,9 @@
[def __upgrade_lockable_concept_type__ [upgrade_lockable_concept_link `UpgradeLockable`]]
-[template lock_ref_link[link_text] [link thread.synchronization.mutex_concepts.lockable.lock [link_text]]]
+[template lock_ref_link[link_text] [link thread.synchronization.mutex_concepts.basic_lockable.lock [link_text]]]
[def __lock_ref__ [lock_ref_link `lock()`]]
+[def __lock [link thread.synchronization.mutex_concepts.basic_lockable.lock `lock`]]
[template lock_multiple_ref_link[link_text] [link thread.synchronization.lock_functions.lock_multiple [link_text]]]
[def __lock_multiple_ref__ [lock_multiple_ref_link `lock()`]]
@@ -46,50 +53,85 @@
[template try_lock_multiple_ref_link[link_text] [link thread.synchronization.lock_functions.try_lock_multiple [link_text]]]
[def __try_lock_multiple_ref__ [try_lock_multiple_ref_link `try_lock()`]]
-[template unlock_ref_link[link_text] [link thread.synchronization.mutex_concepts.lockable.unlock [link_text]]]
+[template unlock_ref_link[link_text] [link thread.synchronization.mutex_concepts.basic_lockable.unlock [link_text]]]
[def __unlock_ref__ [unlock_ref_link `unlock()`]]
+[def __unlock [link thread.synchronization.mutex_concepts.basic_lockable.unlock `unlock`]]
[template try_lock_ref_link[link_text] [link thread.synchronization.mutex_concepts.lockable.try_lock [link_text]]]
[def __try_lock_ref__ [try_lock_ref_link `try_lock()`]]
+[def __try_lock [link thread.synchronization.mutex_concepts.lockable.try_lock `try_lock`]]
[template timed_lock_ref_link[link_text] [link thread.synchronization.mutex_concepts.timed_lockable.timed_lock [link_text]]]
[def __timed_lock_ref__ [timed_lock_ref_link `timed_lock()`]]
+[def __timed_lock [link thread.synchronization.mutex_concepts.timed_lockable.timed_lock `timed_lock`]]
[def __try_lock_for [link thread.synchronization.mutex_concepts.timed_lockable.try_lock_for `try_lock_for`]]
[def __try_lock_until [link thread.synchronization.mutex_concepts.timed_lockable.try_lock_until `try_lock_until`]]
[template timed_lock_duration_ref_link[link_text] [link thread.synchronization.mutex_concepts.timed_lockable.timed_lock_duration [link_text]]]
[def __timed_lock_duration_ref__ [timed_lock_duration_ref_link `timed_lock()`]]
+[def __timed_lock_duration [link thread.synchronization.mutex_concepts.timed_lockable.timed_lock_duration `timed_lock`]]
[template lock_shared_ref_link[link_text] [link thread.synchronization.mutex_concepts.shared_lockable.lock_shared [link_text]]]
[def __lock_shared_ref__ [lock_shared_ref_link `lock_shared()`]]
+[def __lock_shared [link thread.synchronization.mutex_concepts.shared_lockable.lock_shared `lock_shared()`]]
[template unlock_shared_ref_link[link_text] [link thread.synchronization.mutex_concepts.shared_lockable.unlock_shared [link_text]]]
[def __unlock_shared_ref__ [unlock_shared_ref_link `unlock_shared()`]]
+[def __unlock_shared [link thread.synchronization.mutex_concepts.shared_lockable.unlock_shared `unlock_shared()`]]
[template try_lock_shared_ref_link[link_text] [link thread.synchronization.mutex_concepts.shared_lockable.try_lock_shared [link_text]]]
[def __try_lock_shared_ref__ [try_lock_shared_ref_link `try_lock_shared()`]]
+[def __try_lock_shared [link thread.synchronization.mutex_concepts.shared_lockable.try_lock_shared `try_lock_shared`]]
[template timed_lock_shared_ref_link[link_text] [link thread.synchronization.mutex_concepts.shared_lockable.timed_lock_shared [link_text]]]
[def __timed_lock_shared_ref__ [timed_lock_shared_ref_link `timed_lock_shared()`]]
+[def __try_lock_shared_for [link thread.synchronization.mutex_concepts.shared_lockable.try_lock_shared_for `try_lock_shared_for`]]
+[def __try_lock_shared_for [link thread.synchronization.mutex_concepts.shared_lockable.try_lock_shared_until `try_lock_shared_until`]]
[template timed_lock_shared_duration_ref_link[link_text] [link thread.synchronization.mutex_concepts.shared_lockable.timed_lock_shared_duration [link_text]]]
[def __timed_lock_shared_duration_ref__ [timed_lock_shared_duration_ref_link `timed_lock_shared()`]]
+[def __try_lock_shared_for [link thread.synchronization.mutex_concepts.shared_lockable.try_lock_shared_for `try_lock_shared_for`]]
+[def __try_lock_shared_until [link thread.synchronization.mutex_concepts.shared_lockable.try_lock_shared_until `try_lock_shared_until`]]
[template lock_upgrade_ref_link[link_text] [link thread.synchronization.mutex_concepts.upgrade_lockable.lock_upgrade [link_text]]]
[def __lock_upgrade_ref__ [lock_upgrade_ref_link `lock_upgrade()`]]
+[def __lock_upgrade [link thread.synchronization.mutex_concepts.upgrade_lockable.lock_upgrade `lock_upgrade`]]
+[def __try_lock_upgrade [link thread.synchronization.mutex_concepts.upgrade_lockable.try_lock_upgrade `try_lock_upgrade`]]
+[def __try_lock_upgrade_for [link thread.synchronization.mutex_concepts.upgrade_lockable.try_lock_upgrade_for `try_lock_upgrade_for`]]
+[def __try_lock_upgrade_until [link thread.synchronization.mutex_concepts.upgrade_lockable.try_lock_upgrade_until `try_lock_upgrade_until`]]
[template unlock_upgrade_ref_link[link_text] [link thread.synchronization.mutex_concepts.upgrade_lockable.unlock_upgrade [link_text]]]
[def __unlock_upgrade_ref__ [unlock_upgrade_ref_link `unlock_upgrade()`]]
+[def __unlock_upgrade [link thread.synchronization.mutex_concepts.upgrade_lockable.unlock_upgrade `unlock_upgrade`]]
[template unlock_upgrade_and_lock_ref_link[link_text] [link thread.synchronization.mutex_concepts.upgrade_lockable.unlock_upgrade_and_lock [link_text]]]
[def __unlock_upgrade_and_lock_ref__ [unlock_upgrade_and_lock_ref_link `unlock_upgrade_and_lock()`]]
+[def __unlock_upgrade_and_lock [link thread.synchronization.mutex_concepts.upgrade_lockable.unlock_upgrade_and_lock `unlock_upgrade_and_lock`]]
[template unlock_and_lock_upgrade_ref_link[link_text] [link thread.synchronization.mutex_concepts.upgrade_lockable.unlock_and_lock_upgrade [link_text]]]
[def __unlock_and_lock_upgrade_ref__ [unlock_and_lock_upgrade_ref_link `unlock_and_lock_upgrade()`]]
+[def __unlock_and_lock_upgrade [link thread.synchronization.mutex_concepts.upgrade_lockable.unlock_and_lock_upgrade `unlock_and_lock_upgrade`]]
[template unlock_upgrade_and_lock_shared_ref_link[link_text] [link thread.synchronization.mutex_concepts.upgrade_lockable.unlock_upgrade_and_lock_shared [link_text]]]
[def __unlock_upgrade_and_lock_shared_ref__ [unlock_upgrade_and_lock_shared_ref_link `unlock_upgrade_and_lock_shared()`]]
+[def __unlock_upgrade_and_lock_shared [link thread.synchronization.mutex_concepts.upgrade_lockable.unlock_upgrade_and_lock_shared `unlock_upgrade_and_lock_shared`]]
+
+
+[def __try_unlock_shared_and_lock [link thread.synchronization.mutex_concepts.upgrade_lockable.try_unlock_shared_and_lock `try_unlock_shared_and_lock`]]
+[def __try_unlock_shared_and_lock_for [link thread.synchronization.mutex_concepts.upgrade_lockable.try_unlock_shared_and_lock_for `try_unlock_shared_and_lock_for`]]
+[def __try_unlock_shared_and_lock_until [link thread.synchronization.mutex_concepts.upgrade_lockable.try_unlock_shared_and_lock_until `try_unlock_shared_and_lock_until`]]
+
+[def __unlock_and_lock_shared [link thread.synchronization.mutex_concepts.upgrade_lockable.unlock_and_lock_shared `unlock_and_lock_shared`]]
+
+[def __try_unlock_shared_and_lock_upgrade [link thread.synchronization.mutex_concepts.upgrade_lockable.try_unlock_shared_and_lock_upgrade `try_unlock_shared_and_lock_upgrade`]]
+[def __try_unlock_shared_and_lock_upgrade_for [link thread.synchronization.mutex_concepts.upgrade_lockable.try_unlock_shared_and_lock_upgrade_for `try_unlock_shared_and_lock_upgrade_for`]]
+[def __try_unlock_shared_and_lock_upgrade_until [link thread.synchronization.mutex_concepts.upgrade_lockable.try_unlock_shared_and_lock_upgrade_until `try_unlock_shared_and_lock_upgrade_until`]]
+
+[def __try_unlock_upgrade_and_lock [link thread.synchronization.mutex_concepts.upgrade_lockable.try_unlock_upgrade_and_lock `try_unlock_upgrade_and_lock`]]
+[def __try_unlock_upgrade_and_lock_for [link thread.synchronization.mutex_concepts.upgrade_lockable.try_unlock_upgrade_and_lock_for `try_unlock_upgrade_and_lock_for`]]
+[def __try_unlock_upgrade_and_lock_until [link thread.synchronization.mutex_concepts.upgrade_lockable.try_unlock_upgrade_and_lock_until `try_unlock_upgrade_and_lock_until`]]
+
[template owns_lock_ref_link[link_text] [link thread.synchronization.locks.unique_lock.owns_lock [link_text]]]
[def __owns_lock_ref__ [owns_lock_ref_link `owns_lock()`]]
@@ -119,6 +161,8 @@
[def __shared_lock__ [link thread.synchronization.locks.shared_lock `boost::shared_lock`]]
[def __upgrade_lock__ [link thread.synchronization.locks.upgrade_lock `boost::upgrade_lock`]]
[def __upgrade_to_unique_lock__ [link thread.synchronization.locks.upgrade_to_unique_lock `boost::upgrade_to_unique_lock`]]
+[def __reverse_lock [link thread.synchronization.other_locks.reverse_lock `reverse_lock`]]
+[def __shared_lock_guard [link thread.synchronization.other_locks.shared_lock_guard `shared_lock_guard`]]
[def __thread__ [link thread.thread_management.thread `boost::thread`]]
@@ -138,6 +182,8 @@
[def __sleep__ [link thread.thread_management.this_thread.sleep `boost::this_thread::sleep()`]]
[def __sleep_for [link thread.thread_management.this_thread.sleep_for `sleep_for`]]
[def __sleep_until [link thread.thread_management.this_thread.sleep_until `sleep_until`]]
+[def __yield [link thread.thread_management.this_thread.yield `yield`]]
+[def __get_id [link thread.thread_management.thread.get_id `get_id`]]
[def __interruption_enabled__ [link thread.thread_management.this_thread.interruption_enabled `boost::this_thread::interruption_enabled()`]]
[def __interruption_requested__ [link thread.thread_management.this_thread.interruption_requested `boost::this_thread::interruption_requested()`]]
@@ -188,6 +234,8 @@
[include time.qbk]
+[include emulations.qbk]
+
[include acknowledgements.qbk]
[include compliance.qbk]
Modified: trunk/libs/thread/doc/thread_ref.qbk
==============================================================================
--- trunk/libs/thread/doc/thread_ref.qbk (original)
+++ trunk/libs/thread/doc/thread_ref.qbk 2012-03-31 03:37:59 EDT (Sat, 31 Mar 2012)
@@ -10,28 +10,37 @@
[section:synopsis Synopsis]
+ #include <boost/thread/thread.hpp>
+
namespace boost
{
class thread;
- void swap(thread& lhs,thread& rhs);
+ void swap(thread& lhs,thread& rhs) noexcept;
+
namespace this_thread
{
thread::id get_id() noexcept;
template<typename TimeDuration>
- void sleep(TimeDuration const& rel_time); // DEPRECATED
- void sleep(system_time const& abs_time) // DEPRECATED
+ void sleep(TimeDuration const& rel_time); // DEPRECATED V2
+ void sleep(system_time const& abs_time) // DEPRECATED V2
void yield() noexcept;
template <class Clock, class Duration>
void sleep_until(const chrono::time_point<Clock, Duration>& abs_time);
template <class Rep, class Period>
void sleep_for(const chrono::duration<Rep, Period>& rel_time);
- void interruption_point();
- bool interruption_requested();
- bool interruption_enabled();
- class disable_interruption;
- class restore_interruption;
+ template<typename Callable>
+ void at_thread_exit(Callable func); // EXTENSION
+
+ void interruption_point(); // EXTENSION
+ bool interruption_requested() noexcept; // EXTENSION
+ bool interruption_enabled() noexcept; // EXTENSION
+ class disable_interruption; // EXTENSION
+ class restore_interruption; // EXTENSION
+
}
+ class thread_group; // EXTENSION
+
}
[endsect] [/section:synopsis Synopsis]
@@ -358,22 +367,30 @@
template <class F>
explicit thread(F f);
+ template <class F>
+ thread(F &&f);
template <class F,class A1,class A2,...>
thread(F f,A1 a1,A2 a2,...);
+ // template <class F, class ...Args>
+ // explicit thread(F&& f, Args&&... args); // NOT YET IMPLEMENTED
template <class F>
- thread(F &&f);
-
- template <class F, class ...Args> explicit thread(F&& f, Args&&... args);
+ explicit thread(attributes& attrs, F f); // EXTENSION
+ template <class F>
+ thread(attributes& attrs, F &&f); // EXTENSION
+ // template <class F, class ...Args>
+ // explicit thread(attributes& attrs, F&& f, Args&&... args); // NOT YET IMPLEMENTED
// move support
- thread(thread && x);
- thread& operator=(thread && x);
+ thread(thread && x) noexcept;
+ thread& operator=(thread && x) noexcept;
void swap(thread& x) noexcept;
class id;
+ class attributes;
+
id get_id() const noexcept;
bool joinable() const noexcept;
@@ -382,9 +399,9 @@
template<typename TimeDuration>
bool timed_join(TimeDuration const& rel_time); // DEPRECATED V2
template <class Rep, class Period>
- bool try_join_for(const chrono::duration<Rep, Period>& rel_time);
+ bool try_join_for(const chrono::duration<Rep, Period>& rel_time); // EXTENSION
template <class Clock, class Duration>
- bool try_join_until(const chrono::time_point<Clock, Duration>& t);
+ bool try_join_until(const chrono::time_point<Clock, Duration>& t); // EXTENSION
void detach();
@@ -393,10 +410,9 @@
typedef platform-specific-type native_handle_type;
native_handle_type native_handle();
- void interrupt();
- bool interruption_requested() const;
+ void interrupt(); // EXTENSION
+ bool interruption_requested() const noexcept; // EXTENSION
- // backwards compatibility
bool operator==(const thread& other) const; // DEPRECATED V2
bool operator!=(const thread& other) const; // DEPRECATED V2
@@ -405,16 +421,18 @@
};
- void swap(thread& lhs,thread& rhs) noexcep;
+ void swap(thread& lhs,thread& rhs) noexcept;
[section:default_constructor Default Constructor]
- thread() noexcep;
+ thread() noexcept;
[variablelist
[[Effects:] [Constructs a __thread__ instance that refers to __not_a_thread__.]]
+[[Postconditions:] [`this->get_id()==thread::id()`]]
+
[[Throws:] [Nothing]]
]
@@ -429,7 +447,7 @@
[[Effects:] [Transfers ownership of the thread managed by `other` (if any) to the newly constructed __thread__ instance.]]
-[[Postconditions:] [`other->get_id()==thread::id()`]]
+[[Postconditions:] [`other.get_id()==thread::id()` and `get_id()` returns the value of `other.get_id()` prior to the construction]]
[[Throws:] [Nothing]]
@@ -447,7 +465,7 @@
any) to `*this`. If there was a thread previously associated with
`*this` then that thread is detached.]]
-[[Postconditions:] [`other->get_id()==thread::id()`]]
+[[Postconditions:] [`other->get_id()==thread::id()` and `get_id()` returns the value of `other.get_id()` prior to the assignment.]]
[[Throws:] [Nothing]]
@@ -462,13 +480,96 @@
[variablelist
+[[Requires:] [`Callable` must by Copyable and `func()` must be a valid expression.]]
+
+[[Effects:] [`func` is copied into storage managed internally by the thread library, and that copy is invoked on a newly-created
+thread of execution. If this invocation results in an exception being propagated into the internals of the thread library that is
+not of type __thread_interrupted__, then `std::terminate()` will be called. Any return value from this invocation is ignored.]]
+
+[[Postconditions:] [`*this` refers to the newly created thread of execution and `this->get_id()!=thread::id()`.]]
+
+[[Throws:] [__thread_resource_error__ if an error occurs. ]]
+
+[[Error Conditions:] [
+
+[*resource_unavailable_try_again] : the system lacked the necessary resources to create an- other thread, or the system-imposed limit on the number of threads in a process would be exceeded.
+
+]]
+
+]
+
+[endsect]
+
+[section:attr_callable_constructor Thread Attributes Constructor EXTENSION]
+
+ template<typename Callable>
+ thread(attributes& attrs, Callable func);
+
+[variablelist
+
[[Preconditions:] [`Callable` must by copyable.]]
[[Effects:] [`func` is copied into storage managed internally by the thread library, and that copy is invoked on a newly-created
+thread of execution with the specified attributes. If this invocation results in an exception being propagated into the internals of the thread library that is
+not of type __thread_interrupted__, then `std::terminate()` will be called. Any return value from this invocation is ignored.
+If the attributes declare the native thread as detached, the boost::thread will be detached.]]
+
+[[Postconditions:] [`*this` refers to the newly created thread of execution and `this->get_id()!=thread::id()`.]]
+
+[[Throws:] [__thread_resource_error__ if an error occurs. ]]
+
+[[Error Conditions:] [
+
+[*resource_unavailable_try_again] : the system lacked the necessary resources to create an- other thread, or the system-imposed limit on the number of threads in a process would be exceeded.
+
+]]
+
+]
+
+[endsect]
+
+[section:callable_move_constructor Thread Callable Move Constructor]
+
+ template<typename Callable>
+ thread(Callable &&func);
+
+[variablelist
+
+[[Preconditions:] [`Callable` must by Movable.]]
+
+[[Effects:] [`func` is moved into storage managed internally by the thread library, and that copy is invoked on a newly-created
thread of execution. If this invocation results in an exception being propagated into the internals of the thread library that is
-not of type __thread_interrupted__, then `std::terminate()` will be called.]]
+not of type __thread_interrupted__, then `std::terminate()` will be called. Any return value from this invocation is ignored.]]
-[[Postconditions:] [`*this` refers to the newly created thread of execution.]]
+[[Postconditions:] [`*this` refers to the newly created thread of execution and `this->get_id()!=thread::id()`.]]
+
+[[Throws:] [__thread_resource_error__ if an error occurs. ]]
+
+[[Error Conditions:] [
+
+[*resource_unavailable_try_again] : the system lacked the necessary resources to create an- other thread, or the system-imposed limit on the number of threads in a process would be exceeded.
+
+]]
+
+]
+
+[endsect]
+
+[section:attr_callable_move_constructor Thread Attributes Move Constructor EXTENSION]
+
+ template<typename Callable>
+ thread(attributes& attrs, Callable func);
+
+[variablelist
+
+[[Preconditions:] [`Callable` must by copyable.]]
+
+[[Effects:] [`func` is copied into storage managed internally by the thread library, and that copy is invoked on a newly-created
+thread of execution with the specified attributes. If this invocation results in an exception being propagated into the internals of the thread library that is
+not of type __thread_interrupted__, then `std::terminate()` will be called. Any return value from this invocation is ignored.
+If the attributes declare the native thread as detached, the boost::thread will be detached.]]
+
+[[Postconditions:] [`*this` refers to the newly created thread of execution and `this->get_id()!=thread::id()`.]]
[[Throws:] [__thread_resource_error__ if an error occurs. ]]
@@ -482,6 +583,7 @@
[endsect]
+
[section:multiple_argument_constructor Thread Constructor with arguments]
template <class F,class A1,class A2,...>
@@ -526,6 +628,25 @@
[endsect]
+[/
+[section:v2_destructor V2 Thread Destructor]
+
+ ~thread();
+
+[variablelist
+
+[[Effects:] [If `*this` has an associated thread of execution, calls terminate. Destroys `*this`.]]
+
+[[Note:] [Either implicitly detaching or joining a `joinable()` thread in its destructor could result in difficult to debug correctness (for `detach`) or performance (for `join`) bugs encountered only when an exception is raised. Thus the programmer must ensure that the destructor is never executed while the thread is still joinable.]]
+
+
+[[Throws:] [Nothing.]]
+
+]
+
+[endsect]
+]
+
[section:joinable Member function `joinable()`]
bool joinable() const noexcept;
@@ -547,7 +668,7 @@
[variablelist
-[[Preconditions:] [`this->get_id()!=boost::this_thread::get_id()`]]
+[[Preconditions:] [the thread is joinable.]]
[[Effects:] [If `*this` refers to a thread of execution, waits for that thread of execution to complete.]]
@@ -614,7 +735,7 @@
[endsect]
-[section:try_join_for Member function `try_join_for()`]
+[section:try_join_for Member function `try_join_for()` EXTENSION]
template <class Rep, class Period>
bool try_join_for(const chrono::duration<Rep, Period>& rel_time);
@@ -653,7 +774,7 @@
[endsect]
-[section:try_join_until Member function `try_join_until()`]
+[section:try_join_until Member function `try_join_until()` EXTENSION]
template <class Clock, class Duration>
bool try_join_until(const chrono::time_point<Clock, Duration>& abs_time);
@@ -696,11 +817,13 @@
[section:detach Member function `detach()`]
- void detach();
+ void detach() noexcept;
[variablelist
-[[Effects:] [If `*this` refers to a thread of execution, that thread of execution becomes detached, and no longer has an associated __thread__ object.]]
+[[Preconditions:] [the thread is joinable.]]
+
+[[Effects:] [The thread of execution becomes detached, and no longer has an associated __thread__ object.]]
[[Postconditions:] [`*this` no longer refers to any thread of execution.]]
@@ -774,7 +897,7 @@
[endsect]
-[section:equals `operator==`]
+[section:equals `operator==` DEPRECATED V2]
bool operator==(const thread& other) const;
@@ -782,11 +905,13 @@
[[Returns:] [`get_id()==other.get_id()`]]
+[[See:] [Use `a.__get_id()==b.__get_id()` instead]]
+
]
[endsect]
-[section:not_equals `operator!=`]
+[section:not_equals `operator!=` DEPRECATED V2]
bool operator!=(const thread& other) const;
@@ -794,6 +919,8 @@
[[Returns:] [`get_id()!=other.get_id()`]]
+[[See:] [Use `a.__get_id()!=b.__get_id()` instead`]]
+
]
[endsect]
@@ -810,6 +937,8 @@
[[Notes:] [`sleep()` is one of the predefined __interruption_points__.]]
+[[See:] [Use `this_thread::__sleep_for()` or `this_thread::__sleep_until()`]]
+
]
[endsect]
@@ -822,6 +951,8 @@
[[Effects:] [See [link thread.thread_management.this_thread.yield `boost::this_thread::yield()`].]]
+[[See:] [Use `this_thread::__yield()`]]
+
]
[endsect]
@@ -858,27 +989,6 @@
[endsect]
-[/
-[section:non_member_move Non-member function `move()`]
-
- #include <boost/thread/thread.hpp>
-
- detail::thread_move_t<thread> move(detail::thread_move_t<thread> t)
-
-[variablelist
-
-[[Returns:] [`t`.]]
-
-]
-
-Enables moving thread objects. e.g.
-
- extern void some_func();
- boost::thread t(some_func);
- boost::thread t2(boost::move(t)); // transfer thread from t to t2
-
-[endsect]
-]
[section:id Class `boost::thread::id`]
@@ -1026,7 +1136,87 @@
[endsect]
+[section:attributes Class `boost::thread::attributes` EXTENSION]
+
+ class thread::attributes {
+ public:
+ attributes() noexcept;
+ ~ attributes()=default;
+ // stack
+ void set_stack_size(std::size_t size) noexcept;
+ std::size_t get_stack_size() const noexcept;
+
+ #if defined BOOST_THREAD_DEFINES_THREAD_ATTRIBUTES_NATIVE_HANDLE
+ typedef platform-specific-type native_handle_type;
+ native_handle_type* native_handle() noexcept;
+ const native_handle_type* native_handle() const noexcept;
+ #endif
+
+ };
+
+[section:constructor Default constructor]
+
+ thread_attributes() noexcept;
+
+[variablelist
+
+[[Effects:] [Constructs a thread atrributes instance with its default values.]]
+
+[[Throws:] [Nothing]]
+
+]
+
+[endsect]
+
+[section: set_stack_size Member function `set_stack_size()`]
+
+ void set_stack_size(std::size_t size) noexcept;
+
+[variablelist
+
+[[Effects:] [Stores the stack size to be used to create a thread. This is an hint that the implementation can choose a better size if to small or too big or not aligned to a page.]]
+
+[[Postconditions:] [`this-> get_stack_size()` returns the chosen stack size.]]
+
+[[Throws:] [Nothing.]]
+
+]
+
+[endsect]
+
+[section:get_stack_size Member function `get_stack_size()`]
+
+ std::size_t get_stack_size() const noexcept;
+
+[variablelist
+
+[[Returns:] [The stack size to be used on the creation of a thread. Note that this function can return 0 meaning the default.]]
+
+[[Throws:] [Nothing.]]
+
+]
+
+[endsect]
+
+[section:nativehandle Member function `native_handle()`]
+
+ typedef platform-specific-type native_handle_type;
+ typedef platform-specific-type native_handle_type;
+ native_handle_type* native_handle() noexcept;
+ const native_handle_type* native_handle() const noexcept;
+
+[variablelist
+
+[[Effects:] [Returns an instance of `native_handle_type` that can be used with platform-specific APIs to manipulate the underlying
+thread attributes implementation. If no such instance exists, `native_handle()` and `native_handle_type` are not present and `BOOST_THREAD_DEFINES_THREAD_ATTRIBUTES_NATIVE_HANDLE` is not defined.]]
+
+[[Throws:] [Nothing.]]
+
+]
+
[endsect]
+[endsect] [/ thread::attributes ]
+[endsect] [/ thread ]
[section:this_thread Namespace `this_thread`]
@@ -1043,11 +1233,14 @@
template <class Rep, class Period>
void sleep_for(const chrono::duration<Rep, Period>& rel_time);
- void interruption_point();
- bool interruption_requested();
- bool interruption_enabled();
- class disable_interruption;
- class restore_interruption;
+ template<typename Callable>
+ void at_thread_exit(Callable func); // EXTENSION
+
+ void interruption_point(); // EXTENSION
+ bool interruption_requested() noexcept; // EXTENSION
+ bool interruption_enabled() noexcept; // EXTENSION
+ class disable_interruption; // EXTENSION
+ class restore_interruption; // EXTENSION
}
}
@@ -1070,7 +1263,7 @@
[endsect]
-[section:interruption_point Non-member function `interruption_point()`]
+[section:interruption_point Non-member function `interruption_point()` EXTENSION]
#include <boost/thread/thread.hpp>
@@ -1089,13 +1282,13 @@
[endsect]
-[section:interruption_requested Non-member function `interruption_requested()`]
+[section:interruption_requested Non-member function `interruption_requested()` EXTENSION]
#include <boost/thread/thread.hpp>
namespace this_thread
{
- bool interruption_requested();
+ bool interruption_requested() noexcept;
}
[variablelist
@@ -1108,13 +1301,13 @@
[endsect]
-[section:interruption_enabled Non-member function `interruption_enabled()`]
+[section:interruption_enabled Non-member function `interruption_enabled()` EXTENSION]
#include <boost/thread/thread.hpp>
namespace this_thread
{
- bool interruption_enabled();
+ bool interruption_enabled() noexcept;
}
[variablelist
@@ -1148,6 +1341,8 @@
[[Notes:] [`sleep()` is one of the predefined __interruption_points__.]]
+[[See:] [Use `__sleep_for()` and `__sleep_until()` instead.]]
+
]
[endsect]
@@ -1207,7 +1402,7 @@
namespace this_thread
{
- void yield();
+ void yield() noexcept;
}
[variablelist
@@ -1220,7 +1415,7 @@
[endsect]
-[section:disable_interruption Class `disable_interruption`]
+[section:disable_interruption Class `disable_interruption` EXTENSION]
#include <boost/thread/thread.hpp>
@@ -1229,8 +1424,10 @@
class disable_interruption
{
public:
- disable_interruption();
- ~disable_interruption();
+ disable_interruption(const disable_interruption&) = delete;
+ disable_interruption& operator=(const disable_interruption&) = delete;
+ disable_interruption() noexcept;
+ ~disable_interruption() noexcept;
};
}
@@ -1239,7 +1436,7 @@
[section:constructor Constructor]
- disable_interruption();
+ disable_interruption() noexcept;
[variablelist
@@ -1255,7 +1452,7 @@
[section:destructor Destructor]
- ~disable_interruption();
+ ~disable_interruption() noexcept;
[variablelist
@@ -1273,7 +1470,7 @@
[endsect]
-[section:restore_interruption Class `restore_interruption`]
+[section:restore_interruption Class `restore_interruption` EXTENSION]
#include <boost/thread/thread.hpp>
@@ -1282,8 +1479,10 @@
class restore_interruption
{
public:
- explicit restore_interruption(disable_interruption& disabler);
- ~restore_interruption();
+ restore_interruption(const restore_interruption&) = delete;
+ restore_interruption& operator=(const restore_interruption&) = delete;
+ explicit restore_interruption(disable_interruption& disabler) noexcept;
+ ~restore_interruption() noexcept;
};
}
@@ -1293,7 +1492,7 @@
[section:constructor Constructor]
- explicit restore_interruption(disable_interruption& disabler);
+ explicit restore_interruption(disable_interruption& disabler) noexcept;
[variablelist
@@ -1311,7 +1510,7 @@
[section:destructor Destructor]
- ~restore_interruption();
+ ~restore_interruption() noexcept;
[variablelist
@@ -1329,7 +1528,7 @@
[endsect]
-[section:atthreadexit Non-member function template `at_thread_exit()`]
+[section:atthreadexit Non-member function template `at_thread_exit()` EXTENSION]
#include <boost/thread/thread.hpp>
Modified: trunk/libs/thread/doc/time.qbk
==============================================================================
--- trunk/libs/thread/doc/time.qbk (original)
+++ trunk/libs/thread/doc/time.qbk 2012-03-31 03:37:59 EDT (Sat, 31 Mar 2012)
@@ -5,19 +5,31 @@
http://www.boost.org/LICENSE_1_0.txt).
]
-[section:time Date and Time Requirements]
+[section:time Time Requirements]
-As of Boost 1.35.0, the __boost_thread__ library uses the [link date_time Boost.Date_Time] library for all operations that require a
-time out. These include (but are not limited to):
+As of Boost 1.50.0, the __boost_thread__ library uses Boost.Chrono library for all operations that require a
+time out as defined in the standard c++11. These include (but are not limited to):
+
+* __sleep_for
+* __sleep_until
+* __try_join_for
+* __try_join_until
+* __wait_for
+* __wait_until
+* __try_lock_for
+* __try_lock_until
+
+[section:deprecated Deprecated]
+The time related functions introduced in Boost 1.35.0, using the [link date_time Boost.Date_Time] library are deprecated. These include (but are not limited to):
* __sleep__
* __timed_join__
* __cond_timed_wait__
* __timed_lock_ref__
-For the overloads that accept an absolute time parameter, an object of type [link thread.time.system_time `boost::system_time`] is
+For the overloads that accept an absolute time parameter, an object of type [link thread.time.deprecated.system_time `boost::system_time`] is
required. Typically, this will be obtained by adding a duration to the current time, obtained with a call to [link
-thread.time.get_system_time `boost::get_system_time()`]. e.g.
+thread.time.deprecated.get_system_time `boost::get_system_time()`]. e.g.
boost::system_time const timeout=boost::get_system_time() + boost::posix_time::milliseconds(500);
@@ -70,6 +82,7 @@
]
[endsect]
+[endsect]
[endsect]
\ No newline at end of file
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk