|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r49072 - sandbox/thread_safe_signals/trunk/libs/signals2/doc
From: fmhess_at_[hidden]
Date: 2008-09-30 15:10:45
Author: fmhess
Date: 2008-09-30 15:10:45 EDT (Tue, 30 Sep 2008)
New Revision: 49072
URL: http://svn.boost.org/trac/boost/changeset/49072
Log:
More updating of obsolete bits of docs.
Text files modified:
sandbox/thread_safe_signals/trunk/libs/signals2/doc/faq.xml | 67 ++++++++++-----------------------------
sandbox/thread_safe_signals/trunk/libs/signals2/doc/introduction.xml | 2
sandbox/thread_safe_signals/trunk/libs/signals2/doc/rationale.xml | 34 ++++++++++----------
3 files changed, 35 insertions(+), 68 deletions(-)
Modified: sandbox/thread_safe_signals/trunk/libs/signals2/doc/faq.xml
==============================================================================
--- sandbox/thread_safe_signals/trunk/libs/signals2/doc/faq.xml (original)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/faq.xml 2008-09-30 15:10:45 EDT (Tue, 30 Sep 2008)
@@ -5,7 +5,7 @@
<title>Frequently Asked Questions</title>
<using-namespace name="boost"/>
- <using-namespace name="boost::signalslib"/>
+ <using-namespace name="boost::signals2"/>
<qandaset>
<qandaentry>
@@ -23,54 +23,18 @@
</qandaentry>
<qandaentry>
<question>
- <para>Is Boost.Signals thread-safe?</para>
+ <para>Is Boost.Signals2 thread-safe?</para>
</question>
<answer>
- <para>Yes, if the ThreadingModel template parameter of the signal is set to
- <code>boost::signalslib::multi_threaded</code>, or if it is set to
- <code>boost::signalslib::auto_threaded</code> and boost has detected thread support
- in the compiler's current translation mode. If you use <code>boost::signalslib::multi_threaded</code>,
- you will also have to link to libboost_thread.</para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question>
- <para>How do I get Boost.Signals to work with Qt?</para>
- </question>
- <answer>
- <para>When building with Qt, the Moc keywords
- <code>signals</code> and <code>slots</code> are defined using
- preprocessor macros, causing a conflict with the <code>boost::signals</code>
- namespace. For thread_safe_signals, <code>boost::signals</code> is actually
- just a namespace alias to <code>boost::signalslib</code>. So by always using the
- namespace <code>boost::signalslib</code> instead of
- <code>boost::signals</code> in your
- code, you can avoid any conflict with the Qt <code>signals</code> macro.
+ <para>
+ Yes, as long as the Mutex template parameter is not set to
+ a fake mutex type like <classname>boost::signals2::dummy_mutex</classname>.
+ Also, if your slots depend on objects which may be destroyed concurrently
+ with signal invocation, you will need to use automatic connection management.
+ That is, the objects will need to be owned by
+ <classname>shared_ptr</classname> and passed to the slot's
+ <methodname alt="slotN::track">track</methodname>() method before the slot is connected.
</para>
-
- <para>Alternatively, for <emphasis>Qt 4.1 and later</emphasis>
- the <code>signals</code> and <code>slots</code> macros
- can be turned off in Qt on a per-project or per-file basis
- with the <code>no_keywords</code> option. This works with
- out-of-the-box builds of Boost and Qt. You do not need to
- re-configure, re-build, or duplicate existing libraries. For a
- project where you want to use both Boost.Signals and Qt
- Signals and Slots, the relevant part of your .pro file might
- look like this:</para>
-
- <programlisting>CONFIG += no_keywords # so Qt won't #define any non-all-caps `keywords'
-INCLUDEPATH += . /usr/local/include/thread_safe_signals /usr/local/include/boost-1_33_1/ # ...your exact paths may vary
-</programlisting>
-
- <para>Now you can mix Boost.Signals and Qt Signals and Slots
- in the same files, and even within the same class or function.
- You will have to use the upper-case versions of Qt macros in
- your own code. See the article <ulink
- url="http://scottcollins.net/articles/a-deeper-look-at-signals-and-slots.html">A
- Deeper Look at Signals and Slots</ulink> [off-site] for more
- complete examples and a survey of the strengths of the two
- systems.</para>
-
</answer>
</qandaentry>
<qandaentry>
@@ -102,7 +66,7 @@
<listitem>
<para>
The <classname>signal</classname> class has an additional template parameter for specifying
- the threading model.
+ the mutex type used internally by the signal.
</para>
<para>The <code>signal::combiner()</code> method, which formerly returned a reference to the
signal's combiner has been replaced by <methodname alt="signalN::combiner">signal::combiner</methodname>
@@ -129,9 +93,12 @@
</para>
</listitem>
<listitem>
- <para>The namespace <code>boost::signals</code> has been renamed <code>boost::signalslib</code>
- to avoid conflict with Qt's signal macro. For backward compatibility, a <code>boost::signals</code>
- namespace alias is provided.
+ <para>The namespace <code>boost::signals</code> has been replaced by <code>boost::signals2</code>
+ to avoid conflict with the original Signals implementation, and the Qt "signals" macro.
+ Also, some classes and headers
+ have been moved to comply with Boost's guidelines. For example, the signal class is now
+ in the boost::signals2 namespace instead of the boost namespace,
+ and it's header file is now at boost/signals2/signal.hpp instead of boost/signal.hpp.
</para>
</listitem>
</itemizedlist>
Modified: sandbox/thread_safe_signals/trunk/libs/signals2/doc/introduction.xml
==============================================================================
--- sandbox/thread_safe_signals/trunk/libs/signals2/doc/introduction.xml (original)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/introduction.xml 2008-09-30 15:10:45 EDT (Tue, 30 Sep 2008)
@@ -44,7 +44,7 @@
Boost vault</ulink>.
The development version of the code is available in the sandbox of the
<ulink url="http://svn.boost.org/trac/boost/wiki/BoostSubversion">Boost svn</ulink>.
- The files for thread_safe_signals are located in the <code>sandbox/thread_safe_signals</code>
+ The files for Signals2 are located in the <code>sandbox/thread_safe_signals</code>
subdirectory and may be <ulink url="http://svn.boost.org/trac/boost/browser/sandbox/thread_safe_signals">
browsed online</ulink> or the trunk checked out with the following command:
<programlisting>svn co http://svn.boost.org/svn/boost/sandbox/thread_safe_signals/trunk thread_safe_signals</programlisting>
Modified: sandbox/thread_safe_signals/trunk/libs/signals2/doc/rationale.xml
==============================================================================
--- sandbox/thread_safe_signals/trunk/libs/signals2/doc/rationale.xml (original)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/rationale.xml 2008-09-30 15:10:45 EDT (Tue, 30 Sep 2008)
@@ -5,7 +5,7 @@
<title>Design Rationale</title>
<using-namespace name="boost"/>
- <using-namespace name="boost::signalslib"/>
+ <using-namespace name="boost::signals2"/>
<using-class name="boost::signalN"/>
<section>
@@ -13,7 +13,7 @@
<para> Users need to have fine control over the connection of
signals to slots and their eventual disconnection. The approach
- taken by Boost.Signals is to return a
+ taken by Boost.Signals2 is to return a
<code><classname>connection</classname></code> object that enables
connected/disconnected query, manual disconnection, and an
automatic disconnection on destruction mode. Some other possible
@@ -45,7 +45,7 @@
disconnect</emphasis>: this approach identifies slots with a
token that is easily comparable (e.g., a string), enabling
slots to be arbitrary function objects. While this approach is
- essentially equivalent to the approach taken by Boost.Signals,
+ essentially equivalent to the approach taken by Boost.Signals2,
it is possibly more error-prone for several reasons:</para>
<itemizedlist>
@@ -77,7 +77,7 @@
</listitem>
</itemizedlist>
- <para> This type of interface is supported in Boost.Signals
+ <para> This type of interface is supported in Boost.Signals2
via the slot grouping mechanism. It augments the
<code><classname>connection</classname></code> object-based
connection management scheme.</para>
@@ -88,12 +88,12 @@
<section>
<title>Automatic Connection Management</title>
- <para>Automatic connection management in thread_safe_signals
+ <para>Automatic connection management in Signals2
depends on the use of <classname>boost::shared_ptr</classname> to
manage the lifetimes of tracked objects. This is differs from
- the original Boost.Signals library, which instead relied on derivation
+ the original Boost.Signals2 library, which instead relied on derivation
from the <code><classname>boost::trackable</classname></code> class.
- The Boost.Signals library would be
+ The Boost.Signals2 library would be
notified of an object's destruction by the
<code><classname>trackable</classname></code> destructor.
</para>
@@ -130,14 +130,14 @@
proficient C++ programmer. Competing interface design generally
required the combiners to be constructed to conform to an
interface that would be customized for (and limited to) the
- Signals library. While these interfaces are generally enable more
+ Signals2 library. While these interfaces are generally enable more
straighforward implementation of the signals & slots
libraries, the combiners are unfortunately not reusable (either in
other signals & slots libraries or within other generic
algorithms), and the learning curve is steepened slightly to learn
the specific combiner interface.</para>
- <para> The Signals formulation of combiners is based on the
+ <para> The Signals2 formulation of combiners is based on the
combiner using the "pull" mode of communication, instead of the
more complex "push" mechanism. With a "pull" mechanism, the
combiner's state can be kept on the stack and in the program
@@ -240,7 +240,7 @@
even outside the context of a signals & slots library.</para>
<para> The cost of the "pull" combiner interface is paid in the
- implementation of the Signals library itself. To correctly handle
+ implementation of the Signals2 library itself. To correctly handle
slot disconnections during calls (e.g., when the dereference
operator is invoked), one must construct the iterator to skip over
disconnected slots. Additionally, the iterator must carry with it
@@ -258,7 +258,7 @@
<section>
<title>Connection Interfaces: += operator</title>
- <para> Boost.Signals supports a connection syntax with the form
+ <para> Boost.Signals2 supports a connection syntax with the form
<code>sig.<methodname>connect</methodname>(slot)</code>, but a
more terse syntax <code>sig += slot</code> has been suggested (and
has been used by other signals & slots implementations). There
@@ -268,7 +268,7 @@
<itemizedlist>
<listitem>
<para><emphasis role="bold">It's unnecessary</emphasis>: the
- connection syntax supplied by Boost.Signals is no less
+ connection syntax supplied by Boost.Signals2 is no less
powerful that that supplied by the <code>+=</code>
operator. The savings in typing (<code>connect()</code>
vs. <code>+=</code>) is essentially negligible. Furthermore,
@@ -317,9 +317,9 @@
an initiative to wrap the C interfaces to <ulink
url="http://www.gtk.org">GTK</ulink> libraries in C++, and has
grown to be a separate library maintained by Karl Nelson. There
- are many similarities between libsigc++ and Boost.Signals, and
- indeed Boost.Signals was strongly influenced by Karl Nelson and
- libsigc++. A cursory inspection of each library will find a
+ are many similarities between libsigc++ and Boost.Signals2, and
+ indeed the original Boost.Signals was strongly influenced by
+ Karl Nelson and libsigc++. A cursory inspection of each library will find a
similar syntax for the construction of signals and in the use of
connections. There
are some major differences in design that separate these
@@ -333,12 +333,12 @@
objects (as part of the library), explicit adaptation from
the argument and return types of the signal to the argument
and return types of the slot (libsigc++ is, by default, more
- strict about types than Boost.Signals).</para>
+ strict about types than Boost.Signals2).</para>
</listitem>
<listitem>
<para><emphasis role="bold">Combiner/Marshaller
- interface</emphasis>: the equivalent to Boost.Signals
+ interface</emphasis>: the equivalent to Boost.Signals2
combiners in libsigc++ are the marshallers. Marshallers are
similar to the "push" interface described in Combiner
Interface, and a proper treatment of the topic is given
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