Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r65400 - in sandbox/sync/libs/sync/doc: . html
From: vicente.botet_at_[hidden]
Date: 2010-09-12 14:55:32

Next message: vicente.botet_at_[hidden]: "[Boost-commit] svn:boost r65401 - in sandbox/sync/boost/sync: . locks"
Previous message: vicente.botet_at_[hidden]: "[Boost-commit] svn:boost r65399 - sandbox/sync/boost"

Author: viboes
Date: 2010-09-12 14:55:30 EDT (Sun, 12 Sep 2010)
New Revision: 65400
URL: http://svn.boost.org/trac/boost/changeset/65400

Log:
Boost.Sync: Add doc
Added:
   sandbox/sync/libs/sync/doc/Jamfile.v2 (contents, props changed)
   sandbox/sync/libs/sync/doc/html/
   sandbox/sync/libs/sync/doc/html/index.html (contents, props changed)
   sandbox/sync/libs/sync/doc/html/standalone_HTML.manifest (contents, props changed)
   sandbox/sync/libs/sync/doc/index.html (contents, props changed)
   sandbox/sync/libs/sync/doc/sync.qbk (contents, props changed)

Added: sandbox/sync/libs/sync/doc/Jamfile.v2
==============================================================================
--- (empty file)
+++ sandbox/sync/libs/sync/doc/Jamfile.v2 2010-09-12 14:55:30 EDT (Sun, 12 Sep 2010)
@@ -0,0 +1,74 @@
+# Boost.Sync library documentation Jamfile ---------------------------------
+#
+# Copyright Vicente J. Botet Escriba 2010. Use, modification and
+# distribution is subject to 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)
+#
+# See http://www.boost.org for updates, documentation, and revision history.
+
+#import doxygen ;
+import quickbook ;
+
+#doxygen autodoc
+# :
+# [ glob ../../../boost/chrono/*.hpp ]
+# [ glob ../../../boost/chrono/allocators/*.hpp ]
+# :
+# <doxygen:param>EXTRACT_ALL=NO
+# <doxygen:param>HIDE_UNDOC_MEMBERS=YES
+# <doxygen:param>EXTRACT_PRIVATE=NO
+# <doxygen:param>EXPAND_ONLY_PREDEF=YES
+# <doxygen:param>PREDEFINED=BOOST_INTERPROCESS_DOXYGEN_INVOKED
+# <xsl:param>"boost.doxygen.reftitle=Boost.Chrono Reference"
+# ;
+
+#path-constant boost-images : ../../../doc/src/images ;
+
+xml sync : sync.qbk ;
+
+boostbook standalone
+ :
+ sync
+ :
+ # HTML options first:
+ # Use graphics not text for navigation:
+ <xsl:param>navig.graphics=1
+ # How far down we chunk nested sections, basically all of them:
+ <xsl:param>chunk.section.depth=0
+ # Don't put the first section on the same page as the TOC:
+ <xsl:param>chunk.first.sections=1
+ # How far down sections get TOC's
+ <xsl:param>toc.section.depth=4
+ # Max depth in each TOC:
+ <xsl:param>toc.max.depth=2
+ # How far down we go with TOC's
+ <xsl:param>generate.section.toc.level=10
+ # Path for links to Boost:
+ <xsl:param>boost.root=../../../..
+ # Path for libraries index:
+ <xsl:param>boost.libraries=../../../../libs/libraries.htm
+ # Use the main Boost stylesheet:
+ <xsl:param>html.stylesheet=../../../../doc/html/boostbook.css
+
+ # PDF Options:
+ # TOC Generation: this is needed for FOP-0.9 and later:
+ #<xsl:param>fop1.extensions=1
+ # Or enable this if you're using XEP:
+ <xsl:param>xep.extensions=1
+ # TOC generation: this is needed for FOP 0.2, but must not be set to zero for FOP-0.9!
+ <xsl:param>fop.extensions=0
+ # No indent on body text:
+ <xsl:param>body.start.indent=0pt
+ # Margin size:
+ <xsl:param>page.margin.inner=0.5in
+ # Margin size:
+ <xsl:param>page.margin.outer=0.5in
+ # Yes, we want graphics for admonishments:
+ <xsl:param>admon.graphics=1
+ # Set this one for PDF generation *only*:
+ # default pnd graphics are awful in PDF form,
+ # better use SVG's instead:
+ <format>pdf:<xsl:param>admon.graphics.extension=".svg"
+ <format>pdf:<xsl:param>admon.graphics.path=$(boost-images)/
+ ;

Added: sandbox/sync/libs/sync/doc/html/index.html
==============================================================================
--- (empty file)
+++ sandbox/sync/libs/sync/doc/html/index.html 2010-09-12 14:55:30 EDT (Sun, 12 Sep 2010)
@@ -0,0 +1,2035 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Boost.Sync 0.1.0</title>
+<link rel="stylesheet" href="../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
+<link rel="start" href="index.html" title="Boost.Sync 0.1.0">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav"></div>
+<div class="article" lang="en">
+<div class="titlepage">
+<div>
+<div><h2 class="title">
+<a name="boost_sync"></a>Boost.Sync 0.1.0</h2></div>
+<div><div class="authorgroup"><div class="author"><h3 class="author">
+Vicente J. Botet Escriba
+</h3></div></div></div>
+<div>Copyright © 2009 -2010 Vicente J. Botet Escriba</div>
+<div><div class="legalnotice">
+<a name="id4987067"></a>
+ 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)
+ 
+</div></div>
+</div>
+<hr>
+</div>
+<div class="toc">
+Table of Contents
+<dl>
+<dt>Overview</dt>
+<dd><dl>
+<dt>Motivation</dt>
+<dt>Description</dt>
+</dl></dd>
+<dt> Users'Guide</dt>
+<dd><dl>
+<dt> Getting Started</dt>
+<dt>Tutorial</dt>
+<dt>Examples</dt>
+<dt> External Resources</dt>
+</dl></dd>
+<dt> Reference </dt>
+<dd><dl>
+<dt> Header <boost/sync.hpp></dt>
+<dt> Header <boost/sync/lockable_traits.hpp></dt>
+<dt><a href="index.html#boost_sync.reference.Locables"> Requirements for Lockable
+ types </a></dt>
+<dt> Header <boost/sync/lockable_concepts.hpp></dt>
+<dt> Header <boost/sync/locks.hpp></dt>
+</dl></dd>
+<dt>Appendices</dt>
+<dd><dl>
+<dt> Appendix A: History</dt>
+<dt> Appendix B: Rationale</dt>
+<dt><a href="index.html#boost_sync.appendices.implementation"> Appendix C: Implementation
+ Notes</a></dt>
+<dt> Appendix D: FAQ</dt>
+<dt><a href="index.html#boost_sync.appendices.acknowledgements"> Appendix E:
+ Acknowledgements</a></dt>
+<dt> Appendix F: Tests</dt>
+<dt> Appendix G: Tickets</dt>
+</dl></dd>
+</dl>
+</div>
+<div class="warning"><table border="0" summary="Warning">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../doc/src/images/warning.png"></td>
+<th align="left">Warning</th>
+</tr>
+<tr><td align="left" valign="top">
+ Sync is not part of the Boost libraries.
+ </td></tr>
+</table></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="boost_sync.overview"></a>Overview
+</h2></div></div></div>
+<div class="toc"><dl>
+<dt>Motivation</dt>
+<dt>Description</dt>
+</dl></div>
+<a name="boost_sync.overview.how_to_use_this_documentation"></a><h3>
+<a name="id4986973"></a>
+ <a href="index.html#boost_sync.overview.how_to_use_this_documentation">How to Use
+ This Documentation</a>
+ </h3>
+
+ This documentation makes use of the following naming and formatting conventions.
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Code is in <code class="computeroutput">fixed width
+ font</code> and is syntax-highlighted.
+ </li>
+<li>
+ Replaceable text that you will need to supply is in <code>italics</code>.
+ </li>
+<li>
+ Free functions are rendered in the code font followed by (), as in free_function().
+ </li>
+<li>
+ If a name refers to a class template, it is specified like this: <code class="computeroutput">class_template<></code>;
+ that is, it is in code font and its name is followed by <code class="computeroutput"><></code>
+ to indicate that it is a class template.
+ </li>
+<li>
+ If a name refers to a function-like macro, it is specified like this:
+ <code class="computeroutput">MACRO()</code>;
+ that is, it is uppercase in code font and its name is followed by <code class="computeroutput">()</code> to indicate that it is a function-like
+ macro. Object-like macros appear without the trailing <code class="computeroutput">()</code>.
+ </li>
+<li>
+ Names that refer to concepts in the generic programming
+ sense are specified in CamelCase.
+ </li>
+</ul></div>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top">
+ In addition, notes such as this one specify non-essential information that
+ provides additional background or rationale.
+ </td></tr>
+</table></div>
+
+ Finally, you can mentally add the following to any code fragments in this document:
+ 
+<pre class="programlisting">// Include all of Sync files
+#include <boost/sync.hpp>
+using namespace boost::sync;
+</pre>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_sync.overview.motivation"></a>Motivation
+</h3></div></div></div>
+
+ The goal of Boost.Sync is to remove the syntactic differences between the
+ synchronization mechanisms of the Boost.Thread and Boost::Interprocess libraries
+ and be a holder of common mechanism and algorithms working on the common
+ concepts.
+ 
+
+ The differences I have identified up to now are:
+ 
+<pre class="programlisting">* The scoped locks can be initialized with static const variables in order to overload the constructor for lock adoption, lock deferral or try to lock. Even if the name of these variables is almost the same, these variables live in different namespace. It would be nice if both libraries use <spa
n class="identifier">the same type and the same variables.
+
+* The shared mutex provide similar service with different names. In addition each implementation provide some functions that are not provided by the other.
+
+* The scoped locks live in a different namespace and some have different names with the same semantic. IMO these should be shared.
+
+* The exception thrown lives in a different name space and different names with equivalent semantics If we follow the C++0x standard the exception to throw should be system_error. Both libraries could adapt his hierarchy to Boost.System. The drawback is that users of Boost.Thread and Boost.</s
pan>Interprocess will need to link with Boost.System which is not a header only library.
+
+* The move semantics (&&) of Boost.Thread should be adapted to the forthcoming Boost.Move library as soon as integrated on the release branch. Boost.Interprocess uses already a detail implementation equivalent to the provided by Boost.Move, so the change will be simpler.
+
+* Adapt both libraries interface to use Boost.Chrono, which is yet a non header only library, once it is accepted.
+</pre>
+
+ Of course, this needs some adaptation of the Thread and Interprocess libraries.
+ 
+
+ This library proposes some classes that make easier to write code that can
+ be used indistinguishably with thread or interprocess synchronization mechanisms.
+ This section is inspired on the work from C++ Threading
+ - A Generic-Programming Approach - Kevlin Henney.
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_sync.overview.description"></a>Description
+</h3></div></div></div>
+
+ Boost.Sync provides a uniform usage of Boost.Thread
+ and Boost.Interprocess synchronization mechanisms based on:
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ share the lock options between both libraries
+ </li>
+<li>
+ lockable concepts.
+ </li>
+<li>
+ lockable traits
+ </li>
+<li>
+ null_mutex and null_condition classes,
+ </li>
+</ul></div>
+</div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="boost_sync.users_guide"></a> Users'Guide
+</h2></div></div></div>
+<div class="toc"><dl>
+<dt> Getting Started</dt>
+<dd><dl><dt><a href="index.html#boost_sync.users_guide.getting_started.install"> Installing
+ Sync</a></dt></dl></dd>
+<dt>Tutorial</dt>
+<dd><dl>
+<dt><a href="index.html#boost_sync.users_guide.tutorial.lockable_traits">Lockable
+ traits</a></dt>
+<dt><a href="index.html#boost_sync.users_guide.tutorial.lockable_generators">Lockable
+ generators</a></dt>
+<dt><a href="index.html#boost_sync.users_guide.tutorial.lockable_concepts">Lockable
+ concepts</a></dt>
+</dl></dd>
+<dt>Examples</dt>
+<dt> External Resources</dt>
+</dl></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_sync.users_guide.getting_started"></a> Getting Started
+</h3></div></div></div>
+<div class="toc"><dl><dt><a href="index.html#boost_sync.users_guide.getting_started.install"> Installing
+ Sync</a></dt></dl></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.users_guide.getting_started.install"></a><a href="index.html#boost_sync.users_guide.getting_started.install" title=" Installing
+ Sync"> Installing
+ Sync</a>
+</h4></div></div></div>
+<a name="boost_sync.users_guide.getting_started.install.getting_boost_sync_"></a><h5>
+<a name="id4942576"></a>
+ <a href="index.html#boost_sync.users_guide.getting_started.install.getting_boost_sync_">Getting
+ Boost.Sync </a>
+ </h5>
+
+ You can get the last stable release of Boost.Sync
+ by downloading <code class="literal">sync.zip</code> from the <a href="http://www.boost-consulting.com/vault/index.php?directory=ConcurrentProgramming" target="_top">Boost
+ Vault</a>.
+ 
+
+ You can also access the latest (unstable?) state from the <a href="https://svn.boost.org/svn/boost/sandbox/sync" target="_top">Boost
+ Sandbox</a>. Just go to here
+ and follow the instructions there for anonymous SVN access.
+ 
+<a name="boost_sync.users_guide.getting_started.install.where_to_install_boost_sync__"></a><h5>
+<a name="id4942640"></a>
+ <a href="index.html#boost_sync.users_guide.getting_started.install.where_to_install_boost_sync__">Where
+ to install Boost.Sync? </a>
+ </h5>
+
+ The simple way is to decompress (or checkout from SVN) the file in your
+ BOOST_ROOT directory.
+ 
+
+ Othesewise, if you decompress in a different directory, you will need to
+ comment some lines, and uncomment and change others in the build/Jamfile
+ and test/Jamfile. Sorry for this, but I have not reached yet to write a
+ Jamfile that is able to work in both environements and use the BOOST_ROOT
+ variable. Any help is welcome.
+ 
+<a name="boost_sync.users_guide.getting_started.install.building_boost_sync_"></a><h5>
+<a name="id4942676"></a>
+ <a href="index.html#boost_sync.users_guide.getting_started.install.building_boost_sync_">Building
+ Boost.Sync </a>
+ </h5>
+
+ Boost.Sync is a header only library, so
+ no need to compile anything.
+ 
+<a name="boost_sync.users_guide.getting_started.install.requirements"></a><h5>
+<a name="id4942706"></a>
+ Requirements
+ </h5>
+
+ Boost.Sync depends on some Boost libraries.
+ For these specific parts you must use either Boost version 1.39.0 or the
+ version in SVN trunk (even if older versions should works also).
+ 
+
+ In particular, Boost.Sync depends on:
+ 
+<div class="variablelist">
+
+<dl>
+<dt>Boost.Config</dt>
+<dd>
+ for configuration purposes, ...
+ </dd>
+<dt>Boost.Integer</dt>
+<dd>
+ for cstdint conformance, and integer traits ...
+ </dd>
+<dt>Boost.MPL</dt>
+<dd>
+ for MPL Assert and bool, logical ...
+ </dd>
+<dt>Boost.StaticAssert</dt>
+<dd>
+ for STATIC_ASSERT, ...
+ </dd>
+<dt>Boost.TypeTraits</dt>
+<dd>
+ for is_base, is_convertible ...
+ </dd>
+<dt>Boost.Utility/EnableIf</dt>
+<dd>
+ for enable_if, ...
+ </dd>
+</dl>
+</div>
+<a name="boost_sync.users_guide.getting_started.install.building_an_executable_that_uses__emphasis_role__bold__boost_sync__emphasis__"></a><h5>
+<a name="id4942884"></a>
+ <a href="index.html#boost_sync.users_guide.getting_started.install.building_an_executable_that_uses__emphasis_role__bold__boost_sync__emphasis__">Building
+ an executable that uses Boost.Sync </a>
+ </h5>
+
+ No link is needed.
+ 
+<a name="boost_sync.users_guide.getting_started.install.exceptions_safety_"></a><h5>
+<a name="id4942918"></a>
+ <a href="index.html#boost_sync.users_guide.getting_started.install.exceptions_safety_">Exceptions
+ safety </a>
+ </h5>
+
+ All functions in the library are exception-neutral and provide strong guarantee
+ of exception safety as long as the underlying parameters provide it.
+ 
+<a name="boost_sync.users_guide.getting_started.install.thread_safety_"></a><h5>
+<a name="id4942945"></a>
+ <a href="index.html#boost_sync.users_guide.getting_started.install.thread_safety_">Thread
+ safety </a>
+ </h5>
+
+ All functions in the library are thread-unsafe except when noted explicitly.
+ 
+<a name="boost_sync.users_guide.getting_started.install.tested_compilers_"></a><h5>
+<a name="id4942971"></a>
+ <a href="index.html#boost_sync.users_guide.getting_started.install.tested_compilers_">Tested
+ compilers </a>
+ </h5>
+
+ The implementation will eventually work with most C++03 conforming compilers.
+ Current version has been tested on:
+ 
+
+ Windows with
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ MSVC 10.0
+ </li>
+<li>
+ MSVC 9.0 Express
+ </li>
+<li>
+ MSVC 8.0
+ </li>
+</ul></div>
+
+ Scientific Linux with
+ 
+<div class="itemizedlist"><ul type="disc"><li>
+ GCC 4.1.2
+ </li></ul></div>
+
+ Cygwin with
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ GCC 3.4.4
+ </li>
+<li>
+ GCC 4.3.4
+ </li>
+</ul></div>
+
+ MinGW with
+ 
+<div class="itemizedlist"><ul type="disc"><li>
+ GCC 4.4.0
+ </li></ul></div>
+
+ Initial version was tested on:
+ 
+
+ MacOS with GCC 4.2.4
+ 
+
+ Ubuntu Linux with GCC 4.2.4
+ 
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top">
+ Please let us know how this works on other platforms/compilers.
+ </td></tr>
+</table></div>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top">
+ Please send any questions, comments and bug reports to boost <at>
+ lists <dot> boost <dot> org.
+ </td></tr>
+</table></div>
+</div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_sync.users_guide.tutorial"></a>Tutorial
+</h3></div></div></div>
+<div class="toc"><dl>
+<dt><a href="index.html#boost_sync.users_guide.tutorial.lockable_traits">Lockable
+ traits</a></dt>
+<dt><a href="index.html#boost_sync.users_guide.tutorial.lockable_generators">Lockable
+ generators</a></dt>
+<dt><a href="index.html#boost_sync.users_guide.tutorial.lockable_concepts">Lockable
+ concepts</a></dt>
+</dl></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.users_guide.tutorial.lockable_traits"></a><a href="index.html#boost_sync.users_guide.tutorial.lockable_traits" title="Lockable
+ traits">Lockable
+ traits</a>
+</h4></div></div></div>
+
+ Lockable substitutability
+ 
+
+ The Boost mutexes have associated an implicit category which form a sub-typing
+ hierarchy:
+ 
+<pre class="programlisting">BasicLockable > TryLockable <- TimedLockable
+</pre>
+
+ Locking behavior can be further categorized as:
+ 
+<div class="itemizedlist"><ul type="disc"><li>
+ Ownership: (concurrent agent affinity): owned or unowned
+ </li></ul></div>
+
+ An owned lockable can be sustituted by any unowned lockable.
+ 
+<pre class="programlisting">owned <- unowned
+</pre>
+<div class="itemizedlist"><ul type="disc"><li>
+ Share: When a lockable is owned by the concurrent agent, this ownership
+ can be either exclusive or shared. When shared ownership is considered
+ there is yet the possibility to change at run-time from shared to exclusive
+ and viceversa. We talk of upgradable lockables.
+ </li></ul></div>
+<pre class="programlisting">ExclusiveLockable <- SharedLockable <- UpgradeLockable
+</pre>
+<div class="itemizedlist"><ul type="disc"><li>
+ Re-entrancy: When a lockable is owned by the concurrent agent, the
+ ownership can be done recursively or not
+ </li></ul></div>
+<pre class="programlisting">non_recursive <- recursive
+</pre>
+<div class="itemizedlist"><ul type="disc"><li>
+ Scope: This is related to the kind of concurrent agents that can own
+ the lockable. Currently the library takes in account mono-threaded,
+ multi-threaded or multi-process contexts.
+ </li></ul></div>
+<pre class="programlisting">mono_threaded <- multi_threaded <- multi_process
+</pre>
+<div class="itemizedlist"><ul type="disc"><li>
+ Lifetime: The lifetime of a lock could be associated to the process,
+ the kernel or the file-system
+ </li></ul></div>
+<pre class="programlisting">process_lifetime <- kernel_lifetime <- filesystem_lifetime
+</pre>
+
+ Substitutability applies both to the degree of syntactic support and to
+ the locking semantics
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ A recursive mutex and binary semaphore are substitutable in code written
+ against a exclusive mutex
+ </li>
+<li>
+ A null mutex is substitutable for all others in a single-threaded environment
+ </li>
+</ul></div>
+
+ We can see these axes of variation expressed against some Boost synchronization
+ mechanisms (from now bip stands for boost::interprocess):
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ <code class="computeroutput">boost::mutex</code>: ExclusiveLockable, owned,
+ non-recursive, multi-threaded
+ </li>
+<li>
+ <code class="computeroutput">boost::shared_mutex</code>: UpgradeableBasicLockable,
+ owned, non-recursive, multi-threaded
+ </li>
+<li>
+ <code class="computeroutput">bip::sync::null_mutex</code>: UpgradableTimedLockable,
+ unowned, recursive, mono-threaded
+ </li>
+<li>
+ <code class="computeroutput">bip::sync::interprocess_recursive_mutex</code>: ExclusiveTimedLockable,
+ owned, recursive, multi_process.
+ </li>
+</ul></div>
+
+ Boost.Sync provides a set of very specific
+ traits classes, some of them encapsulate a single trait for a <code class="computeroutput">Lockable</code> type; for example, is a lockable
+ recursive (<code class="computeroutput">is_recursive</code>),
+ is useful in a multi threaded context (<code class="computeroutput">is_multi_threaded</code>).
+ 
+
+ The Boost.Sync lockable traits classes
+ share a unified design that mimic the one of Boost.TypeTraits: each class
+ inherits from a the type <code class="computeroutput">true_type</code>
+ if the type has the specified property and inherits from <code class="computeroutput">false_type</code> otherwise.
+ 
+
+ The Boost.Sync library also contains a
+ set of classes that perform a specific transformation on a type. Each class
+ that performs a transformation defines a single typedef-member type that
+ is the result of the transformation.
+ 
+
+ All of the locakble traits classes are defined inside namespace boost::lockable.
+ 
+
+ tag trait implementation
+ 
+
+ Most of the implementation is fairly repetitive anyway, so here we will
+ just give you a flavor for how some of the classes are implemented. See
+ the reference section for the full details.
+ 
+
+ The library defines a tag hierarchy associated to a trait. For example
+ for the scope trait:
+ 
+<pre class="programlisting">struct mono_threaded_tag {};
+struct multi_threaded_tag : mono_threaded_tag {};
+struct multi_process_tag : multi_threaded_tag {};
+</pre>
+
+ By default the <code class="computeroutput">scope</code> trait
+ forward to a nested type <code class="computeroutput">scope</code>.
+ 
+<pre class="programlisting">template <typename Lockable>
+struct scope {
+ typedef typename Lockable::scope type;
+};
+</pre>
+
+ In order to make a type a model of <code class="computeroutput">Lockable</code>
+ we have two possibilities:
+ 
+<div class="itemizedlist"><ul type="disc"><li>
+ declare the nested type <code class="computeroutput">scope</code>
+ </li></ul></div>
+<pre class="programlisting">class my_mutex {
+public:
+ typedef <a scope tag> scope;
+ // ...
+};
+</pre>
+<div class="itemizedlist"><ul type="disc"><li>
+ specialize the class template <code class="computeroutput">sync::scope</code>
+ </li></ul></div>
+<pre class="programlisting">template<>
+struct scope_tag<my_mutex> {
+ typedef multi_threaded_tag type;
+};
+</pre>
+
+ lockable_base helper
+ 
+
+ The library provis also a mixin class <code class="computeroutput">lockable_base</code>
+ which will define all the needed nested typedefs.
+ 
+<pre class="programlisting">template<
+ typename Scope=multi_threaded_tag,
+ typename Category=exclusive_tag,
+ typename Reentrancy=non_recursive_tag,
+ typename Kind=timed_lockable_tag,
+ typename Lifetime=typename default_lifetime<Scope>,
+ typename Named=anonymous_tag,
+ typename Base=void
+> struct lockable_base;
+</pre>
+
+ which defines the correct types. The <code class="computeroutput">lockable_base</code>
+ has a lot of parameters, and the defaults are the ones associated to <code class="computeroutput">boost::mutex</code>. So Boost.Thread could use it as
+ follows
+ 
+<pre class="programlisting">class mutex : public lockable_base<> {
+ // ...
+};
+</pre>
+
+ is_trait implementation
+ 
+
+ For example the trait <code class="computeroutput">is_multi_threaded</code>
+ is defined as : If Lockable has <code class="computeroutput">scope</code>
+ trait is the same or inherits from <code class="computeroutput">multi_threaded_tag</code>
+ then it is <code class="computeroutput">true_type</code>, otherwise
+ it is <code class="computeroutput">false_type</code>.
+ 
+<pre class="programlisting">template <typename Lockable>
+struct is_multi_threaded
+ : is_same_or_is_base_and_derived<
+ multi_threaded_tag,
+ typename scope<Lockable>::type
+ >
+{};
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.users_guide.tutorial.lockable_generators"></a><a href="index.html#boost_sync.users_guide.tutorial.lockable_generators" title="Lockable
+ generators">Lockable
+ generators</a>
+</h4></div></div></div>
+
+ Finding the best lock
+ 
+
+ Inverse traits can match a lockable type based on specific traits, form
+ a given family of lockable types.
+ 
+
+ It is also possible to specify characteristics to perform a reverse lookup
+ to find a primitive lockable type, either by exact match or by substitutable
+ match.
+ 
+<pre class="programlisting">find_best_lock<>::type == boost::mutex
+find_best_lock<mono_threaded_tag>::type == bsync::null_mutex
+find_best_lock<multi_threaded_tag>::type == bsync::thread_mutex
+find_best_lock<multi_process_tag>::type == bsync::interprocess_mutex
+</pre>
+
+ The user can also find a lockable using mpl constraints as follows
+ 
+<pre class="programlisting">typedef find_best_lock_between<Lockables,
+ mpl::and<is_multi_threaded<_>, is_recursive<_> > >::type best;
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.users_guide.tutorial.lockable_concepts"></a><a href="index.html#boost_sync.users_guide.tutorial.lockable_concepts" title="Lockable
+ concepts">Lockable
+ concepts</a>
+</h4></div></div></div>
+
+ For the main category clasification, the library provides concept classes
+ that can be used with Boost.ConceptCheck. For example <code class="computeroutput">LockableConcept</code>
+ object supports the basic features required to delimit a critical region.
+ Supports the basic <code class="computeroutput">lock</code>,
+ <code class="computeroutput">unlock</code> and <code class="computeroutput">try_lock</code> functions and defines the lock
+ traits.
+ 
+<pre class="programlisting">template <typename Lockable>
+struct BasicLockableConcept {
+ typedef typename category<Lockable>::type category;
+ typedef typename kind<Lockable>::type kind;
+ typedef typename reentrancy<Lockable>::type reentrancy;
+ typedef typename scope<Lockable>::type scope;
+ typedef typename lifetime<Lockable>::type lifetime;
+ typedef typename named<Lockable>::type named;
+
+ BOOST_CONCEPT_USAGE(BasicLockableConcept) {
+ l.lock();
+ l.unlock();
+ }
+ Lockable& l;
+};
+</pre>
+
+ The user can now check staticaly that the template parameter is a model
+ of BasicLocable as follows
+ 
+<pre class="programlisting">#include "boost/sync/lockable_concepts.hpp"
+template <typename Lockable>
+class my_class {
+ BOOST_CONCEPT_ASSERT((BasicLockableConcept<Lockable>));
+ // ...
+};
+</pre>
+
+ The same can be done for <code class="computeroutput">TimedLockableConcept</code>,
+ <code class="computeroutput">ShareLockableConcept</code> and
+ <code class="computeroutput">UpgradeLockableConcept</code>
+ (See the reference section for more details).
+ 
+</div>
+</div>
+<div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title">
+<a name="boost_sync.users_guide.examples"></a>Examples
+</h3></div></div></div></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_sync.users_guide.ext_references"></a> External Resources
+</h3></div></div></div>
+<div class="variablelist">
+
+<dl>
+<dt><a href="http://www.open-std.org/jtc1/sc22/wg21" target="_top">C++
+ Standards Committee's current Working Paper</a></dt>
+<dd>
+ The most authoritative reference material for the library is the C++
+ Standards Committee's current Working Paper (WP). 30 - Thread support
+ library
+ </dd>
+<dt>N3130 - Lockable requirements for C++0x</dt>
+<dd>
+ From Anthony Williams.
+ </dd>
+<dt>N1833 - Preliminary Threading Library Proposal for TR2</dt>
+<dd>
+ Kevlin Henney, 2005
+ </dd>
+<dt>More C++ Threading - From Procedural to Generic, by Example</dt>
+<dd>
+ Kevlin Henney
+ </dd>
+<dt>C++ Threading - A Generic-Programming Approach</dt>
+<dd>
+ Kevlin Henney, April 16, 2004
+ </dd>
+</dl>
+</div>
+</div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="boost_sync.reference"></a> Reference
+</h2></div></div></div>
+<div class="toc"><dl>
+<dt> Header <boost/sync.hpp></dt>
+<dt> Header <boost/sync/lockable_traits.hpp></dt>
+<dd><dl>
+<dt><a href="index.html#boost_sync.reference.lockable_traits_hpp.category_hpp">
+ Header <code class="computeroutput"><boost/sync/lockable_traits/category.hpp></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_traits_hpp.reentrancy_hpp">
+ Header <code class="computeroutput"><boost/sync/lockable_traits/reentrancy.hpp></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_traits_hpp.scope_hpp">
+ Header <code class="computeroutput"><boost/sync/lockable_traits/scope.hpp></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_traits_hpp.ownership_hpp">
+ Header <code class="computeroutput"><boost/sync/lockable_traits/ownership.hpp></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_traits_hpp.lifetime_hpp">
+ Header <code class="computeroutput"><boost/sync/lockable_traits/lifetime.hpp></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_traits_hpp.name_hpp">
+ Header <code class="computeroutput"><boost/sync/lockable_traits/naming.hpp></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_traits_hpp.lockable_base_hpp">
+ Header <code class="computeroutput"><boost/sync/lockable_traits/lockable_base.hpp></code></a></dt>
+</dl></dd>
+<dt><a href="index.html#boost_sync.reference.Locables"> Requirements for Lockable
+ types </a></dt>
+<dd><dl>
+<dt><a href="index.html#boost_sync.reference.Locables.BasicLockable"> BasicLockable
+ Requirements </a></dt>
+<dt><a href="index.html#boost_sync.reference.Locables.TryLockable"> Lockable
+ Requirements </a></dt>
+<dt><a href="index.html#boost_sync.reference.Locables.TimedLockable"> TimedLockable
+ Requirements </a></dt>
+<dt><a href="index.html#boost_sync.reference.Locables.SharedBasicLockable">
+ SharedBasicLockable Requirements </a></dt>
+<dt><a href="index.html#boost_sync.reference.Locables.SharedLockable"> SharedLockable
+ Requirements </a></dt>
+<dt><a href="index.html#boost_sync.reference.Locables.SharedTimedLockable">
+ SharedTimedLockable Requirements </a></dt>
+</dl></dd>
+<dt> Header <boost/sync/lockable_concepts.hpp></dt>
+<dd><dl>
+<dt><a href="index.html#boost_sync.reference.lockable_concept_hpp.BasicLockableConcept">
+ Template Class <code class="computeroutput">BasicLockableConcept<></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_concept_hpp.LockableConcept">
+ Template Class <code class="computeroutput">LockableConcept<></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_concept_hpp.TimedLockableConcept">
+ Template Class <code class="computeroutput">TimedLockableConcept<></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_concept_hpp.ShareBasicLockableConcept">
+ Template Class <code class="computeroutput">ShareBasicLockableConcept<></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_concept_hpp.ShareLockableConcept">
+ Template Class <code class="computeroutput">ShareLockableConcept<></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_concept_hpp.ShareTimedLockableConcept">
+ Template Class <code class="computeroutput">ShareTimedLockableConcept<></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_concept_hpp.UpgradeBasicLockableConcept">
+ Template Class <code class="computeroutput">UpgradeBasicLockableConcept<></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_concept_hpp.UpgradeLockableConcept">
+ Template Class <code class="computeroutput">UpgradeLockableConcept<></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_concept_hpp.UpgradeTimedLockableConcept">
+ Template Class <code class="computeroutput">UpgradeTimedLockableConcept<></code></a></dt>
+</dl></dd>
+<dt> Header <boost/sync/locks.hpp></dt>
+<dd><dl>
+<dt><a href="index.html#boost_sync.reference.locks_hpp.lock_options_hpp"> Header
+ <code class="computeroutput"><boost/sync/locks/lock_options.hpp></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.locks_hpp.lock_guard_hpp"> Header
+ <code class="computeroutput"><boost/sync/locks/lock_guard.hpp></code></a></dt>
+</dl></dd>
+</dl></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_sync.reference.sync_hpp"></a> Header <boost/sync.hpp>
+</h3></div></div></div>
+<pre class="programlisting">#include <boost/sync/lockable_traits.hpp>
+#include <boost/sync/lockable_concepts.hpp>
+#include <boost/sync/locks.hpp>
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_sync.reference.lockable_traits_hpp"></a> Header <boost/sync/lockable_traits.hpp>
+</h3></div></div></div>
+<div class="toc"><dl>
+<dt><a href="index.html#boost_sync.reference.lockable_traits_hpp.category_hpp">
+ Header <code class="computeroutput"><boost/sync/lockable_traits/category.hpp></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_traits_hpp.reentrancy_hpp">
+ Header <code class="computeroutput"><boost/sync/lockable_traits/reentrancy.hpp></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_traits_hpp.scope_hpp">
+ Header <code class="computeroutput"><boost/sync/lockable_traits/scope.hpp></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_traits_hpp.ownership_hpp">
+ Header <code class="computeroutput"><boost/sync/lockable_traits/ownership.hpp></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_traits_hpp.lifetime_hpp">
+ Header <code class="computeroutput"><boost/sync/lockable_traits/lifetime.hpp></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_traits_hpp.name_hpp">
+ Header <code class="computeroutput"><boost/sync/lockable_traits/naming.hpp></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_traits_hpp.lockable_base_hpp">
+ Header <code class="computeroutput"><boost/sync/lockable_traits/lockable_base.hpp></code></a></dt>
+</dl></div>
+<pre class="programlisting">#include <boost/sync/lockable_traits/category.hpp>
+#include <boost/sync/lockable_traits/reentrancy.hpp>
+#include <boost/sync/lockable_traits/scope.hpp>
+#include <boost/sync/lockable_traits/ownership.hpp>
+#include <boost/sync/lockable_traits/lifetime.hpp>
+#include <boost/sync/lockable_traits/naming.hpp>
+#include <boost/sync/lockable_traits/lock_traits_base.hpp>
+#include <boost/sync/lockable_traits/best_condition_variable.hpp>
+#include <boost/sync/lockable_traits/generic_condition_variable.hpp>
+</pre>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.reference.lockable_traits_hpp.category_hpp"></a><a href="index.html#boost_sync.reference.lockable_traits_hpp.category_hpp" title="
+ Header <boost/sync/lockable_traits/category.hpp>">
+ Header <code class="computeroutput"><boost/sync/lockable_traits/category.hpp></code></a>
+</h4></div></div></div>
+<pre class="programlisting">namespace boost { namespace sync {
+
+ struct exclusive_basic_lockable_tag;
+ struct exclusive_try_lockable_tag;
+ struct exclusive_timed_lockable_tag;
+ struct sharable_basic_lockable_tag;
+ struct sharable_try_lockable_tag;
+ struct sharable_timed_lockable_tag;
+ struct upgradable_basic_lockable_tag;
+ struct upgradable_try_lockable_tag;
+ struct upgradable_timed_lockable_tag;
+ template <typename Lockable> struct category;
+
+ template <typename Lockable> struct is_basic_lockable;
+ template <typename Lockable> struct is_try_lockable;
+ template <typename Lockable> struct is_timed_lockable;
+ template <typename Lockable> struct is_exclusive;
+ template <typename Lockable> struct is_sharable;
+ template <typename Lockable> struct is_upgradable;
+}
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.reference.lockable_traits_hpp.reentrancy_hpp"></a><a href="index.html#boost_sync.reference.lockable_traits_hpp.reentrancy_hpp" title="
+ Header <boost/sync/lockable_traits/reentrancy.hpp>">
+ Header <code class="computeroutput"><boost/sync/lockable_traits/reentrancy.hpp></code></a>
+</h4></div></div></div>
+<pre class="programlisting">namespace boost { namespace sync {
+
+ struct non_recursive_tag;
+ struct recursive_tag;
+ template <typename Lockable> struct reentrancy;
+
+ template <typename Lockable> struct is_recursive;
+}
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.reference.lockable_traits_hpp.scope_hpp"></a><a href="index.html#boost_sync.reference.lockable_traits_hpp.scope_hpp" title="
+ Header <boost/sync/lockable_traits/scope.hpp>">
+ Header <code class="computeroutput"><boost/sync/lockable_traits/scope.hpp></code></a>
+</h4></div></div></div>
+<pre class="programlisting">namespace boost { namespace sync {
+
+ struct mono_threaded_tag;
+ struct multi_threaded_tag;
+ struct multi_process_tag;
+ template <typename Lockable> struct scope;
+
+ template <typename Lockable> struct is_mono_threaded;
+ template <typename Lockable> struct is_multi_threaded;
+ template <typename Lockable> struct is_multi_process;
+}
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.reference.lockable_traits_hpp.ownership_hpp"></a><a href="index.html#boost_sync.reference.lockable_traits_hpp.ownership_hpp" title="
+ Header <boost/sync/lockable_traits/ownership.hpp>">
+ Header <code class="computeroutput"><boost/sync/lockable_traits/ownership.hpp></code></a>
+</h4></div></div></div>
+<pre class="programlisting">namespace boost { namespace sync {
+
+ struct unowned_tag;
+ struct owned_tag;
+ template <typename Lockable> struct ownership;
+
+ template <typename Lockable> struct is_owned;
+}
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.reference.lockable_traits_hpp.lifetime_hpp"></a><a href="index.html#boost_sync.reference.lockable_traits_hpp.lifetime_hpp" title="
+ Header <boost/sync/lockable_traits/lifetime.hpp>">
+ Header <code class="computeroutput"><boost/sync/lockable_traits/lifetime.hpp></code></a>
+</h4></div></div></div>
+<pre class="programlisting">namespace boost { namespace sync {
+
+ struct process_lifetime_tag;
+ struct kernel_lifetime_tag;
+ struct filesystem_lifetime_tag;
+ template <typename Lockable> struct lifetime;
+
+ template <typename Lockable> struct has_process_lifetime;
+ template <typename Lockable> struct has_kernel_lifetime;
+ template <typename Lockable> struct has_filesystem_lifetime;
+
+}
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.reference.lockable_traits_hpp.name_hpp"></a><a href="index.html#boost_sync.reference.lockable_traits_hpp.name_hpp" title="
+ Header <boost/sync/lockable_traits/naming.hpp>">
+ Header <code class="computeroutput"><boost/sync/lockable_traits/naming.hpp></code></a>
+</h4></div></div></div>
+<pre class="programlisting">namespace boost { namespace sync {
+
+ struct anonymous_tag;
+ struct named_tag;
+ template <typename Lockable> struct naming;
+ template <typename Lockable> struct is_named;
+
+}
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.reference.lockable_traits_hpp.lockable_base_hpp"></a><a href="index.html#boost_sync.reference.lockable_traits_hpp.lockable_base_hpp" title="
+ Header <boost/sync/lockable_traits/lockable_base.hpp>">
+ Header <code class="computeroutput"><boost/sync/lockable_traits/lockable_base.hpp></code></a>
+</h4></div></div></div>
+<pre class="programlisting">namespace boost { namespace sync {
+
+ template<typename Scope> struct default_lifetime;
+
+ template<
+ typename Scope=multi_threaded_tag,
+ typename Category=exclusive_tag,
+ typename Reentrancy=non_recursive_tag,
+ typename Kind=timed_lockable_tag,
+ typename Lifetime=typename default_lifetime<Scope>,
+ typename Named=anonymous_tag,
+ typename Base=void
+ > struct lockable_base;
+}
+</pre>
+</div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_sync.reference.Locables"></a><a href="index.html#boost_sync.reference.Locables" title=" Requirements for Lockable
+ types "> Requirements for Lockable
+ types </a>
+</h3></div></div></div>
+<div class="toc"><dl>
+<dt><a href="index.html#boost_sync.reference.Locables.BasicLockable"> BasicLockable
+ Requirements </a></dt>
+<dt><a href="index.html#boost_sync.reference.Locables.TryLockable"> Lockable
+ Requirements </a></dt>
+<dt><a href="index.html#boost_sync.reference.Locables.TimedLockable"> TimedLockable
+ Requirements </a></dt>
+<dt><a href="index.html#boost_sync.reference.Locables.SharedBasicLockable">
+ SharedBasicLockable Requirements </a></dt>
+<dt><a href="index.html#boost_sync.reference.Locables.SharedLockable"> SharedLockable
+ Requirements </a></dt>
+<dt><a href="index.html#boost_sync.reference.Locables.SharedTimedLockable">
+ SharedTimedLockable Requirements </a></dt>
+</dl></div>
+
+ A concurrent agent is a an entity (such as a thread, process, or packaged
+ task) that may perform work in parallel with other concurrent agents. The
+ calling agent is determined by context, e.g. the calling thread or the packaged
+ task that contains the call, etc.
+ 
+
+ The standard and also the Boost.Thread and Boost.Interprocess library templates
+ <code class="computeroutput">unique_lock</code>, <code class="computeroutput">lock_guard</code>, <code class="computeroutput">lock</code>,
+ <code class="computeroutput">try_lock</code> and <code class="computeroutput">condition_variable_any</code> all operate on user-supplied
+ lockable objects. Such an object must support the member functions specified
+ for either the <code class="computeroutput">BasicLockable</code>
+ requirements, the <code class="computeroutput">Lockable</code>
+ requirements or the <code class="computeroutput">TimedLockable</code>
+ requirements as appropriate to acquire or release ownership of a lock by
+ a given concurrent agent.
+ 
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top">
+ The nature of any lock ownership and any synchronization it may entail
+ are not part of these requirements.
+ </td></tr>
+</table></div>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top">
+ Some lockable objects are "agent-oblivious" in that they work
+ for any concurrent-agent model because they do not determine or store the
+ agent's ID (e.g., an ordinary spin-lock).
+ </td></tr>
+</table></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.reference.Locables.BasicLockable"></a><a href="index.html#boost_sync.reference.Locables.BasicLockable" title=" BasicLockable
+ Requirements "> BasicLockable
+ Requirements </a>
+</h4></div></div></div>
+
+ In order for a type <code class="computeroutput">L</code> to
+ qualify as a <code class="computeroutput">BasicLockable</code>
+ type, the following expressions must be supported, with the specified semantics,
+ where <code class="computeroutput">m</code> denotes a value
+ of type <code class="computeroutput">L</code>:
+ 
+
+ The expression <code class="computeroutput">m.lock()</code>
+ shall be well-formed and have the following semantics:
+ 
+
+ Effects: Block until a lock can be acquired
+ for the current concurrent agent. If an exception is thrown then a lock
+ shall not have been acquired for the current concurrent agent.
+ 
+
+ Return type: void
+ 
+
+ The expression <code class="computeroutput">m.unlock()</code>
+ shall be well-formed and have the following semantics:
+ 
+
+ Requires: The current concurrent agent
+ shall hold a lock on <code class="computeroutput">m</code>.
+ 
+
+ Effects: Release a lock on <code class="computeroutput">m</code> held by the current concurrent agent.
+ 
+
+ Return type: <code class="computeroutput">void</code>
+ 
+
+ Throws: Nothing.
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.reference.Locables.TryLockable"></a><a href="index.html#boost_sync.reference.Locables.TryLockable" title=" Lockable
+ Requirements "> Lockable
+ Requirements </a>
+</h4></div></div></div>
+
+ In order for a type <code class="computeroutput">L</code> to
+ qualify as a <code class="computeroutput">Lockable</code> type,
+ it must meet the <code class="computeroutput">BasicLockable</code>
+ requirements. In addition, the following expressions must be supported,
+ with the specified semantics, where m denotes a value of type <code class="computeroutput">L</code>:
+ 
+
+ The expression <code class="computeroutput">m.try_lock()</code>
+ shall be well-formed and have the following semantics:
+ 
+
+ Effects: Attempt to acquire a lock for
+ the current concurrent agent without blocking. If an exception is thrown
+ then a lock shall not have been acquired for the current concurrent agent.
+ 
+
+ Return type: <code class="computeroutput">bool</code>
+ 
+
+ Returns: <code class="computeroutput">true</code>
+ if the lock was acquired, <code class="computeroutput">false</code>
+ otherwise.
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.reference.Locables.TimedLockable"></a><a href="index.html#boost_sync.reference.Locables.TimedLockable" title=" TimedLockable
+ Requirements "> TimedLockable
+ Requirements </a>
+</h4></div></div></div>
+
+ For a type <code class="computeroutput">TL</code> to qualify
+ as <code class="computeroutput">TimedLockable</code> it must
+ meet the Lockable requirements, and additionally the following expressions
+ must be well-formed, with the specified semantics, where <code class="computeroutput">m</code> is an instance of a type <code class="computeroutput">TL</code>, <code class="computeroutput">rel_time</code>
+ denotes instantiation of <code class="computeroutput">duration</code>
+ and <code class="computeroutput">abs_time</code> denotes an
+ instantiation of <code class="computeroutput">time_point</code>.
+ 
+
+ The expression <code class="computeroutput">m.try_lock_for(rel_time)</code>
+ shall be well-formed and have the following semantics:
+ 
+
+ Effects: Attempt to acquire a lock for
+ the current concurrent agent within the relative timeout specified by
+ <code class="computeroutput">rel_time</code>. The function
+ shall return within the timeout specified by <code class="computeroutput">rel_time</code>
+ only if it has obtained a lock on <code class="computeroutput">m</code>
+ for the current concurrent agent. If an exception is thrown then a lock
+ shall not have been acquired for the current concurrent agent.
+ 
+
+ Return type: <code class="computeroutput">bool</code>
+ 
+
+ Returns: <code class="computeroutput">true</code>
+ if the lock was acquired, <code class="computeroutput">false</code>
+ otherwise.
+ 
+
+ The expression <code class="computeroutput">m.try_lock_until(abs_time)</code>
+ shall be well-formed and have the following semantics:
+ 
+
+ Effects: Attempt to acquire a lock for
+ the current concurrent agent before the absolute timeout specified by
+ <code class="computeroutput">abs_time</code>. The function
+ shall return before the timeout specified by <code class="computeroutput">abs_time</code>
+ only if it has obtained a lock on <code class="computeroutput">m</code>
+ for the current concurrent agent. If an exception is thrown then a lock
+ shall not have been acquired for the current concurrent agent.
+ 
+
+ Return type: <code class="computeroutput">bool</code>
+ 
+
+ Returns: <code class="computeroutput">true</code>
+ if the lock was acquired, <code class="computeroutput">false</code>
+ otherwise.
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.reference.Locables.SharedBasicLockable"></a><a href="index.html#boost_sync.reference.Locables.SharedBasicLockable" title="
+ SharedBasicLockable Requirements ">
+ SharedBasicLockable Requirements </a>
+</h4></div></div></div>
+
+ In order for a type <code class="computeroutput">L</code> to
+ qualify as a <code class="computeroutput">SharedBasicLockable</code>
+ type, it must meet the <code class="computeroutput">BasicLockable</code>
+ requirements. In addition, the following expressions must be supported,
+ with the specified semantics, where <code class="computeroutput">m</code>
+ denotes a value of type <code class="computeroutput">L</code>:
+ 
+
+ The expression <code class="computeroutput">is_shared_lockable<L></code> is <code class="computeroutput">true_type</code>.
+ 
+
+ The expression <code class="computeroutput">m.lock_shared()</code>
+ shall be well-formed and have the following semantics:
+ 
+
+ Effects: Block until shared ownership
+ can be acquired for the current concurrent agent. If an exception is thrown
+ then a lock shall not have been acquired for the current concurrent agent.
+ 
+
+ Return type: <code class="computeroutput">void</code>
+ 
+
+ The expression <code class="computeroutput">m.unlock_shared()</code>
+ shall be well-formed and have the following semantics:
+ 
+
+ Requires: The current concurrent agent
+ has shared onership on <code class="computeroutput">m</code>.
+ 
+
+ Effects: Release shared ownership on
+ <code class="computeroutput">m</code> held by the current concurrent
+ agent.
+ 
+
+ Return type: <code class="computeroutput">void</code>
+ 
+
+ Throws: Nothing.
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.reference.Locables.SharedLockable"></a><a href="index.html#boost_sync.reference.Locables.SharedLockable" title=" SharedLockable
+ Requirements "> SharedLockable
+ Requirements </a>
+</h4></div></div></div>
+
+ In order for a type <code class="computeroutput">L</code> to
+ qualify as a <code class="computeroutput">SharedLockable</code>
+ type, it must meet the <code class="computeroutput">SharedBasicLockable</code>
+ and <code class="computeroutput">Locable</code> requirements.
+ In addition, the following expressions must be supported, with the specified
+ semantics, where <code class="computeroutput">m</code> denotes
+ a value of type <code class="computeroutput">L</code>:
+ 
+
+ The expression <code class="computeroutput">m.try_lock_shared()</code>
+ shall be well-formed and have the following semantics:
+ 
+
+ Effects: Attempt to obtain shared ownership
+ for the current concurrent agent without blocking. If an exception is thrown
+ then a lock shall not have been acquired for the current concurrent agent.
+ 
+
+ Return type: <code class="computeroutput">bool</code>
+ 
+
+ Returns: <code class="computeroutput">true</code>
+ if shared ownership was obtained for the current thread, <code class="computeroutput">false</code> otherwise.
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.reference.Locables.SharedTimedLockable"></a><a href="index.html#boost_sync.reference.Locables.SharedTimedLockable" title="
+ SharedTimedLockable Requirements ">
+ SharedTimedLockable Requirements </a>
+</h4></div></div></div>
+
+ For a type <code class="computeroutput">TL</code> to qualify
+ as <code class="computeroutput">SharedTimedLockable</code>
+ it must meet the <code class="computeroutput">SharedLockable</code>
+ and the <code class="computeroutput">TimedLockable</code> requirements,
+ and additionally the following expressions must be well-formed, with the
+ specified semantics, where <code class="computeroutput">m</code>
+ is an instance of a type <code class="computeroutput">TL</code>,
+ <code class="computeroutput">rel_time</code> denotes instantiation
+ of duration and <code class="computeroutput">abs_time</code>
+ denotes an instantiation of time_point.
+ 
+
+ The expression <code class="computeroutput">m.try_lock_shared_for(rel_time)</code>
+ shall be well-formed and have the following semantics:
+ 
+
+ Effects: Attempt to acquire a lock for
+ the current concurrent agent within the relative timeout specified by
+ <code class="computeroutput">rel_time</code>. The function
+ shall return within the timeout specified by rel_time only if it has obtained
+ a lock on <code class="computeroutput">m</code> for the current
+ concurrent agent. If an exception is thrown then a lock shall not have
+ been acquired for the current concurrent agent.
+ 
+
+ Return type: <code class="computeroutput">bool</code>
+ 
+
+ Returns: <code class="computeroutput">true</code>
+ if the lock was acquired, <code class="computeroutput">false</code>
+ otherwise.
+ 
+
+ The expression <code class="computeroutput">m.try_lock_shared_until(abs_time)</code>
+ shall be well-formed and have the following semantics:
+ 
+
+ Effects: Attempt to obtain shared ownership
+ for the current concurrent agent before the absolute timeout specified
+ by <code class="computeroutput">abs_time</code>. The function
+ shall return before the timeout specified by <code class="computeroutput">abs_time</code>
+ only if it has obtained shared ownership on m for the current concurrent
+ agent. If an exception is thrown then shared ownership shall not have been
+ acquired for the current concurrent agent.
+ 
+
+ Return type: <code class="computeroutput">bool</code>
+ 
+
+ Returns: <code class="computeroutput">true</code>
+ if shared ownership was acquired, <code class="computeroutput">false</code>
+ otherwise.
+ 
+</div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_sync.reference.lockable_concept_hpp"></a> Header <boost/sync/lockable_concepts.hpp>
+</h3></div></div></div>
+<div class="toc"><dl>
+<dt><a href="index.html#boost_sync.reference.lockable_concept_hpp.BasicLockableConcept">
+ Template Class <code class="computeroutput">BasicLockableConcept<></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_concept_hpp.LockableConcept">
+ Template Class <code class="computeroutput">LockableConcept<></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_concept_hpp.TimedLockableConcept">
+ Template Class <code class="computeroutput">TimedLockableConcept<></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_concept_hpp.ShareBasicLockableConcept">
+ Template Class <code class="computeroutput">ShareBasicLockableConcept<></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_concept_hpp.ShareLockableConcept">
+ Template Class <code class="computeroutput">ShareLockableConcept<></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_concept_hpp.ShareTimedLockableConcept">
+ Template Class <code class="computeroutput">ShareTimedLockableConcept<></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_concept_hpp.UpgradeBasicLockableConcept">
+ Template Class <code class="computeroutput">UpgradeBasicLockableConcept<></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_concept_hpp.UpgradeLockableConcept">
+ Template Class <code class="computeroutput">UpgradeLockableConcept<></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.lockable_concept_hpp.UpgradeTimedLockableConcept">
+ Template Class <code class="computeroutput">UpgradeTimedLockableConcept<></code></a></dt>
+</dl></div>
+<pre class="programlisting">namespace boost { namespace sync {
+
+ template <typename Lockable> struct BasicLockableConcept;
+ template <typename Lockable> struct LockableConcept;
+ template <typename Lockable> struct TimedLockableConcept;
+ template <typename Lockable> struct ShareBasicLockableConcept;
+ template <typename Lockable> struct ShareLockableConcept;
+ template <typename Lockable> struct ShareTimedLockableConcept;
+ template <typename Lockable> struct UpgradeBasicLockableConcept;
+ template <typename Lockable> struct UpgradeLockableConcept;
+ template <typename Lockable> struct UpgradeTimedLockableConcept;
+
+}}
+</pre>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.reference.lockable_concept_hpp.BasicLockableConcept"></a><a href="index.html#boost_sync.reference.lockable_concept_hpp.BasicLockableConcept" title="
+ Template Class BasicLockableConcept<>">
+ Template Class <code class="computeroutput">BasicLockableConcept<></code></a>
+</h4></div></div></div>
+
+ The <code class="computeroutput">boost::mutex</code> and <code class="computeroutput">boost:interprocess
+ mutex family
+ classes are
+ a non-polymorphic
+ classes that
+ encapsulates a
+ system primitive
+ and portion
+ of C
+ API.
+ Clearly,
+ many of
+ the synchronisation
+ primitives support
+ common operations, and hence
+ a Concept. The </code>ExclusiveLockableConcept`
+ class can be used with the Boost.ConceptCheck in templates that work with
+ a exclusive synchronisation.
+ 
+
+ <code class="computeroutput">LockableConcept</code> object
+ supports the basic features required to delimit a critical region. Supports
+ the basic <code class="computeroutput">lock</code>, <code class="computeroutput">unlock</code> and <code class="computeroutput">try_lock</code>
+ functions and defines the lockable traits
+ 
+<pre class="programlisting">template <typename Lockable>
+struct BasicLockableConcept {
+ typedef typename category<Lockable>::type category;
+ typedef typename kind<Lockable>::type kind;
+ typedef typename reentrancy<Lockable>::type reentrancy;
+ typedef typename scope<Lockable>::type scope;
+ typedef typename lifetime<Lockable>::type lifetime;
+ typedef typename named<Lockable>::type named;
+
+ BOOST_CONCEPT_USAGE(LockableConcept) {
+ l.lock();
+ l.unlock();
+ }
+ Lockable l;
+};
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.reference.lockable_concept_hpp.LockableConcept"></a><a href="index.html#boost_sync.reference.lockable_concept_hpp.LockableConcept" title="
+ Template Class LockableConcept<>">
+ Template Class <code class="computeroutput">LockableConcept<></code></a>
+</h4></div></div></div>
+
+ The <code class="computeroutput">boost::mutex</code> and <code class="computeroutput">boost:interprocess
+ mutex family
+ classes are
+ a non-polymorphic
+ classes that
+ encapsulates a
+ system primitive
+ and portion
+ of C
+ API.
+ Clearly,
+ many of
+ the synchronisation
+ primitives support
+ common operations, and hence
+ a Concept. The </code>ExclusiveLockableConcept`
+ class can be used with the Boost.ConceptCheck in templates that work with
+ a exclusive synchronisation.
+ 
+
+ <code class="computeroutput">LockableConcept</code> object
+ supports the basic features required to delimit a critical region. Supports
+ the basic <code class="computeroutput">lock</code>, <code class="computeroutput">unlock</code> and <code class="computeroutput">try_lock</code>
+ functions and defines the lockable traits
+ 
+<pre class="programlisting">template <typename Lockable>
+struct LockableConcept {
+ BOOST_CONCEPT_ASSERT((BasicLockableConcept<Lockable>));
+
+ BOOST_CONCEPT_USAGE(LockableConcept) {
+ b=l.try_lock();
+ }
+ Lockable l;
+ bool b;
+};
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.reference.lockable_concept_hpp.TimedLockableConcept"></a><a href="index.html#boost_sync.reference.lockable_concept_hpp.TimedLockableConcept" title="
+ Template Class TimedLockableConcept<>">
+ Template Class <code class="computeroutput">TimedLockableConcept<></code></a>
+</h4></div></div></div>
+
+ <code class="computeroutput">TimedLockableConcept</code> object
+ extends <code class="computeroutput">ExclusiveLockConcept</code>
+ with the <code class="computeroutput">try_lock_until</code>
+ and <code class="computeroutput">try_lock_for</code> functions.
+ 
+<pre class="programlisting">template <typename Lockable>
+struct TimedLockableConcept {
+ BOOST_CONCEPT_ASSERT((LockableConcept<Lockable>));
+
+ BOOST_CONCEPT_USAGE(TimedLockableConcept) {
+ b=l.try_lock_until(t);
+ b=l.try_lock_for(boost::chrono::seconds(1));
+ }
+ Lockable l;
+ boost::chrono::system_clock::time_point t;
+ bool b;
+};
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.reference.lockable_concept_hpp.ShareBasicLockableConcept"></a><a href="index.html#boost_sync.reference.lockable_concept_hpp.ShareBasicLockableConcept" title="
+ Template Class ShareBasicLockableConcept<>">
+ Template Class <code class="computeroutput">ShareBasicLockableConcept<></code></a>
+</h4></div></div></div>
+
+ <code class="computeroutput">ShareBasicLockableConcept</code>
+ object extends <code class="computeroutput">BasicLockableConcept</code>
+ with the <code class="computeroutput">lock_shared</code> and
+ <code class="computeroutput">unlock_shared</code> functions
+ 
+<pre class="programlisting">template <typename Lockable>
+struct ShareBasicLockableConcept {
+ BOOST_CONCEPT_ASSERT((BasicLockableConcept<Lockable>));
+
+ BOOST_CONCEPT_USAGE(ShareBasicLockableConcept) {
+ l.lock_shared();
+ l.unlock_shared();
+ }
+ Lockable l;
+};
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.reference.lockable_concept_hpp.ShareLockableConcept"></a><a href="index.html#boost_sync.reference.lockable_concept_hpp.ShareLockableConcept" title="
+ Template Class ShareLockableConcept<>">
+ Template Class <code class="computeroutput">ShareLockableConcept<></code></a>
+</h4></div></div></div>
+
+ <code class="computeroutput">ShareLockableConcept</code> object
+ extends <code class="computeroutput">ShareBasicLockableConcept</code>
+ and <code class="computeroutput">LockableConcept</code> with
+ the <code class="computeroutput">try_lock_shared</code> functions.
+ 
+<pre class="programlisting">template <typename Lockable>
+struct ShareLockableConcept {
+ BOOST_CONCEPT_ASSERT((ShareBasicLockableConcept<Lockable>));
+ BOOST_CONCEPT_ASSERT((LockableConcept<Lockable>));
+
+ BOOST_CONCEPT_USAGE(ShareLockableConcept) {
+ b=l=.try_lock_shared();
+ }
+ Lockable l;
+ boost::chrono::system_clock::time_point t;
+ bool b;
+};
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.reference.lockable_concept_hpp.ShareTimedLockableConcept"></a><a href="index.html#boost_sync.reference.lockable_concept_hpp.ShareTimedLockableConcept" title="
+ Template Class ShareTimedLockableConcept<>">
+ Template Class <code class="computeroutput">ShareTimedLockableConcept<></code></a>
+</h4></div></div></div>
+
+ <code class="computeroutput">ShareTimedLockableConcept</code>
+ object extends <code class="computeroutput">ShareBasicLockableConcept</code>
+ and <code class="computeroutput">LockableConcept</code> with
+ the <code class="computeroutput">try_lock_shared_until</code>
+ and <code class="computeroutput">try_lock_shared_for</code>
+ functions
+ 
+<pre class="programlisting">template <typename Lockable>
+struct ShareLockableConcept {
+ BOOST_CONCEPT_ASSERT((ShareBasicLockableConcept<Lockable>));
+ BOOST_CONCEPT_ASSERT((LockableConcept<Lockable>));
+
+ BOOST_CONCEPT_USAGE(ShareLockableConcept) {
+ b=l.try_lock_shared_until(t);
+ b=l.try_lock_shared_for(boost::chrono::seconds(1));
+ }
+ Lockable& l;
+ boost::chrono::system_clock::time_point t;
+ bool b;
+};
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.reference.lockable_concept_hpp.UpgradeBasicLockableConcept"></a><a href="index.html#boost_sync.reference.lockable_concept_hpp.UpgradeBasicLockableConcept" title="
+ Template Class UpgradeBasicLockableConcept<>">
+ Template Class <code class="computeroutput">UpgradeBasicLockableConcept<></code></a>
+</h4></div></div></div>
+
+ <code class="computeroutput">UpgradeBasicLockableConcept</code>
+ object extends <code class="computeroutput">SharedBasicLockableConcept</code>
+ with the <code class="computeroutput">lock_upgrade</code>,
+ <code class="computeroutput">unlock_upgrade_and_lock</code>,
+ <code class="computeroutput">unlock_and_lock_shared</code>
+ and <code class="computeroutput">unlock_upgrade_and_lock_shared</code>
+ functions.
+ 
+<pre class="programlisting">template <typename Lockable>
+struct UpgradeLockableConcept {
+ BOOST_CONCEPT_ASSERT((SharedBasicLockableConcept<Lockable>));
+
+ BOOST_CONCEPT_USAGE(UpgradeLockableConcept) {
+ l.lock_upgrade();
+ l.unlock_upgrade_and_lock();
+ l.unlock_and_lock_upgrade();
+ l.unlock_and_lock_shared();
+ l.unlock_upgrade_and_lock_shared();
+ }
+ Lockable& l;
+ boost::chrono::system_clock::time_point t;
+};
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.reference.lockable_concept_hpp.UpgradeLockableConcept"></a><a href="index.html#boost_sync.reference.lockable_concept_hpp.UpgradeLockableConcept" title="
+ Template Class UpgradeLockableConcept<>">
+ Template Class <code class="computeroutput">UpgradeLockableConcept<></code></a>
+</h4></div></div></div>
+
+ <code class="computeroutput">UpgradeLockableConcept</code>
+ object extends <code class="computeroutput">UpgradeBasicLockableConcept</code>
+ and <code class="computeroutput">SharedLockableConcept</code>
+ with the <code class="computeroutput">try_lock_upgrade</code>,
+ <code class="computeroutput">try_unlock_upgrade_and_lock</code>,
+ <code class="computeroutput">try_unlock_share_and_lock</code>
+ and <code class="computeroutput">try_unlock_share_and_lock_upgrade</code>
+ functions.
+ 
+<pre class="programlisting">template <typename Lockable>
+struct UpgradeLockableConcept {
+ BOOST_CONCEPT_ASSERT((UpgradeBasicLockableConcept<Lockable>));
+
+ BOOST_CONCEPT_USAGE(UpgradeLockableConcept) {
+ b=l.try_lock_upgrade();
+ b=l.try_unlock_upgrade_and_lock();
+ b=l.try_unlock_share_and_lock();
+ b=l.try_unlock_share_and_lock_upgrade();
+ }
+ Lockable& l;
+ boost::chrono::system_clock::time_point t;
+ bool b;
+};
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.reference.lockable_concept_hpp.UpgradeTimedLockableConcept"></a><a href="index.html#boost_sync.reference.lockable_concept_hpp.UpgradeTimedLockableConcept" title="
+ Template Class UpgradeTimedLockableConcept<>">
+ Template Class <code class="computeroutput">UpgradeTimedLockableConcept<></code></a>
+</h4></div></div></div>
+
+ <code class="computeroutput">UpgradeTimedLockableConcept</code>
+ object extends <code class="computeroutput">UpgradeLockableConcept</code>
+ and <code class="computeroutput">SharedTimedLockableConcept</code>
+ with the <code class="computeroutput">try_lock_upgrade_until</code>,
+ <code class="computeroutput">try_lock_upgrade_for</code>,
+ <code class="computeroutput">try_unlock_upgrade_and_lock_for</code>
+ and <code class="computeroutput">try_unlock_upgrade_and_lock_until</code>
+ functions.
+ 
+<pre class="programlisting">template <typename Lockable>
+struct UpgradeLockableConcept {
+ BOOST_CONCEPT_ASSERT((UpgradeBasicLockableConcept<Lockable>));
+
+ BOOST_CONCEPT_USAGE(UpgradeLockableConcept) {
+ b=l.try_lock_upgrade_until(t);
+ b=l.try_lock_upgrade_for(d);
+ b=l.try_unlock_upgrade_and_lock_for(d);
+ b=l.try_unlock_upgrade_and_lock_until(t);
+ }
+ Lockable& l;
+ boost::chrono::system_clock::time_point t;
+ bool b;
+};
+</pre>
+</div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_sync.reference.locks_hpp"></a> Header <boost/sync/locks.hpp>
+</h3></div></div></div>
+<div class="toc"><dl>
+<dt><a href="index.html#boost_sync.reference.locks_hpp.lock_options_hpp"> Header
+ <code class="computeroutput"><boost/sync/locks/lock_options.hpp></code></a></dt>
+<dt><a href="index.html#boost_sync.reference.locks_hpp.lock_guard_hpp"> Header
+ <code class="computeroutput"><boost/sync/locks/lock_guard.hpp></code></a></dt>
+<dd><dl>
+<dt><a href="index.html#boost_sync.reference.locks_hpp.lock_guard_hpp.constructor">
+ Constructor <code class="computeroutput">lock_guard(Lockable & m)</code></a></dt>
+<dt><a href="index.html#boost_sync.reference.locks_hpp.lock_guard_hpp.constructor_adopt">
+ Constructor <code class="computeroutput">lock_guard(Lockable & m,boost::adopt_lock_t)</code></a></dt>
+<dt><a href="index.html#boost_sync.reference.locks_hpp.lock_guard_hpp.destructor">
+ Destructor <code class="computeroutput">~lock_guard()</code></a></dt>
+</dl></dd>
+</dl></div>
+<pre class="programlisting">#include <boost/sync/locks/lock_options.hpp>
+#include <boost/sync/locks/lock_guard.hpp>
+</pre>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.reference.locks_hpp.lock_options_hpp"></a><a href="index.html#boost_sync.reference.locks_hpp.lock_options_hpp" title=" Header
+ <boost/sync/locks/lock_options.hpp>"> Header
+ <code class="computeroutput"><boost/sync/locks/lock_options.hpp></code></a>
+</h4></div></div></div>
+
+ Some lock constructors take tag types which describe what should be done
+ with the lockable object during the lock's construction.
+ 
+<pre class="programlisting">namespace boost {
+
+ //!Type to indicate to a mutex lock constructor that must not lock the mutex.
+ struct defer_lock_t{};
+ //!Type to indicate to a mutex lock constructor that must try to lock the mutex.
+ struct try_to_lock_t {};
+ //!Type to indicate to a mutex lock constructor that the mutex is already locked.
+ struct adopt_lock_t{};
+
+ //!An object indicating that the locking
+ //!must be deferred.
+ static const defer_lock_t defer_lock = {};
+
+ //!An object indicating that a try_lock()
+ //!operation must be executed.
+ static const try_to_lock_t try_to_lock = {};
+
+ //!An object indicating that the ownership of lockable
+ //!object must be accepted by the new owner.
+ static const adopt_lock_t adopt_lock = {};
+
+} // namespace boost
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.reference.locks_hpp.lock_guard_hpp"></a><a href="index.html#boost_sync.reference.locks_hpp.lock_guard_hpp" title=" Header
+ <boost/sync/locks/lock_guard.hpp>"> Header
+ <code class="computeroutput"><boost/sync/locks/lock_guard.hpp></code></a>
+</h4></div></div></div>
+<div class="toc"><dl>
+<dt><a href="index.html#boost_sync.reference.locks_hpp.lock_guard_hpp.constructor">
+ Constructor <code class="computeroutput">lock_guard(Lockable & m)</code></a></dt>
+<dt><a href="index.html#boost_sync.reference.locks_hpp.lock_guard_hpp.constructor_adopt">
+ Constructor <code class="computeroutput">lock_guard(Lockable & m,boost::adopt_lock_t)</code></a></dt>
+<dt><a href="index.html#boost_sync.reference.locks_hpp.lock_guard_hpp.destructor">
+ Destructor <code class="computeroutput">~lock_guard()</code></a></dt>
+</dl></div>
+<pre class="programlisting">namespace boost {
+
+ template<typename BasicLockable>
+ class lock_guard
+ {
+ public:
+ typedef BasicLockable lockable_type;
+ explicit lock_guard(lockable_type& m_);
+ lock_guard(lockable_type& m_,boost::adopt_lock_t);
+ ~lock_guard();
+
+ lock_guard(lock_guard const&) = delete;
+ lock_guard& operator=(lock_guard const&) = delete;
+ private:
+ lockable_type& pm; // exposition only
+ };
+
+} // namespace boost
+</pre>
+
+ An object of type <a href="index.html#boost_sync.reference.locks_hpp.lock_guard_hpp" title=" Header
+ <boost/sync/locks/lock_guard.hpp>"><code class="computeroutput">lock_guard</code></a> controls the ownership
+ of a lockable object within a scope. A <a href="index.html#boost_sync.reference.locks_hpp.lock_guard_hpp" title=" Header
+ <boost/sync/locks/lock_guard.hpp>"><code class="computeroutput">lock_guard</code></a> object maintains ownership
+ of a lockable object throughout the <a href="index.html#boost_sync.reference.locks_hpp.lock_guard_hpp" title=" Header
+ <boost/sync/locks/lock_guard.hpp>"><code class="computeroutput">lock_guard</code></a> object's lifetime.
+ The behavior of a program is undefined if the lockable object referenced
+ by <code class="computeroutput">pm</code> does not exist for
+ the entire lifetime of the <a href="index.html#boost_sync.reference.locks_hpp.lock_guard_hpp" title=" Header
+ <boost/sync/locks/lock_guard.hpp>"><code class="computeroutput">lock_guard</code></a> object. <code class="computeroutput">BasicLockable</code> shall meet the <a href="index.html#boost_sync.reference.Locables.BasicLockable" title=" BasicLockable
+ Requirements "><code class="computeroutput">BasicLockable</code></a> requirements.
+ 
+
+ <a href="index.html#boost_sync.reference.locks_hpp.lock_guard_hpp" title=" Header
+ <boost/sync/locks/lock_guard.hpp>"><code class="computeroutput">lock_guard</code></a> is very simple: on
+ construction it acquires ownership of the implementation of the <a href="index.html#boost_sync.reference.Locables.BasicLockable" title=" BasicLockable
+ Requirements "><code class="computeroutput">BasicLockable</code></a> concept supplied
+ as the constructor parameter. On destruction, the ownership is released.
+ This provides simple RAII-style locking of a <a href="index.html#boost_sync.reference.Locables.BasicLockable" title=" BasicLockable
+ Requirements "><code class="computeroutput">BasicLockable</code></a> object, to facilitate
+ exception-safe locking and unlocking. In addition, the <a href="index.html#boost_sync.reference.locks_hpp.lock_guard_hpp.constructor_adopt" title="
+ Constructor lock_guard(Lockable & m,boost::adopt_lock_t)"><code class="computeroutput">lock_guard(Lockable &
+ m,boost::adopt_lock_t)</code>
+ constructor</a> allows the <a href="index.html#boost_sync.reference.locks_hpp.lock_guard_hpp" title=" Header
+ <boost/sync/locks/lock_guard.hpp>"><code class="computeroutput">lock_guard</code></a> object to take ownership
+ of a lock already held by the current concurrent agent.
+ 
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="boost_sync.reference.locks_hpp.lock_guard_hpp.constructor"></a><a href="index.html#boost_sync.reference.locks_hpp.lock_guard_hpp.constructor" title="
+ Constructor lock_guard(Lockable & m)">
+ Constructor <code class="computeroutput">lock_guard(Lockable & m)</code></a>
+</h5></div></div></div>
+
+ Effects: Stores a reference to <code class="computeroutput">m</code>. Invokes <a href="index.html#boost_sync.reference.Locables.BasicLockable" title=" BasicLockable
+ Requirements "><code class="computeroutput">m.lock()</code></a>.
+ 
+
+ Throws: Any exception thrown by the
+ call to <a href="index.html#boost_sync.reference.Locables.BasicLockable" title=" BasicLockable
+ Requirements "><code class="computeroutput">m.lock()</code></a>.
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="boost_sync.reference.locks_hpp.lock_guard_hpp.constructor_adopt"></a><a href="index.html#boost_sync.reference.locks_hpp.lock_guard_hpp.constructor_adopt" title="
+ Constructor lock_guard(Lockable & m,boost::adopt_lock_t)">
+ Constructor <code class="computeroutput">lock_guard(Lockable & m,boost::adopt_lock_t)</code></a>
+</h5></div></div></div>
+
+ Precondition: The current thread owns
+ a lock on <code class="computeroutput">m</code> equivalent
+ to one obtained by a call to <a href="index.html#boost_sync.reference.Locables.BasicLockable" title=" BasicLockable
+ Requirements "><code class="computeroutput">m.lock()</code></a>.
+ 
+
+ Effects: Stores a reference to <code class="computeroutput">m</code>. Takes ownership of the lock state
+ of <code class="computeroutput">m</code>.
+ 
+
+ Throws: Nothing.
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="boost_sync.reference.locks_hpp.lock_guard_hpp.destructor"></a><a href="index.html#boost_sync.reference.locks_hpp.lock_guard_hpp.destructor" title="
+ Destructor ~lock_guard()">
+ Destructor <code class="computeroutput">~lock_guard()</code></a>
+</h5></div></div></div>
+
+ Effects: Invokes <a href="index.html#boost_sync.reference.Locables.BasicLockable" title=" BasicLockable
+ Requirements "><code class="computeroutput">m.unlock()</code></a>
+ on the <a href="index.html#boost_sync.reference.Locables.BasicLockable" title=" BasicLockable
+ Requirements "><code class="computeroutput">BasicLockable</code></a> object passed
+ to the constructor.
+ 
+
+ Throws: Nothing.
+ 
+</div>
+</div>
+</div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="boost_sync.appendices"></a>Appendices
+</h2></div></div></div>
+<div class="toc"><dl>
+<dt> Appendix A: History</dt>
+<dd><dl><dt>Version 0.1.0, September 10, 2010 </dt></dl></dd>
+<dt> Appendix B: Rationale</dt>
+<dt><a href="index.html#boost_sync.appendices.implementation"> Appendix C: Implementation
+ Notes</a></dt>
+<dt> Appendix D: FAQ</dt>
+<dt><a href="index.html#boost_sync.appendices.acknowledgements"> Appendix E:
+ Acknowledgements</a></dt>
+<dt> Appendix F: Tests</dt>
+<dd><dl><dt>lockable_traits</dt></dl></dd>
+<dt> Appendix G: Tickets</dt>
+</dl></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_sync.appendices.history"></a> Appendix A: History
+</h3></div></div></div>
+<div class="toc"><dl><dt>Version 0.1.0, September 10, 2010 </dt></dl></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.appendices.history.__version_0_1_0__september_10__2010__"></a>Version 0.1.0, September 10, 2010
+</h4></div></div></div>
+
+ Features:
+ 
+<div class="itemizedlist"><ul type="disc"><li>
+ </li></ul></div>
+</div>
+</div>
+<div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title">
+<a name="boost_sync.appendices.rationale"></a> Appendix B: Rationale
+</h3></div></div></div></div>
+<div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title">
+<a name="boost_sync.appendices.implementation"></a><a href="index.html#boost_sync.appendices.implementation" title=" Appendix C: Implementation
+ Notes"> Appendix C: Implementation
+ Notes</a>
+</h3></div></div></div></div>
+<div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title">
+<a name="boost_sync.appendices.faq"></a> Appendix D: FAQ
+</h3></div></div></div></div>
+<div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title">
+<a name="boost_sync.appendices.acknowledgements"></a><a href="index.html#boost_sync.appendices.acknowledgements" title=" Appendix E:
+ Acknowledgements"> Appendix E:
+ Acknowledgements</a>
+</h3></div></div></div></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_sync.appendices.tests"></a> Appendix F: Tests
+</h3></div></div></div>
+<div class="toc"><dl><dt>lockable_traits</dt></dl></div>
+
+ In order to test you need to do.
+ 
+<pre class="programlisting">bjam libs/lockable_traits/test
+</pre>
+
+ You can also run a specific suite of test by doing
+ 
+<pre class="programlisting">cd libs/lockable_traits/test
+bjam lockable_traits
+</pre>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_sync.appendices.tests._lockable_traits_"></a>lockable_traits
+</h4></div></div></div>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Name
+ 
+ </th>
+<th>
+ 
+ kind
+ 
+ </th>
+<th>
+ 
+ Description
+ 
+ </th>
+<th>
+ 
+ Result
+ 
+ </th>
+<th>
+ 
+ Ticket
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ ratio_fail_test1
+ 
+ </td>
+<td>
+ 
+ compile-fails
+ 
+ </td>
+<td>
+ 
+ ...
+ 
+ </td>
+<td>
+ 
+ Pass
+ 
+ </td>
+<td>
+ 
+ #
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ ratio_test
+ 
+ </td>
+<td>
+ 
+ run
+ 
+ </td>
+<td>
+ 
+ ...
+ 
+ </td>
+<td>
+ 
+ Pass
+ 
+ </td>
+<td>
+ 
+ #
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_sync.appendices.tickets"></a> Appendix G: Tickets
+</h3></div></div></div>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<tbody><tr>
+<td>
+ 
+ Ticket
+ 
+ </td>
+<td>
+ 
+ Description
+ 
+ </td>
+<td>
+ 
+ Resolution
+ 
+ </td>
+<td>
+ 
+ State
+ 
+ </td>
+</tr></tbody>
+</table></div>
+</div>
+</div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left">Last revised: September 12, 2010 at 16:29:47 GMT</td>
+<td align="right"><div class="copyright-footer"></div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav"></div>
+</body>
+</html>

Added: sandbox/sync/libs/sync/doc/html/standalone_HTML.manifest
==============================================================================
--- (empty file)
+++ sandbox/sync/libs/sync/doc/html/standalone_HTML.manifest 2010-09-12 14:55:30 EDT (Sun, 12 Sep 2010)
@@ -0,0 +1 @@
+index.html

Added: sandbox/sync/libs/sync/doc/index.html
==============================================================================
--- (empty file)
+++ sandbox/sync/libs/sync/doc/index.html 2010-09-12 14:55:30 EDT (Sun, 12 Sep 2010)
@@ -0,0 +1,9 @@
+<html>
+<head>
+<meta http-equiv="refresh" content="0; URL=html/index.html">
+</head>
+<body>
+Automatic redirection failed, please go to
+../../doc/html/locakble_traits.html
+</body>
+</html>

Added: sandbox/sync/libs/sync/doc/sync.qbk
==============================================================================
--- (empty file)
+++ sandbox/sync/libs/sync/doc/sync.qbk 2010-09-12 14:55:30 EDT (Sun, 12 Sep 2010)
@@ -0,0 +1,1214 @@
+[/
+ / Copyright (c) 2008 Howard Hinnant
+ / Copyright (c) 2006, 2008 Beman Dawes
+ / Copyright (c) 2009-20010 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)
+ /]
+
+[article Boost.Sync
+ [quickbook 1.5]
+ [version 0.1.0]
+ [authors [Botet Escriba, Vicente J.]]
+ [copyright 2009-2010 Vicente J. Botet Escriba]
+ [license
+ 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])
+ ]
+]
+
+[template basic_lockable_req_link[link_text] [link boost_sync.reference.Locables.BasicLockable [link_text]]]
+[def __basic_lockable_req__ [basic_lockable_req_link `BasicLockable`]]
+
+[template lockable_req_link[link_text] [link boost_sync.reference.Locables.Lockable [link_text]]]
+[def __lockable_req__ [lockable_req_link `Lockable`]]
+
+
+[def __lock_guard__ [link boost_sync.reference.locks_hpp.lock_guard_hpp `lock_guard`]]
+
+[template lock_ref_link[link_text] [link boost_sync.reference.Locables.BasicLockable [link_text]]]
+[def __lock_ref__ [lock_ref_link `lock()`]]
+
+[template unlock_ref_link[link_text] [link boost_sync.reference.Locables.BasicLockable [link_text]]]
+[def __unlock_ref__ [unlock_ref_link `unlock()`]]
+
+
+[/==================]
+[def __Boost_Sync__ [*Boost.Sync]]
+
+
+[warning Sync is not part of the Boost libraries.]
+
+[/===============]
+[section Overview]
+[/===============]
+
+
+[/====================================]
+[heading How to Use This Documentation]
+[/====================================]
+
+This documentation makes use of the following naming and formatting conventions.
+
+* Code is in `fixed width font` and is syntax-highlighted.
+* Replaceable text that you will need to supply is in [~italics].
+* Free functions are rendered in the code font followed by (), as in free_function().
+* If a name refers to a class template, it is specified like this: `class_template<>`; that is, it is in code font and its name is followed by `<>` to indicate that it is a class template.
+* If a name refers to a function-like macro, it is specified like this: `MACRO()`;
+ that is, it is uppercase in code font and its name is followed by `()` to indicate that it is a function-like macro. Object-like macros appear without the trailing `()`.
+* Names that refer to /concepts/ in the generic programming sense are specified in CamelCase.
+
+[note In addition, notes such as this one specify non-essential information that provides additional background or rationale.]
+
+Finally, you can mentally add the following to any code fragments in this document:
+
+ // Include all of Sync files
+ #include <boost/sync.hpp>
+ using namespace boost::sync;
+
+[/=================]
+[section Motivation]
+[/=================]
+
+
+The goal of Boost.Sync is to remove the syntactic differences between the synchronization mechanisms of the Boost.Thread and Boost::Interprocess libraries and be a holder of common mechanism and algorithms working on the common concepts.
+
+The differences I have identified up to now are:
+
+ * The scoped locks can be initialized with static const variables in order to overload the constructor for lock adoption, lock deferral or try to lock. Even if the name of these variables is almost the same, these variables live in different namespace. It would be nice if both libraries use the same type and the same variables.
+
+ * The shared mutex provide similar service with different names. In addition each implementation provide some functions that are not provided by the other.
+
+ * The scoped locks live in a different namespace and some have different names with the same semantic. IMO these should be shared.
+
+ * The exception thrown lives in a different name space and different names with equivalent semantics If we follow the C++0x standard the exception to throw should be system_error. Both libraries could adapt his hierarchy to Boost.System. The drawback is that users of Boost.Thread and Boost.Interprocess will need to link with Boost.System which is not a header only library.
+
+ * The move semantics (&&) of Boost.Thread should be adapted to the forthcoming Boost.Move library as soon as integrated on the release branch. Boost.Interprocess uses already a detail implementation equivalent to the provided by Boost.Move, so the change will be simpler.
+
+ * Adapt both libraries interface to use Boost.Chrono, which is yet a non header only library, once it is accepted.
+
+Of course, this needs some adaptation of the Thread and Interprocess libraries.
+
+
+This library proposes some classes that make easier to write code that can be used indistinguishably with thread or interprocess synchronization mechanisms. This section is inspired on the work from [*C++ Threading - A Generic-Programming Approach] - Kevlin Henney.
+
+
+
+[endsect]
+
+[/==================]
+[section Description]
+[/==================]
+
+__Boost_Sync__ provides a uniform usage of Boost.Thread and Boost.Interprocess synchronization mechanisms based on:
+
+* share the lock options between both libraries
+* lockable concepts.
+* lockable traits
+* null_mutex and null_condition classes,
+
+
+[/*
+ * lockable inverse traits
+ * Add some common locks as
+ o strict_lock, nested_strict_lock,
+ o reverse_lock, nested_reverse_lock,
+ * A polymorphic lockable hierarchy.
+]
+
+[endsect]
+
+[endsect]
+
+
+[/==============================]
+[section:users_guide Users'Guide]
+[/==============================]
+
+[/======================================]
+[section:getting_started Getting Started]
+[/======================================]
+
+[/======================================]
+[section:install Installing Sync]
+[/======================================]
+
+[/=================================]
+[heading Getting Boost.Sync ]
+[/=================================]
+
+You can get the last stable release of __Boost_Sync__ by downloading [^sync.zip] from the
+[@http://www.boost-consulting.com/vault/index.php?directory=ConcurrentProgramming Boost Vault].
+
+You can also access the latest (unstable?) state from the [@https://svn.boost.org/svn/boost/sandbox/sync Boost Sandbox]. Just go to [@http://svn.boost.org/trac/boost/wiki/BoostSubversion here] and follow the instructions there for anonymous SVN access.
+
+[/==========================================]
+[heading Where to install Boost.Sync? ]
+[/==========================================]
+
+The simple way is to decompress (or checkout from SVN) the file in your BOOST_ROOT directory.
+
+Othesewise, if you decompress in a different directory, you will need to comment some lines, and uncomment and change others in the build/Jamfile and test/Jamfile. Sorry for this, but I have not reached yet to write a Jamfile that is able to work in both environements and use the BOOST_ROOT variable. Any help is welcome.
+
+[/=================================]
+[heading Building Boost.Sync ]
+[/=================================]
+
+__Boost_Sync__ is a header only library, so no need to compile anything.
+
+
+[/===================]
+[heading Requirements]
+[/===================]
+
+__Boost_Sync__ depends on some Boost libraries. For these specific parts you must use either Boost version 1.39.0 or the version in SVN trunk (even if older versions should works also).
+
+In particular, __Boost_Sync__ depends on:
+
+[variablelist
+[
+ [[@http://www.boost.org/libs/config [*Boost.Config]]] [for configuration purposes, ...]
+]
+[
+ [[@http://www.boost.org/libs/integer [*Boost.Integer]]] [for cstdint conformance, and integer traits ...]
+]
+[
+ [[@http://www.boost.org/libs/mpl [*Boost.MPL]]] [for MPL Assert and bool, logical ...]
+]
+[
+ [[@http://www.boost.org/libs/static_assert [*Boost.StaticAssert]]] [for STATIC_ASSERT, ...]
+]
+[
+ [[@http://www.boost.org/libs/type_traits [*Boost.TypeTraits]]] [for is_base, is_convertible ...]
+]
+[
+ [[@http://www.boost.org/libs/utility [*Boost.Utility/EnableIf]]] [for enable_if, ...]
+]
+]
+
+
+[/=========================================================]
+[heading Building an executable that uses __Boost_Sync__ ]
+[/=========================================================]
+
+No link is needed.
+
+
+[/=========================]
+[heading Exceptions safety ]
+[/=========================]
+
+All functions in the library are exception-neutral and provide strong guarantee of exception safety as long as the underlying parameters provide it.
+
+[/=====================]
+[heading Thread safety ]
+[/=====================]
+
+All functions in the library are thread-unsafe except when noted explicitly.
+
+[/========================]
+[heading Tested compilers ]
+[/========================]
+
+The implementation will eventually work with most C++03 conforming compilers. Current version has been tested on:
+
+Windows with
+
+* MSVC 10.0
+* MSVC 9.0 Express
+* MSVC 8.0
+
+[/* Intel 11.0]
+
+Scientific Linux with
+
+* GCC 4.1.2
+
+Cygwin with
+
+* GCC 3.4.4
+* GCC 4.3.4
+
+MinGW with
+
+* GCC 4.4.0
+
+Initial version was tested on:
+
+MacOS with GCC 4.2.4
+
+Ubuntu Linux with GCC 4.2.4
+
+[note Please let us know how this works on other platforms/compilers.]
+
+[note Please send any questions, comments and bug reports to boost <at> lists <dot> boost <dot> org.]
+
+[endsect]
+[/
+[/====================]
+[section Hello World! ]
+[/====================]
+
+
+ #include <boost/lockable_traits.hpp>
+
+
+[endsect]
+]
+[endsect]
+
+[/===============]
+[section Tutorial]
+[/===============]
+
+[section Lockable traits]
+
+[*Lockable substitutability]
+
+The Boost mutexes have associated an implicit category which form a sub-typing hierarchy:
+
+ BasicLockable > TryLockable <- TimedLockable
+
+Locking behavior can be further categorized as:
+
+* Ownership: (concurrent agent affinity): owned or unowned
+
+An owned lockable can be sustituted by any unowned lockable.
+
+ owned <- unowned
+
+* Share: When a lockable is owned by the concurrent agent, this ownership can be either exclusive or shared. When shared ownership is considered there is yet the possibility to change at run-time from shared to exclusive and viceversa. We talk of upgradable lockables.
+
+ ExclusiveLockable <- SharedLockable <- UpgradeLockable
+
+* Re-entrancy: When a lockable is owned by the concurrent agent, the ownership can be done recursively or not
+
+ non_recursive <- recursive
+
+* Scope: This is related to the kind of concurrent agents that can own the lockable. Currently the library takes in account mono-threaded, multi-threaded or multi-process contexts.
+
+ mono_threaded <- multi_threaded <- multi_process
+
+* Lifetime: The lifetime of a lock could be associated to the process, the kernel or the file-system
+
+ process_lifetime <- kernel_lifetime <- filesystem_lifetime
+
+
+Substitutability applies both to the degree of syntactic support and to the locking semantics
+
+* A recursive mutex and binary semaphore are substitutable in code written against a exclusive mutex
+* A null mutex is substitutable for all others in a single-threaded environment
+
+
+We can see these axes of variation expressed against some Boost synchronization mechanisms (from now bip stands for boost::interprocess):
+
+* `boost::mutex`: ExclusiveLockable, owned, non-recursive, multi-threaded
+* `boost::shared_mutex`: UpgradeableBasicLockable, owned, non-recursive, multi-threaded
+* `bip::sync::null_mutex`: UpgradableTimedLockable, unowned, recursive, mono-threaded
+* `bip::sync::interprocess_recursive_mutex`: ExclusiveTimedLockable, owned, recursive, multi_process.
+
+
+__Boost_Sync__ provides a set of very specific traits classes, some of them encapsulate a single trait for a `Lockable` type; for example, is a lockable recursive (`is_recursive`), is useful in a multi threaded context
+(`is_multi_threaded`).
+
+The __Boost_Sync__ lockable traits classes share a unified design that mimic the one of Boost.TypeTraits: each class inherits from a the type `true_type` if the type has the specified property and inherits from `false_type` otherwise.
+
+The __Boost_Sync__ library also contains a set of classes that perform a specific transformation on a type. Each class that performs a transformation defines a single typedef-member type that is the result of the transformation.
+
+All of the locakble traits classes are defined inside namespace boost::lockable.
+
+[*tag trait implementation]
+
+Most of the implementation is fairly repetitive anyway, so here we will just give you a flavor for how some of the classes are implemented. See the reference section for the full details.
+
+The library defines a tag hierarchy associated to a trait. For example for the scope trait:
+
+ struct mono_threaded_tag {};
+ struct multi_threaded_tag : mono_threaded_tag {};
+ struct multi_process_tag : multi_threaded_tag {};
+
+By default the `scope` trait forward to a nested type `scope`.
+
+ template <typename Lockable>
+ struct scope {
+ typedef typename Lockable::scope type;
+ };
+
+In order to make a type a model of `Lockable` we have two possibilities:
+
+* declare the nested type `scope`
+
+ class my_mutex {
+ public:
+ typedef <a scope tag> scope;
+ // ...
+ };
+
+* specialize the class template `sync::scope`
+
+ template<>
+ struct scope_tag<my_mutex> {
+ typedef multi_threaded_tag type;
+ };
+
+[*lockable_base helper]
+
+The library provis also a mixin class `lockable_base` which will define all the needed nested typedefs.
+
+ template<
+ typename Scope=multi_threaded_tag,
+ typename Category=exclusive_tag,
+ typename Reentrancy=non_recursive_tag,
+ typename Kind=timed_lockable_tag,
+ typename Lifetime=typename default_lifetime<Scope>,
+ typename Named=anonymous_tag,
+ typename Base=void
+ > struct lockable_base;
+
+which defines the correct types. The `lockable_base` has a lot of parameters, and the defaults are the ones associated to `boost::mutex`. So Boost.Thread could use it as follows
+
+ class mutex : public lockable_base<> {
+ // ...
+ };
+
+[/
+Waiting for that __Boost_Sync__ specialize the scope in the locable_traits/adapters/thread/mutex.hpp file.
+
+ template<>
+ struct scope<boost::mutex> {
+ typedef multi_threaded_tag type;
+ };
+
+So the user must include this file to make `boost::mutex` a model of `Lockable` for `__Boost_Sync__`.
+]
+
+[*is_trait implementation]
+
+For example the trait `is_multi_threaded` is defined as : If Lockable has `scope` trait is the same or inherits from `multi_threaded_tag` then it is `true_type`, otherwise it is `false_type`.
+
+ template <typename Lockable>
+ struct is_multi_threaded
+ : is_same_or_is_base_and_derived<
+ multi_threaded_tag,
+ typename scope<Lockable>::type
+ >
+ {};
+
+[endsect]
+
+[section Lockable generators]
+[*Finding the best lock]
+
+Inverse traits can match a lockable type based on specific traits, form a given family of lockable types.
+
+It is also possible to specify characteristics to perform a reverse lookup to find a primitive lockable type, either by exact match or by substitutable match.
+
+ find_best_lock<>::type == boost::mutex
+ find_best_lock<mono_threaded_tag>::type == bsync::null_mutex
+ find_best_lock<multi_threaded_tag>::type == bsync::thread_mutex
+ find_best_lock<multi_process_tag>::type == bsync::interprocess_mutex
+
+The user can also find a lockable using mpl constraints as follows
+
+ typedef find_best_lock_between<Lockables,
+ mpl::and<is_multi_threaded<_>, is_recursive<_> > >::type best;
+
+[endsect]
+
+[section Lockable concepts]
+
+For the main category clasification, the library provides concept classes that can be used with Boost.ConceptCheck. For example `LockableConcept` object supports the basic features required to delimit a critical region. Supports the basic `lock`, `unlock` and `try_lock` functions and defines the lock traits.
+
+ template <typename Lockable>
+ struct BasicLockableConcept {
+ typedef typename category<Lockable>::type category;
+ typedef typename kind<Lockable>::type kind;
+ typedef typename reentrancy<Lockable>::type reentrancy;
+ typedef typename scope<Lockable>::type scope;
+ typedef typename lifetime<Lockable>::type lifetime;
+ typedef typename named<Lockable>::type named;
+
+ BOOST_CONCEPT_USAGE(BasicLockableConcept) {
+ l.lock();
+ l.unlock();
+ }
+ Lockable& l;
+ };
+
+The user can now check staticaly that the template parameter is a model of BasicLocable as follows
+
+ #include "boost/sync/lockable_concepts.hpp"
+ template <typename Lockable>
+ class my_class {
+ BOOST_CONCEPT_ASSERT((BasicLockableConcept<Lockable>));
+ // ...
+ };
+
+The same can be done for `TimedLockableConcept`, `ShareLockableConcept` and `UpgradeLockableConcept` (See the reference section for more details).
+
+[endsect]
+
+[endsect]
+[/===============]
+[section Examples]
+[/===============]
+
+
+[/'See the source file [@../../test/ratio_test.cpp test/ratio_test.cpp]]
+
+[endsect]
+
+
+
+
+[/================================]
+[section:ext_references External Resources]
+[/================================]
+
+[variablelist
+
+[
+ [[@http://www.open-std.org/jtc1/sc22/wg21 [*C++ Standards Committee's current Working Paper]]]
+ [The most authoritative reference material for the library is the C++ Standards Committee's current Working Paper (WP). 30 - Thread support library ]
+]
+
+[
+ [[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3130.html [*N3130 - Lockable requirements for C++0x]]]
+ [From Anthony Williams.]
+]
+
+[
+ [[@http:/www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1883.pdf
+ [*N1833 - Preliminary Threading Library Proposal for TR2]]]
+ [Kevlin Henney, 2005]
+]
+
+[
+ [[@http://www.two-sdg.demon.co.uk/curbralan/papers/accu/MoreC++Threading.pdf
+ [*More C++ Threading - From Procedural to Generic, by Example]]]
+ [Kevlin Henney]
+]
+[
+ [[@http://www.two-sdg.demon.co.uk/curbralan/papers/accu/C++Threading.pdf
+ [*C++ Threading - A Generic-Programming Approach]]]
+ [Kevlin Henney, April 16, 2004]
+]
+
+]
+
+[endsect]
+
+[endsect]
+
+[/=================]
+[section:reference Reference ]
+[/=================]
+
+[/===========================================]
+[section:sync_hpp Header `<boost/sync.hpp>`]
+[/===========================================]
+
+ #include <boost/sync/lockable_traits.hpp>
+ #include <boost/sync/lockable_concepts.hpp>
+ #include <boost/sync/locks.hpp>
+
+[endsect]
+
+
+[/===========================================]
+[section:lockable_traits_hpp Header `<boost/sync/lockable_traits.hpp>`]
+[/===========================================]
+
+ #include <boost/sync/lockable_traits/category.hpp>
+ #include <boost/sync/lockable_traits/reentrancy.hpp>
+ #include <boost/sync/lockable_traits/scope.hpp>
+ #include <boost/sync/lockable_traits/ownership.hpp>
+ #include <boost/sync/lockable_traits/lifetime.hpp>
+ #include <boost/sync/lockable_traits/naming.hpp>
+ #include <boost/sync/lockable_traits/lock_traits_base.hpp>
+ #include <boost/sync/lockable_traits/best_condition_variable.hpp>
+ #include <boost/sync/lockable_traits/generic_condition_variable.hpp>
+
+
+
+[/===========================================]
+[section:category_hpp Header `<boost/sync/lockable_traits/category.hpp>`]
+[/===========================================]
+
+ namespace boost { namespace sync {
+
+ struct exclusive_basic_lockable_tag;
+ struct exclusive_try_lockable_tag;
+ struct exclusive_timed_lockable_tag;
+ struct sharable_basic_lockable_tag;
+ struct sharable_try_lockable_tag;
+ struct sharable_timed_lockable_tag;
+ struct upgradable_basic_lockable_tag;
+ struct upgradable_try_lockable_tag;
+ struct upgradable_timed_lockable_tag;
+ template <typename Lockable> struct category;
+
+ template <typename Lockable> struct is_basic_lockable;
+ template <typename Lockable> struct is_try_lockable;
+ template <typename Lockable> struct is_timed_lockable;
+ template <typename Lockable> struct is_exclusive;
+ template <typename Lockable> struct is_sharable;
+ template <typename Lockable> struct is_upgradable;
+ }
+
+[endsect]
+
+[/===========================================]
+[section:reentrancy_hpp Header `<boost/sync/lockable_traits/reentrancy.hpp>`]
+[/===========================================]
+
+ namespace boost { namespace sync {
+
+ struct non_recursive_tag;
+ struct recursive_tag;
+ template <typename Lockable> struct reentrancy;
+
+ template <typename Lockable> struct is_recursive;
+ }
+
+[endsect]
+
+[/===========================================]
+[section:scope_hpp Header `<boost/sync/lockable_traits/scope.hpp>`]
+[/===========================================]
+
+ namespace boost { namespace sync {
+
+ struct mono_threaded_tag;
+ struct multi_threaded_tag;
+ struct multi_process_tag;
+ template <typename Lockable> struct scope;
+
+ template <typename Lockable> struct is_mono_threaded;
+ template <typename Lockable> struct is_multi_threaded;
+ template <typename Lockable> struct is_multi_process;
+ }
+
+
+[endsect]
+
+[/===========================================]
+[section:ownership_hpp Header `<boost/sync/lockable_traits/ownership.hpp>`]
+[/===========================================]
+
+ namespace boost { namespace sync {
+
+ struct unowned_tag;
+ struct owned_tag;
+ template <typename Lockable> struct ownership;
+
+ template <typename Lockable> struct is_owned;
+ }
+
+[endsect]
+
+[/===========================================]
+[section:lifetime_hpp Header `<boost/sync/lockable_traits/lifetime.hpp>`]
+[/===========================================]
+
+ namespace boost { namespace sync {
+
+ struct process_lifetime_tag;
+ struct kernel_lifetime_tag;
+ struct filesystem_lifetime_tag;
+ template <typename Lockable> struct lifetime;
+
+ template <typename Lockable> struct has_process_lifetime;
+ template <typename Lockable> struct has_kernel_lifetime;
+ template <typename Lockable> struct has_filesystem_lifetime;
+
+ }
+
+[endsect]
+
+[/===========================================]
+[section:name_hpp Header `<boost/sync/lockable_traits/naming.hpp>`]
+[/===========================================]
+
+ namespace boost { namespace sync {
+
+ struct anonymous_tag;
+ struct named_tag;
+ template <typename Lockable> struct naming;
+ template <typename Lockable> struct is_named;
+
+ }
+
+[endsect]
+
+
+[/===========================================]
+[section:lockable_base_hpp Header `<boost/sync/lockable_traits/lockable_base.hpp>`]
+[/===========================================]
+
+ namespace boost { namespace sync {
+
+ template<typename Scope> struct default_lifetime;
+
+ template<
+ typename Scope=multi_threaded_tag,
+ typename Category=exclusive_tag,
+ typename Reentrancy=non_recursive_tag,
+ typename Kind=timed_lockable_tag,
+ typename Lifetime=typename default_lifetime<Scope>,
+ typename Named=anonymous_tag,
+ typename Base=void
+ > struct lockable_base;
+ }
+
+[endsect]
+
+[endsect]
+
+[/===========================================]
+[section:Locables Requirements for Lockable types ]
+[/===========================================]
+
+A concurrent agent is a an entity (such as a thread, process, or packaged task) that may perform work in parallel with other concurrent agents. The calling agent is determined by context, e.g. the calling thread or the packaged task that contains the call, etc.
+
+The standard and also the Boost.Thread and Boost.Interprocess library templates `unique_lock`, `lock_guard`, `lock`, `try_lock` and `condition_variable_any` all operate on user-supplied lockable objects. Such an object must support the member functions specified for either the `BasicLockable` requirements, the `Lockable` requirements or the `TimedLockable` requirements as appropriate to acquire or release ownership of a lock by a given concurrent agent.
+
+[note The nature of any lock ownership and any synchronization it may entail are not part of these requirements.]
+
+[note Some lockable objects are "agent-oblivious" in that they work for any concurrent-agent model because they do not determine or store the agent's ID (e.g., an ordinary spin-lock).]
+
+[/===========================================]
+[section:BasicLockable BasicLockable Requirements ]
+[/===========================================]
+
+In order for a type `L` to qualify as a `BasicLockable` type, the following expressions must be supported, with the specified semantics, where `m` denotes a value of type `L`:
+
+The expression `m.lock()` shall be well-formed and have the following semantics:
+
+[*Effects:] Block until a lock can be acquired for the current concurrent agent. If an exception is thrown then a lock shall not have been acquired for the current concurrent agent.
+
+[*Return type:] void
+
+The expression `m.unlock()` shall be well-formed and have the following semantics:
+
+[*Requires:] The current concurrent agent shall hold a lock on `m`.
+
+[*Effects:] Release a lock on `m` held by the current concurrent agent.
+
+[*Return type:] `void`
+
+[*Throws:] Nothing.
+
+[endsect]
+
+[/===========================================]
+[section:TryLockable Lockable Requirements ]
+[/===========================================]
+
+In order for a type `L` to qualify as a `Lockable` type, it must meet the `BasicLockable` requirements. In addition, the following expressions must be supported, with the specified semantics, where m denotes a value of type `L`:
+
+The expression `m.try_lock()` shall be well-formed and have the following semantics:
+
+[*Effects:] Attempt to acquire a lock for the current concurrent agent without blocking. If an exception is thrown then a lock shall not have been acquired for the current concurrent agent.
+
+[*Return type:] `bool`
+
+[*Returns:] `true` if the lock was acquired, `false` otherwise.
+
+[endsect]
+
+[/===========================================]
+[section:TimedLockable TimedLockable Requirements ]
+[/===========================================]
+
+For a type `TL` to qualify as `TimedLockable` it must meet the Lockable requirements, and additionally the following expressions must be well-formed, with the specified semantics, where `m` is an instance of a type `TL`, `rel_time` denotes instantiation of `duration` and `abs_time` denotes an instantiation of `time_point`.
+
+The expression `m.try_lock_for(rel_time)` shall be well-formed and have the following semantics:
+
+[*Effects:] Attempt to acquire a lock for the current concurrent agent within the relative timeout specified by `rel_time`. The function shall return within the timeout specified by `rel_time` only if it has obtained a lock on `m` for the current concurrent agent. If an exception is thrown then a lock shall not have been acquired for the current concurrent agent.
+
+[*Return type:] `bool`
+
+[*Returns:] `true` if the lock was acquired, `false` otherwise.
+
+The expression `m.try_lock_until(abs_time)` shall be well-formed and have the following semantics:
+
+[*Effects:] Attempt to acquire a lock for the current concurrent agent before the absolute timeout specified by `abs_time`. The function shall return before the timeout specified by `abs_time` only if it has obtained a lock on `m` for the current concurrent agent. If an exception is thrown then a lock shall not have been acquired for the current concurrent agent.
+
+[*Return type:] `bool`
+
+[*Returns:] `true` if the lock was acquired, `false` otherwise.
+
+[endsect]
+
+[/===========================================]
+[section:SharedBasicLockable SharedBasicLockable Requirements ]
+[/===========================================]
+
+In order for a type `L` to qualify as a `SharedBasicLockable` type, it must meet the `BasicLockable` requirements. In addition, the following expressions must be supported, with the specified semantics, where `m` denotes a value of type `L`:
+
+The expression `is_shared_lockable<L>` is `true_type`.
+
+The expression `m.lock_shared()` shall be well-formed and have the following semantics:
+
+[*Effects:] Block until shared ownership can be acquired for the current concurrent agent. If an exception is thrown then a lock shall not have been acquired for the current concurrent agent.
+
+[*Return type:] `void`
+
+The expression `m.unlock_shared()` shall be well-formed and have the following semantics:
+
+[*Requires:] The current concurrent agent has shared onership on `m`.
+
+[*Effects:] Release shared ownership on `m` held by the current concurrent agent.
+
+[*Return type:] `void`
+
+[*Throws:] Nothing.
+
+[endsect]
+
+[/===========================================]
+[section:SharedLockable SharedLockable Requirements ]
+[/===========================================]
+
+In order for a type `L` to qualify as a `SharedLockable` type, it must meet the `SharedBasicLockable` and `Locable` requirements. In addition, the following expressions must be supported, with the specified semantics, where `m` denotes a value of type `L`:
+
+The expression `m.try_lock_shared()` shall be well-formed and have the following semantics:
+
+[*Effects:] Attempt to obtain shared ownership for the current concurrent agent without blocking. If an exception is thrown then a lock shall not have been acquired for the current concurrent agent.
+
+[*Return type:] `bool`
+
+[*Returns:] `true` if shared ownership was obtained for the current thread, `false` otherwise.
+
+[endsect]
+
+[/===========================================]
+[section:SharedTimedLockable SharedTimedLockable Requirements ]
+[/===========================================]
+
+For a type `TL` to qualify as `SharedTimedLockable` it must meet the `SharedLockable` and the `TimedLockable` requirements, and additionally the following expressions must be well-formed, with the specified semantics, where `m` is an instance of a type `TL`, `rel_time` denotes instantiation of duration and `abs_time` denotes an instantiation of time_point.
+
+The expression `m.try_lock_shared_for(rel_time)` shall be well-formed and have the following semantics:
+
+[*Effects:] Attempt to acquire a lock for the current concurrent agent within the relative timeout specified by `rel_time`. The function shall return within the timeout specified by rel_time only if it has obtained a lock on `m` for the current concurrent agent. If an exception is thrown then a lock shall not have been acquired for the current concurrent agent.
+
+[*Return type:] `bool`
+
+[*Returns:] `true` if the lock was acquired, `false` otherwise.
+
+The expression `m.try_lock_shared_until(abs_time)` shall be well-formed and have the following semantics:
+
+[*Effects:] Attempt to obtain shared ownership for the current concurrent agent before the absolute timeout specified by `abs_time`. The function shall return before the timeout specified by `abs_time` only if it has obtained shared ownership on m for the current concurrent agent. If an exception is thrown then shared ownership shall not have been acquired for the current concurrent agent.
+
+[*Return type:] `bool`
+
+[*Returns:] `true` if shared ownership was acquired, `false` otherwise.
+
+[endsect]
+
+[endsect]
+
+[/==========================================================================================]
+[section:lockable_concept_hpp Header `<boost/sync/lockable_concepts.hpp>`]
+[/==========================================================================================]
+
+ namespace boost { namespace sync {
+
+ template <typename Lockable> struct BasicLockableConcept;
+ template <typename Lockable> struct LockableConcept;
+ template <typename Lockable> struct TimedLockableConcept;
+ template <typename Lockable> struct ShareBasicLockableConcept;
+ template <typename Lockable> struct ShareLockableConcept;
+ template <typename Lockable> struct ShareTimedLockableConcept;
+ template <typename Lockable> struct UpgradeBasicLockableConcept;
+ template <typename Lockable> struct UpgradeLockableConcept;
+ template <typename Lockable> struct UpgradeTimedLockableConcept;
+
+ }}
+
+[section:BasicLockableConcept Template Class `BasicLockableConcept<>`]
+
+The `boost::mutex` and `boost:interprocess mutex family classes are a non-polymorphic classes that encapsulates a system primitive and portion of C API. Clearly, many of the synchronisation
+primitives support common operations, and hence a Concept.
+The `ExclusiveLockableConcept` class can be used with the Boost.ConceptCheck in templates that work with a exclusive synchronisation.
+
+`LockableConcept` object supports the basic features required to delimit a critical region. Supports the basic `lock`, `unlock` and `try_lock` functions and defines the lockable traits
+
+ template <typename Lockable>
+ struct BasicLockableConcept {
+ typedef typename category<Lockable>::type category;
+ typedef typename kind<Lockable>::type kind;
+ typedef typename reentrancy<Lockable>::type reentrancy;
+ typedef typename scope<Lockable>::type scope;
+ typedef typename lifetime<Lockable>::type lifetime;
+ typedef typename named<Lockable>::type named;
+
+ BOOST_CONCEPT_USAGE(LockableConcept) {
+ l.lock();
+ l.unlock();
+ }
+ Lockable l;
+ };
+
+[endsect]
+[section:LockableConcept Template Class `LockableConcept<>`]
+
+The `boost::mutex` and `boost:interprocess mutex family classes are a non-polymorphic classes that encapsulates a system primitive and portion of C API. Clearly, many of the synchronisation
+primitives support common operations, and hence a Concept.
+The `ExclusiveLockableConcept` class can be used with the Boost.ConceptCheck in templates that work with a exclusive synchronisation.
+
+`LockableConcept` object supports the basic features required to delimit a critical region. Supports the basic `lock`, `unlock` and `try_lock` functions and defines the lockable traits
+
+ template <typename Lockable>
+ struct LockableConcept {
+ BOOST_CONCEPT_ASSERT((BasicLockableConcept<Lockable>));
+
+ BOOST_CONCEPT_USAGE(LockableConcept) {
+ b=l.try_lock();
+ }
+ Lockable l;
+ bool b;
+ };
+
+[endsect]
+[section:TimedLockableConcept Template Class `TimedLockableConcept<>`]
+
+`TimedLockableConcept` object extends `ExclusiveLockConcept` with the `try_lock_until` and `try_lock_for` functions.
+
+ template <typename Lockable>
+ struct TimedLockableConcept {
+ BOOST_CONCEPT_ASSERT((LockableConcept<Lockable>));
+
+ BOOST_CONCEPT_USAGE(TimedLockableConcept) {
+ b=l.try_lock_until(t);
+ b=l.try_lock_for(boost::chrono::seconds(1));
+ }
+ Lockable l;
+ boost::chrono::system_clock::time_point t;
+ bool b;
+ };
+
+[endsect]
+[section:ShareBasicLockableConcept Template Class `ShareBasicLockableConcept<>`]
+
+`ShareBasicLockableConcept` object extends `BasicLockableConcept` with the `lock_shared` and `unlock_shared` functions
+
+ template <typename Lockable>
+ struct ShareBasicLockableConcept {
+ BOOST_CONCEPT_ASSERT((BasicLockableConcept<Lockable>));
+
+ BOOST_CONCEPT_USAGE(ShareBasicLockableConcept) {
+ l.lock_shared();
+ l.unlock_shared();
+ }
+ Lockable l;
+ };
+
+
+[endsect]
+[section:ShareLockableConcept Template Class `ShareLockableConcept<>`]
+
+`ShareLockableConcept` object extends `ShareBasicLockableConcept` and `LockableConcept` with the `try_lock_shared` functions.
+
+ template <typename Lockable>
+ struct ShareLockableConcept {
+ BOOST_CONCEPT_ASSERT((ShareBasicLockableConcept<Lockable>));
+ BOOST_CONCEPT_ASSERT((LockableConcept<Lockable>));
+
+ BOOST_CONCEPT_USAGE(ShareLockableConcept) {
+ b=l=.try_lock_shared();
+ }
+ Lockable l;
+ boost::chrono::system_clock::time_point t;
+ bool b;
+ };
+
+
+[endsect]
+[section:ShareTimedLockableConcept Template Class `ShareTimedLockableConcept<>`]
+
+`ShareTimedLockableConcept` object extends `ShareBasicLockableConcept` and `LockableConcept` with the `try_lock_shared_until` and `try_lock_shared_for` functions
+
+ template <typename Lockable>
+ struct ShareLockableConcept {
+ BOOST_CONCEPT_ASSERT((ShareBasicLockableConcept<Lockable>));
+ BOOST_CONCEPT_ASSERT((LockableConcept<Lockable>));
+
+ BOOST_CONCEPT_USAGE(ShareLockableConcept) {
+ b=l.try_lock_shared_until(t);
+ b=l.try_lock_shared_for(boost::chrono::seconds(1));
+ }
+ Lockable& l;
+ boost::chrono::system_clock::time_point t;
+ bool b;
+ };
+
+
+[endsect]
+[section:UpgradeBasicLockableConcept Template Class `UpgradeBasicLockableConcept<>`]
+
+`UpgradeBasicLockableConcept` object extends `SharedBasicLockableConcept` with the `lock_upgrade`, `unlock_upgrade`, `unlock_upgrade_and_lock`, `unlock_and_lock_shared` and `unlock_upgrade_and_lock_shared` functions.
+
+ template <typename Lockable>
+ struct UpgradeBasicLockableConcept {
+ BOOST_CONCEPT_ASSERT((SharedBasicLockableConcept<Lockable>));
+
+ BOOST_CONCEPT_USAGE(UpgradeBasicLockableConcept) {
+ l.lock_upgrade();
+ l.unlock_upgrade();
+ l.unlock_upgrade_and_lock();
+ l.unlock_and_lock_upgrade();
+ l.unlock_and_lock_shared();
+ l.unlock_upgrade_and_lock_shared();
+ }
+ Lockable& l;
+ boost::chrono::system_clock::time_point t;
+ };
+
+[endsect]
+[section:UpgradeLockableConcept Template Class `UpgradeLockableConcept<>`]
+
+`UpgradeLockableConcept` object extends `UpgradeBasicLockableConcept` and `SharedLockableConcept` with the `try_lock_upgrade`, `try_unlock_upgrade_and_lock`, `try_unlock_share_and_lock` and `try_unlock_share_and_lock_upgrade` functions.
+
+
+ template <typename Lockable>
+ struct UpgradeLockableConcept {
+ BOOST_CONCEPT_ASSERT((UpgradeBasicLockableConcept<Lockable>));
+
+ BOOST_CONCEPT_USAGE(UpgradeLockableConcept) {
+ b=l.try_lock_upgrade();
+ b=l.try_unlock_upgrade_and_lock();
+ b=l.try_unlock_share_and_lock();
+ b=l.try_unlock_share_and_lock_upgrade();
+ }
+ Lockable& l;
+ boost::chrono::system_clock::time_point t;
+ bool b;
+ };
+
+
+
+[endsect]
+[section:UpgradeTimedLockableConcept Template Class `UpgradeTimedLockableConcept<>`]
+
+`UpgradeTimedLockableConcept` object extends `UpgradeLockableConcept` and `SharedTimedLockableConcept` with the `try_lock_upgrade_until`, `try_lock_upgrade_for`, `try_unlock_upgrade_and_lock_for` and `try_unlock_upgrade_and_lock_until` functions.
+
+
+ template <typename Lockable>
+ struct UpgradeLockableConcept {
+ BOOST_CONCEPT_ASSERT((UpgradeBasicLockableConcept<Lockable>));
+
+ BOOST_CONCEPT_USAGE(UpgradeLockableConcept) {
+ b=l.try_lock_upgrade_until(t);
+ b=l.try_lock_upgrade_for(d);
+ b=l.try_unlock_upgrade_and_lock_for(d);
+ b=l.try_unlock_upgrade_and_lock_until(t);
+ }
+ Lockable& l;
+ boost::chrono::system_clock::time_point t;
+ bool b;
+ };
+
+
+
+[endsect]
+[endsect]
+
+[/===========================================]
+[section:locks_hpp Header `<boost/sync/locks.hpp>`]
+[/===========================================]
+
+ #include <boost/sync/locks/lock_options.hpp>
+ #include <boost/sync/locks/lock_guard.hpp>
+
+
+
+[/===========================================]
+[section:lock_options_hpp Header `<boost/sync/locks/lock_options.hpp>`]
+[/===========================================]
+
+Some lock constructors take tag types which describe what should be done with the lockable object during
+the lock's construction.
+
+ namespace boost {
+
+ //!Type to indicate to a mutex lock constructor that must not lock the mutex.
+ struct defer_lock_t{};
+ //!Type to indicate to a mutex lock constructor that must try to lock the mutex.
+ struct try_to_lock_t {};
+ //!Type to indicate to a mutex lock constructor that the mutex is already locked.
+ struct adopt_lock_t{};
+
+ //!An object indicating that the locking
+ //!must be deferred.
+ static const defer_lock_t defer_lock = {};
+
+ //!An object indicating that a try_lock()
+ //!operation must be executed.
+ static const try_to_lock_t try_to_lock = {};
+
+ //!An object indicating that the ownership of lockable
+ //!object must be accepted by the new owner.
+ static const adopt_lock_t adopt_lock = {};
+
+ } // namespace boost
+
+
+
+[endsect]
+
+[/===========================================]
+[section:lock_guard_hpp Header `<boost/sync/locks/lock_guard.hpp>`]
+[/===========================================]
+
+ namespace boost {
+
+ template<typename BasicLockable>
+ class lock_guard
+ {
+ public:
+ typedef BasicLockable lockable_type;
+ explicit lock_guard(lockable_type& m_);
+ lock_guard(lockable_type& m_,boost::adopt_lock_t);
+ ~lock_guard();
+
+ lock_guard(lock_guard const&) = delete;
+ lock_guard& operator=(lock_guard const&) = delete;
+ private:
+ lockable_type& pm; // exposition only
+ };
+
+ } // namespace boost
+
+An object of type __lock_guard__ controls the ownership of a lockable object within a scope. A __lock_guard__ object maintains ownership of a lockable object throughout the __lock_guard__ object's lifetime. The behavior of a program is undefined if the lockable object referenced by `pm` does not exist for the entire lifetime of the __lock_guard__ object. `BasicLockable` shall meet the __basic_lockable_req__ requirements.
+
+__lock_guard__ is very simple: on construction it acquires ownership of the implementation of the __basic_lockable_req__ concept supplied as the constructor parameter. On destruction, the ownership is released. This provides simple RAII-style locking of a __basic_lockable_req__ object, to facilitate exception-safe locking and unlocking. In addition, the [link boost_sync.reference.locks_hpp.lock_guard_hpp.constructor_adopt `lock_guard(Lockable & m,boost::adopt_lock_t)` constructor] allows the __lock_guard__ object to take ownership of a lock already held by the current concurrent agent.
+
+[section:constructor Constructor `lock_guard(Lockable & m)`]
+
+
+[*Effects:] Stores a reference to `m`. Invokes [lock_ref_link `m.lock()`].
+
+[*Throws:] Any exception thrown by the call to [lock_ref_link `m.lock()`].
+
+[endsect]
+
+[section:constructor_adopt Constructor `lock_guard(Lockable & m,boost::adopt_lock_t)`]
+
+
+[*Precondition:] The current thread owns a lock on `m` equivalent to one
+obtained by a call to [lock_ref_link `m.lock()`].
+
+[*Effects:] Stores a reference to `m`. Takes ownership of the lock state of
+`m`.
+
+[*Throws:] Nothing.
+
+
+[endsect]
+
+[section:destructor Destructor `~lock_guard()`]
+
+[*Effects:] Invokes [unlock_ref_link `m.unlock()`] on the __basic_lockable_req__
+object passed to the constructor.
+
+[*Throws:] Nothing.
+
+
+[endsect]
+[endsect]
+
+[endsect]
+
+[endsect]
+
+
+[/=================]
+[section Appendices]
+[/=================]
+[/==================================]
+[section:history Appendix A: History]
+[/==================================]
+
+[section [*Version 0.1.0, September 10, 2010] ]
+
+[*Features:]
+
+*
+
+[endsect]
+
+[endsect]
+
+[/======================================]
+[section:rationale Appendix B: Rationale]
+
+
+[endsect]
+
+[/======================================================]
+[section:implementation Appendix C: Implementation Notes]
+
+
+[endsect]
+
+[/======================================================]
+[section:faq Appendix D: FAQ]
+
+
+[endsect]
+
+[/====================================================]
+[section:acknowledgements Appendix E: Acknowledgements]
+
+
+[endsect]
+
+[/====================================================]
+[section:tests Appendix F: Tests]
+
+In order to test you need to do.
+
+ bjam libs/lockable_traits/test
+
+You can also run a specific suite of test by doing
+
+ cd libs/lockable_traits/test
+ bjam lockable_traits
+
+
+[section `lockable_traits`]
+[table
+ [[Name] [kind] [Description] [Result] [Ticket]]
+ [[ratio_fail_test1] [compile-fails] [...] [Pass] [#]]
+ [[ratio_test] [run] [...] [Pass] [#]]
+]
+[endsect]
+
+
+[endsect]
+[/=====================================]
+[section:tickets Appendix G: Tickets]
+
+[table
+ [[Ticket] [Description] [Resolution] [State]]
+ [/[#] [XXXX] [XXXX] [Closed]]
+]
+
+
+[endsect]
+
+[/
+[/=====================================]
+[section:todo Appendix H: Future plans]
+[/=====================================]
+
+[heading For later releases]
+
+
+[endsect]
+]
+[endsect]

Next message: vicente.botet_at_[hidden]: "[Boost-commit] svn:boost r65401 - in sandbox/sync/boost/sync: . locks"
Previous message: vicente.botet_at_[hidden]: "[Boost-commit] svn:boost r65399 - sandbox/sync/boost"

Date view	Thread view	Subject view	Author view

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