Menu
▾
▴
[Boost-sandbox-cvs] boost-sandbox/libs/signals/doc signals.xml, 1.1, 1.2 tutorial.xml, 1.1, 1.2
|
From: Frank M. H. <fm...@us...> - 2007-02-20 20:06:50
|
Update of /cvsroot/boost-sandbox/boost-sandbox/libs/signals/doc In directory sc8-pr-cvs3.sourceforge.net:/tmp/cvs-serv23831 Modified Files: signals.xml tutorial.xml Log Message: Updated tutorial to use new boost::track instead of old boost::trackable. Index: tutorial.xml =================================================================== RCS file: /cvsroot/boost-sandbox/boost-sandbox/libs/signals/doc/tutorial.xml,v retrieving revision 1.1 retrieving revision 1.2 diff -u -d -r1.1 -r1.2 --- tutorial.xml 7 Feb 2007 01:21:50 -0000 1.1 +++ tutorial.xml 20 Feb 2007 20:06:46 -0000 1.2 @@ -28,7 +28,7 @@ will not need to read the <emphasis>Advanced</emphasis> sections.</para> </section> -<section><title>Compatibility Note</title> +<section><title>Compatibility Note</title> <para>Boost.Signals has two syntactical forms: the preferred form and the compatibility form. The preferred form fits more closely with the @@ -101,12 +101,12 @@ <row> <entry> <programlisting> -struct HelloWorld +struct HelloWorld { - void operator()() const - { + void operator()() const + { std::cout << "Hello, World!" << std::endl; - } + } }; // ... @@ -124,12 +124,12 @@ </entry> <entry> <programlisting> -struct HelloWorld +struct HelloWorld { - void operator()() const - { + void operator()() const + { std::cout << "Hello, World!" << std::endl; - } + } }; // ... @@ -159,7 +159,7 @@ slots. The first slot will print "Hello" and may look like this:</para> <programlisting> -struct Hello +struct Hello { void operator()() const { @@ -482,7 +482,7 @@ max_value = *first; ++first; } - + return max_value; } }; @@ -512,13 +512,13 @@ <row> <entry> <programlisting> -<classname>boost::signal</classname><float (float x, float y), +<classname>boost::signal</classname><float (float x, float y), maximum<float> > sig; </programlisting> </entry> <entry> <programlisting> -<classname alt="boost::signalN">boost::signal2</classname><float, float, float, +<classname alt="boost::signalN">boost::signal2</classname><float, float, float, maximum<float> > sig; </programlisting> </entry> @@ -558,7 +558,7 @@ }; </programlisting> <para> -Again, we can create a signal with this new combiner: +Again, we can create a signal with this new combiner: </para> <informaltable> <tgroup cols="2" align="left"> @@ -572,7 +572,7 @@ <row> <entry> <programlisting> -<classname>boost::signal</classname><float (float, float), +<classname>boost::signal</classname><float (float, float), aggregate_values<std::vector<float> > > sig; sig.<methodname>connect</methodname>(&quotient); @@ -581,7 +581,7 @@ sig.<methodname>connect</methodname>(&difference); std::vector<float> results = sig(5, 3); -std::copy(results.begin(), results.end(), +std::copy(results.begin(), results.end(), std::ostream_iterator<float>(cout, " ")); </programlisting> </entry> @@ -596,7 +596,7 @@ sig.<methodname>connect</methodname>(&difference); std::vector<float> results = sig(5, 3); -std::copy(results.begin(), results.end(), +std::copy(results.begin(), results.end(), std::ostream_iterator<float>(cout, " ")); </programlisting> </entry> @@ -676,7 +676,7 @@ </programlisting> </section> -<section><title>Blocking Slots (Beginner)</title> +<section><title>Blocking Slots (Beginner)</title> <para>Slots can be temporarily "blocked", meaning that they will be ignored when the signal is invoked but have not been disconnected. The @@ -825,34 +825,45 @@ // ... NewsMessageArea newsMessageArea = new NewsMessageArea(/* ... */); // ... -deliverNews.<methodname>connect</methodname>(boost::bind(&NewsMessageArea::displayNews, +deliverNews.<methodname>connect</methodname>(boost::bind(&NewsMessageArea::displayNews, newsMessageArea, _1)); </programlisting> <para>However, what if the user closes the news message area, destroying the <code>newsMessageArea</code> object that <code>deliverNews</code> knows about? Most likely, a segmentation -fault will occur. However, with Boost.Signals one need only make -<code>NewsMessageArea</code> <emphasis>trackable</emphasis>, and the slot -involving <code>newsMessageArea</code> will be disconnected when -<code>newsMessageArea</code> is destroyed. The -<code>NewsMessageArea</code> class is made trackable by deriving -publicly from the <code>boost::signals::trackable</code> class, +fault will occur. However, with Boost.Signals one may track any object +which is managed by a shared_ptr, by using +<functionname>boost::track</functionname>. A slot will automatically +disconnect when any tracked objects bound to it are destroyed. In +addition, Boost.Signals will ensure that a tracked object is not +destroyed while the slot it is associated with is in mid-execution +(especially useful in multi-threaded code). +To track <code>NewsMessageArea</code>, we use a shared_ptr to manage +its lifetime, and wrap it in a call to <functionname>boost::track</functionname> +before passing it to <code>boost::bind</code>, e.g.:</para> <programlisting> -struct NewsMessageArea : public MessageArea, public boost::signals::trackable -{ - // ... -}; +// ... +boost::shared_ptr<NewsMessageArea> newsMessageArea(new NewsMessageArea(/* ... */)); +// ... +deliverNews.<methodname>connect</methodname>(boost::bind(&NewsMessageArea::displayNews, + boost::track(newsMessageArea), _1)); </programlisting> +<para> <functionname>boost::track</functionname> returns an object of type +<classname>boost::tracked<T></classname> when given a <code>shared_ptr<T></code> +as input. +<code>tracked<T></code> objects are implicitly convertible +to T&, T*, shared_ptr<T>, or weak_ptr<T>, and so can be bound to arguments +which require references or pointers.</para> <para>At this time there is a significant limitation to the use of -<code>trackable</code> objects in making slot connections: function -objects built using Boost.Bind are understood, such that pointers -or references to <code>trackable</code> objects passed to +tracked objects in making slot connections: only function +objects built using Boost.Bind are understood, such that <code>tracked</code> +objects passed to <code>boost::bind</code> will be found and tracked.</para> <para><emphasis role="bold">Warning</emphasis>: User-defined function objects and function objects from other libraries (e.g., Boost.Function or Boost.Lambda) -do not implement the required interfaces for <code>trackable</code> -object detection, and <emphasis>will silently ignore any bound trackable +do not implement the required interfaces for <code>tracked</code> +object detection, and <emphasis>will silently ignore any bound tracked objects</emphasis>. Future versions of the Boost libraries will address this limitation.</para> </section> @@ -865,7 +876,7 @@ <code>disconnect</code> method directly, or indirectly via the signal's <code>disconnect</code> method or <code>scoped_connection</code>'s destructor.</para></listitem> -<listitem><para>A <code>trackable</code> object bound to the slot is +<listitem><para>A <code>tracked</code> object bound to the slot is destroyed.</para></listitem> <listitem><para>The signal is destroyed.</para></listitem></itemizedlist> <para>These events can occur at any time without disrupting a signal's @@ -902,7 +913,7 @@ <row> <entry> <programlisting> -class Button +class Button { typedef boost::signal<void (int x, int y)> OnClick; @@ -933,7 +944,7 @@ </entry> <entry> <programlisting> -class Button +class Button { typedef <classname alt="boost::signalN">boost::signal2</classname><void,int,int> OnClick; @@ -976,7 +987,7 @@ <section> <title>Example: Document-View</title> - + <para>Signals can be used to implement flexible Document-View architectures. The document will contain a signal to which each of the views can connect. The following <code>Document</code> class Index: signals.xml =================================================================== RCS file: /cvsroot/boost-sandbox/boost-sandbox/libs/signals/doc/signals.xml,v retrieving revision 1.1 retrieving revision 1.2 diff -u -d -r1.1 -r1.2 --- signals.xml 7 Feb 2007 01:21:50 -0000 1.1 +++ signals.xml 20 Feb 2007 20:06:46 -0000 1.2 @@ -1,8 +1,8 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> -<library name="Signals" dirname="signals" - xmlns:xi="http://www.w3.org/2001/XInclude" id="signals" +<library name="Signals" dirname="signals" + xmlns:xi="http://www.w3.org/2001/XInclude" id="signals" last-revision="$Date$"> <libraryinfo> <author> @@ -10,6 +10,11 @@ <surname>Gregor</surname> <!-- <email>gr...@cs...</email> --> </author> + <author> + <firstname>Frank</firstname> + <surname>Hess</surname> + <!-- <email>fm...@us...</email> --> + </author> <copyright> <year>2001</year> @@ -18,6 +23,10 @@ <year>2004</year> <holder>Douglas Gregor</holder> </copyright> + <copyright> + <year>2007</year> + <holder>Frank Mori Hess</holder> + </copyright> <legalnotice> <para>Use, modification and distribution is subject to the Boost |
