| <html> | |
| <head> | |
| <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> | |
| <title>Thread-Safety</title> | |
| <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> | |
| <meta name="generator" content="DocBook XSL Stylesheets V1.75.2"> | |
| <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> | |
| <link rel="up" href="../signals2.html" title="Chapter 19. Boost.Signals2"> | |
| <link rel="prev" href="../boost/signals2/trackable.html" title="Class trackable"> | |
| <link rel="next" href="faq.html" title="Frequently Asked Questions"> | |
| </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"><a href="../../../index.html">Home</a></td> | |
| <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> | |
| <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> | |
| <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> | |
| <td align="center"><a href="../../../more/index.htm">More</a></td> | |
| </tr></table> | |
| <hr> | |
| <div class="spirit-nav"> | |
| <a accesskey="p" href="../boost/signals2/trackable.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../signals2.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="faq.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h2 class="title" style="clear: both"> | |
| <a name="signals2.thread-safety"></a>Thread-Safety</h2></div></div></div> | |
| <div class="toc"><dl> | |
| <dt><span class="section"><a href="thread-safety.html#id2564768">Introduction</a></span></dt> | |
| <dt><span class="section"><a href="thread-safety.html#id2564825">Signals and combiners</a></span></dt> | |
| <dt><span class="section"><a href="thread-safety.html#id2564989">Connections and other classes</a></span></dt> | |
| </dl></div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h3 class="title"> | |
| <a name="id2564768"></a>Introduction</h3></div></div></div> | |
| <p> | |
| The primary motivation for Boost.Signals2 is to provide a version of | |
| the original Boost.Signals library which can be used safely in a | |
| multi-threaded environment. | |
| This is achieved primarily through two changes from the original Boost.Signals | |
| API. One is the introduction of a new automatic connection management scheme | |
| relying on <code class="computeroutput">shared_ptr</code> and <code class="computeroutput">weak_ptr</code>, | |
| as described in the <a class="link" href="tutorial.html#signals2.tutorial.connection-management" title="Automatic Connection Management (Intermediate)">tutorial</a>. | |
| The second change was the introduction of a <code class="computeroutput">Mutex</code> template type | |
| parameter to the <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html" title="Class template signal">signal</a></code> class. This section details how | |
| the library employs these changes to provide thread-safety, and | |
| the limits of the provided thread-safety. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h3 class="title"> | |
| <a name="id2564825"></a>Signals and combiners</h3></div></div></div> | |
| <p> | |
| Each signal object default-constructs a <code class="computeroutput">Mutex</code> object to protect | |
| its internal state. Furthermore, a <code class="computeroutput">Mutex</code> is created | |
| each time a new slot is connected to the signal, to protect the | |
| associated signal-slot connection. | |
| </p> | |
| <p> | |
| A signal's mutex is automatically locked whenever any of the | |
| signal's methods are called. The mutex is usually held until the | |
| method completes, however there is one major exception to this rule. When | |
| a signal is invoked by calling | |
| <code class="computeroutput">signal::operator()</code>, | |
| the invocation first acquires a lock on the signal's mutex. Then | |
| it obtains a handle to the signal's slot list and combiner. Next | |
| it releases the signal's mutex, before invoking the combiner to | |
| iterate through the slot list. Thus no mutexes are held by the | |
| signal while a slot is executing. This design choice | |
| makes it impossible for user code running in a slot | |
| to deadlock against any of the | |
| mutexes used internally by the Boost.Signals2 library. | |
| It also prevents slots from accidentally causing | |
| recursive locking attempts on any of the library's internal mutexes. | |
| Therefore, if you invoke a signal concurrently from multiple threads, | |
| it is possible for the signal's combiner to be invoked concurrently | |
| and thus the slots to execute concurrently. | |
| </p> | |
| <p> | |
| During a combiner invocation, the following steps are performed in order to | |
| find the next callable slot while iterating through the signal's | |
| slot list. | |
| </p> | |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | |
| <li class="listitem"><p>The <code class="computeroutput">Mutex</code> associated with the connection to the | |
| slot is locked.</p></li> | |
| <li class="listitem"><p>All the tracked <code class="computeroutput">weak_ptr</code> associated with the | |
| slot are copied into temporary <code class="computeroutput">shared_ptr</code> which | |
| will be kept alive until the invocation is done with the slot. If this fails due | |
| to any of the | |
| <code class="computeroutput">weak_ptr</code> being expired, the connection is | |
| automatically disconnected. Therefore a slot will never be run | |
| if any of its tracked <code class="computeroutput">weak_ptr</code> have expired, | |
| and none of its tracked <code class="computeroutput">weak_ptr</code> will | |
| expire while the slot is running. | |
| </p></li> | |
| <li class="listitem"><p> | |
| The slot's connection is checked to see if it is blocked | |
| or disconnected, and then the connection's mutex is unlocked. If the connection | |
| was either blocked or disconnected, we | |
| start again from the beginning with the next slot in the slot list. | |
| Otherwise, we commit to executing the slot when the combiner next | |
| dereferences the slot call iterator (unless the combiner should increment | |
| the iterator without ever dereferencing it). | |
| </p></li> | |
| </ul></div> | |
| <p> | |
| Note that since we unlock the connection's mutex before executing | |
| its associated slot, it is possible a slot will still be executing | |
| after it has been disconnected by a | |
| <code class="computeroutput"><a class="link" href="../boost/signals2/connection.html#id1175348-bb">connection::disconnect</a>()</code>, if | |
| the disconnect was called concurrently with signal invocation. | |
| </p> | |
| <p> | |
| You may have noticed above that during signal invocation, the invocation only | |
| obtains handles to the signal's slot list and combiner while holding the | |
| signal's mutex. Thus concurrent signal invocations may still wind up | |
| accessing the | |
| same slot list and combiner concurrently. So what happens if the slot list is modified, | |
| for example by connecting a new slot, while a signal | |
| invocation is in progress concurrently? If the slot list is already in use, | |
| the signal performs a deep copy of the slot list before modifying it. | |
| Thus the a concurrent signal invocation will continue to use the old unmodified slot list, | |
| undisturbed by modifications made to the newly created deep copy of the slot list. | |
| Future signal invocations will receive a handle to the newly created deep | |
| copy of the slot list, and the old slot list will be destroyed once it | |
| is no longer in use. Similarly, if you change a signal's combiner with | |
| <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#id663325-bb">signal::set_combiner</a></code> | |
| while a signal invocation is running concurrently, the concurrent | |
| signal invocation will continue to use the old combiner undisturbed, | |
| while future signal invocations will receive a handle to the new combiner. | |
| </p> | |
| <p> | |
| The fact that concurrent signal invocations use the same combiner object | |
| means you need to insure any custom combiner you write is thread-safe. | |
| So if your combiner maintains state which is modified when the combiner | |
| is invoked, you | |
| may need to protect that state with a mutex. Be aware, if you hold | |
| a mutex in your combiner while dereferencing slot call iterators, | |
| you run the risk of deadlocks and recursive locking if any of | |
| the slots cause additional mutex locking to occur. One way to avoid | |
| these perils is for your combiner to release any locks before | |
| dereferencing a slot call iterator. The combiner classes provided by | |
| the Boost.Signals2 library are all thread-safe, since they do not maintain | |
| any state across invocations. | |
| </p> | |
| <p> | |
| Suppose a user writes a slot which connects another slot to the invoking signal. | |
| Will the newly connected slot be run during the same signal invocation in | |
| which the new connection was made? The answer is no. Connecting a new slot | |
| modifies the signal's slot list, and as explained above, a signal invocation | |
| already in progress will not see any modifications made to the slot list. | |
| </p> | |
| <p> | |
| Suppose a user writes a slot which disconnects another slot from the invoking signal. | |
| Will the disconnected slot be prevented from running during the same signal invocation, | |
| if it appears later in the slot list than the slot which disconnected it? | |
| This time the answer is yes. Even if the disconnected slot is still | |
| present in the signal's slot list, each slot is checked to see if it is | |
| disconnected or blocked immediately before it is executed (or not executed as | |
| the case may be), as was described in more detail above. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h3 class="title"> | |
| <a name="id2564989"></a>Connections and other classes</h3></div></div></div> | |
| <p> | |
| The methods of the <code class="computeroutput"><a class="link" href="../boost/signals2/connection.html" title="Class connection">signals2::connection</a></code> class are thread-safe, | |
| with the exception of assignment and swap. This is achived via locking the mutex | |
| associated with the object's underlying signal-slot connection. Assignment and | |
| swap are not thread-safe because the mutex protects the underlying connection | |
| which a <code class="computeroutput"><a class="link" href="../boost/signals2/connection.html" title="Class connection">signals2::connection</a></code> object references, not | |
| the <code class="computeroutput"><a class="link" href="../boost/signals2/connection.html" title="Class connection">signals2::connection</a></code> object itself. That is, | |
| there may be many copies of a <code class="computeroutput"><a class="link" href="../boost/signals2/connection.html" title="Class connection">signals2::connection</a></code> object, | |
| all of which reference the same underlying connection. There is not a mutex | |
| for each <code class="computeroutput"><a class="link" href="../boost/signals2/connection.html" title="Class connection">signals2::connection</a></code> object, there is only | |
| a single mutex protecting the underlying connection they reference. | |
| </p> | |
| <p>The <code class="computeroutput"><a class="link" href="../boost/signals2/shared_connection_block.html" title="Class shared_connection_block">shared_connection_block</a></code> class obtains some thread-safety | |
| from the <code class="computeroutput">Mutex</code> protecting the underlying connection which is blocked | |
| and unblocked. The internal reference counting which is used to keep track of | |
| how many <code class="computeroutput"><a class="link" href="../boost/signals2/shared_connection_block.html" title="Class shared_connection_block">shared_connection_block</a></code> objects are asserting | |
| blocks on their underlying connection is also thread-safe (the implementation | |
| relies on <code class="computeroutput">shared_ptr</code> for the reference counting). | |
| However, individual <code class="computeroutput"><a class="link" href="../boost/signals2/shared_connection_block.html" title="Class shared_connection_block">shared_connection_block</a></code> objects | |
| should not be accessed concurrently by multiple threads. As long as two | |
| threads each have their own <code class="computeroutput"><a class="link" href="../boost/signals2/shared_connection_block.html" title="Class shared_connection_block">shared_connection_block</a></code> object, | |
| then they may use them in safety, even if both <code class="computeroutput"><a class="link" href="../boost/signals2/shared_connection_block.html" title="Class shared_connection_block">shared_connection_block</a></code> | |
| objects are copies and refer to the same underlying connection. | |
| </p> | |
| <p> | |
| The <code class="computeroutput"><a class="link" href="../boost/signals2/slot.html" title="Class template slot">signals2::slot</a></code> class has no internal mutex locking | |
| built into it. It is expected that slot objects will be created then | |
| connected to a signal in a single thread. Once they have been copied into | |
| a signal's slot list, they are protected by the mutex associated with | |
| each signal-slot connection. | |
| </p> | |
| <p>The <code class="computeroutput"><a class="link" href="../boost/signals2/trackable.html" title="Class trackable">signals2::trackable</a></code> class does NOT provide | |
| thread-safe automatic connection management. In particular, it leaves open the | |
| possibility of a signal invocation calling into a partially destructed object | |
| if the trackable-derived object is destroyed in a different thread from the | |
| one invoking the signal. | |
| <code class="computeroutput"><a class="link" href="../boost/signals2/trackable.html" title="Class trackable">signals2::trackable</a></code> is only provided as a convenience | |
| for porting single-threaded code from Boost.Signals to Boost.Signals2. | |
| </p> | |
| </div> | |
| </div> | |
| <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> | |
| <td align="left"><p><small>Last revised: June 12, 2007 at 14:01:23 -0400</small></p></td> | |
| <td align="right"><div class="copyright-footer">Copyright © 2001-2004 Douglas Gregor<br>Copyright © 2007-2009 Frank Mori Hess<p>Distributed under the Boost | |
| Software License, Version 1.0. (See accompanying file | |
| <code class="filename">LICENSE_1_0.txt</code> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)</p> | |
| </div></td> | |
| </tr></table> | |
| <hr> | |
| <div class="spirit-nav"> | |
| <a accesskey="p" href="../boost/signals2/trackable.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../signals2.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="faq.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> | |
| </div> | |
| </body> | |
| </html> |