Menu
▾
▴
boost-sandbox-cvs
|
From: Frank M. H. <fm...@us...> - 2007-03-06 21:51:58
|
Update of /cvsroot/boost-sandbox/boost-sandbox/libs/thread_safe_signals/doc/reference In directory sc8-pr-cvs3.sourceforge.net:/tmp/cvs-serv2126/reference Modified Files: connection.xml last_value.xml reference.xml signal_header.xml slot.xml track.xml visit_each.xml Added Files: auto_threaded.xml deconstruct_ptr.xml multi_threaded.xml postconstructible.xml predestructible.xml shared_connection_block.xml single_threaded.xml Log Message: Updated documentation. Index: slot.xml =================================================================== RCS file: /cvsroot/boost-sandbox/boost-sandbox/libs/thread_safe_signals/doc/reference/slot.xml,v retrieving revision 1.1 retrieving revision 1.2 diff -u -d -r1.1 -r1.2 --- slot.xml 5 Mar 2007 19:54:28 -0000 1.1 +++ slot.xml 6 Mar 2007 21:51:55 -0000 1.2 @@ -6,8 +6,6 @@ <using-namespace name="boost::signals"/> <using-class name="boost::signalN"/> <namespace name="boost"> - <class name="expired_slot"> - </class> <class name="slotN"> <template> <template-type-parameter name="R"/> @@ -172,7 +170,7 @@ <returns><simpara>The result returned by the slot's <code>SlotFunction</code> object.</simpara></returns> <throws><simpara>Any exceptions thrown by the slot's <code>SlotFunction</code> object. - <class>boost::expired_slot</class> if any object in the tracked object list + <classname>boost::expired_slot</classname> if any object in the tracked object list has expired.</simpara></throws> <notes><simpara>If you have already used <methodname>lock</methodname> to insure the @@ -197,15 +195,9 @@ <paramtype>const signals::detail::slot_base &</paramtype> </parameter> </signature> - <signature> - <type>slotN &</type> - <parameter name="tracked_signal"> - <paramtype>const signals::detail::signal_base &</paramtype> - </parameter> - </signature> <effects><para>Adds object(s) to the slot's tracked object list. Should any of the tracked objects expire, then subsequent attempts to call the slot's <code>operator()</code> - or <code>lock()</code> methods will throw an <class>expired_slot</class> exception.</para> + or <code>lock()</code> methods will throw an <classname>expired_slot</classname> exception.</para> <para>In the case of passing another slot as the argument to <code>track()</code>, only the objects in the other slot's tracked object list are added to the tracked object list of <code>this</code>. The other slot object itself @@ -222,7 +214,7 @@ <type>locked_container_type</type> <returns>A container holding <code>shared_ptr</code>s to each of the slot's tracked objects. As long as the returned container is kept in scope, none of the slot's tracked objects can expire.</returns> - <throws><class>expired_slot</class> if any of the slot's tracked objects have expired.</throws> + <throws><classname>expired_slot</classname> if any of the slot's tracked objects have expired.</throws> </method> <method name = "tracked_objects" cv="const"> <type>const tracked_container_type &</type> @@ -272,5 +264,21 @@ <constructor> </constructor> </class> + + <class name="expired_slot"> + <inherit access="public"><classname>bad_weak_ptr</classname></inherit> + <purpose>Indicates at least one of a slot's tracked objects has expired.</purpose> + <description>The <code>expired_slot</code> exception is thrown to indicate at least one of + a slot's tracked objects has expired. A <classname alt="signalN">signal</classname> + will automatically disconnect any slot which throws this exception during + signal invocation. Combiners + that wish to support disconnection via expired_slot exceptions should be + prepared to handle <code>expired_slot</code> exceptions thrown + by the slot iterator dereference operation. + </description> + <method name="what" cv="const" specifiers="virtual"> + <type>const char * </type> + </method> + </class> </namespace> </header> \ No newline at end of file Index: connection.xml =================================================================== RCS file: /cvsroot/boost-sandbox/boost-sandbox/libs/thread_safe_signals/doc/reference/connection.xml,v retrieving revision 1.1 retrieving revision 1.2 diff -u -d -r1.1 -r1.2 --- connection.xml 5 Mar 2007 19:54:28 -0000 1.1 +++ connection.xml 6 Mar 2007 21:51:55 -0000 1.2 @@ -25,7 +25,7 @@ </constructor> <constructor> - <parameter name="other"> + <parameter name="other"> <paramtype>const <classname>connection</classname>&</paramtype> </parameter> @@ -37,7 +37,7 @@ </constructor> <copy-assignment> - <parameter name="other"> + <parameter name="other"> <paramtype>const <classname>connection</classname>&</paramtype> </parameter> @@ -70,22 +70,6 @@ </method-group> <method-group name="blocking"> - <method name="block"> - <type>void</type> - <parameter name="should_block"> - <paramtype>bool</paramtype> - <default>true</default> - </parameter> - <requires><simpara><code>connected()</code></simpara></requires> - <postconditions><simpara><code>blocked() == should_block</code></simpara></postconditions> - <throws><simpara>Will not throw.</simpara></throws> - </method> - <method name="unblock"> - <type>void</type> - <requires><simpara><code>connected()</code></simpara></requires> - <postconditions><simpara><code>!blocked()</code></simpara></postconditions> - <throws><simpara>Will not throw.</simpara></throws> - </method> <method name="blocked" cv="const"> <type>bool</type> <returns><simpara><code>true</code> if the associated slot is either disconnected or blocked, <code>false</code> otherwise.</simpara></returns> @@ -102,9 +86,9 @@ <effects><para>Swaps the connections referenced in <computeroutput>this</computeroutput> and <computeroutput>other</computeroutput>.</para></effects> - + <throws><para>Will not throw.</para></throws> - </method> + </method> </method-group> <method-group name="comparisons"> @@ -160,6 +144,9 @@ </class> <class name="scoped_connection"> + <inherit access="public"> + <type><classname>connection</classname></type> + </inherit> <inherit access="private"> <type><classname>noncopyable</classname></type> <purpose>Exposition only</purpose> @@ -167,7 +154,7 @@ <purpose>Limits a signal-slot connection lifetime to a particular scope.</purpose> <constructor> - <parameter name="other"> + <parameter name="other"> <paramtype>const <classname>connection</classname>&</paramtype> </parameter> @@ -184,26 +171,7 @@ disconnects the signal-slot connection.</para></effects> </destructor> - <method-group name="connection management"> - <method name="disconnect" cv="const"> - <type>void</type> - <effects><para>If - <computeroutput>this-><methodname>connected</methodname>()</computeroutput>, - disconnects the signal and slot referenced by this; - otherwise, this operation is a no-op.</para></effects> - - <postconditions><para><computeroutput>!this-><methodname>connected</methodname>()</computeroutput>.</para></postconditions> - </method> - - <method name="connected" cv="const"> - <type>bool</type> - <returns><para><computeroutput>true</computeroutput> if this - references a non-NULL connection that is still active - (connected), and <computeroutput>false</computeroutput> - otherwise.</para></returns> - <throws><para>Will not throw.</para></throws> - </method> - </method-group> + <description><para>A connection which automatically disconnects on destruction.</para></description> </class> </namespace> </namespace> --- NEW FILE: multi_threaded.xml --- <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE header PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> <header name="boost/signals/multi_threaded.hpp" last-revision="$Date: 2007/03/06 21:51:55 $"> <using-namespace name="boost"/> <using-namespace name="boost::signals"/> <namespace name="boost"> <namespace name="signals"> <class name="multi_threaded"> <purpose>Thread-safety for a signal, using Boost.Threads.</purpose> <description> <para>The <code>multi_threaded</code> class will produce a thread-safe signal class when used as the signal's <code>ThreadingModel</code> template parameter. The <code>multi_threaded</code> class depends on the boost.threads library. If you include the boost/signals/multi_threaded.hpp header file, you will be required to link your code to the boost.threads binary library. Thus boost/signals/multi_threaded.hpp is not automatically included when you include boost/signal.hpp, and must be included separately if you wish to use <code>multi_threaded</code>. </para> </description> </class> </namespace> </namespace> </header> --- NEW FILE: deconstruct_ptr.xml --- <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE header PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> <header name="boost/deconstruct_ptr.hpp" last-revision="$Date: 2007/03/06 21:51:55 $"> <using-namespace name="boost"/> <namespace name="boost"> <overloaded-function name="deconstruct_ptr"> <signature> <template> <template-type-parameter name="T"/> </template> <type>shared_ptr<T></type> <parameter name="pointer"><paramtype>T*</paramtype></parameter> </signature> <signature> <template> <template-type-parameter name="T"/> <template-type-parameter name="D"/> </template> <type>shared_ptr<T></type> <parameter name="pointer"><paramtype>T*</paramtype></parameter> <parameter name="deleter"><paramtype>D</paramtype></parameter> </signature> <purpose>Create a <code>shared_ptr</code> which supports post-constructors and pre-destructors.</purpose> <effects><para>Creates a <code>shared_ptr<T></code> by passing the <code>pointer</code> and <code>deleter</code> parameters to the <code>shared_ptr</code> constructor. If no <code>deleter</code> is specified, then <classname>predestructing_deleter</classname> is used as the default. If <code>T</code> is derived from <classname>postconstructible</classname> (and <code>pointer</code> is not a null pointer), then <code>pointer->postconstruct()</code> will be called after the <code>shared_ptr</code> is constructed.</para> </effects> <returns><para>A <code>shared_ptr<T></code> owning <code>pointer</code>.</para></returns> </overloaded-function> <class name="predestructing_deleter"> <template> <template-type-parameter name="T"/> </template> <method name="operator()" cv="const"> <type>void</type> <parameter name="pointer"><paramtype>const T *</paramtype> </parameter> <effects><para>Calls <code>pointer-><methodname>predestruct</methodname>()</code> if <code>T</code> is derived from <classname>predestructible</classname>. Then <code>pointer</code> is deleted using <functionname>checked_delete</functionname>.</para></effects> </method> <purpose>Predestruct object if it is predestructible, then delete. </purpose> </class> </namespace> </header> --- NEW FILE: shared_connection_block.xml --- <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE header PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> <header name="boost/signals/shared_connection_block.hpp" last-revision="$Date: 2007/03/06 21:51:55 $"> <using-namespace name="boost"/> <using-namespace name="boost::signals"/> <using-class name="boost::signals::connection"/> <namespace name="boost"> <namespace name="signals"> <class name="shared_connection_block"> <purpose>Blocks a connection between a signal and a slot.</purpose> <description> <para>A <code>shared_connection_block</code> object blocks a connection, preventing the associated slot from executing when the associated signal is invoked. The connection will remain blocked until every <code>shared_connection_block</code> that references the connection releases its block. A <code>shared_connection_block</code> releases its block when it is destroyed or its <methodname>unblock</methodname> method is called.</para> <para>A <code>shared_connection_block</code> is safe to use even after the <classname>connection</classname> object it was constructed from has been destroyed, or the connection it references has been disconnected.</para> </description> <constructor> <parameter name="conn"> <paramtype>boost::signals::connection &</paramtype> </parameter> <effects> <para>Creates a <code>shared_connection_block</code> which references the connection referenced by <code>conn</code>. The connection will initially be blocked, and remain so until <methodname>unblock</methodname> is called, or the <code>shared_connection_block</code> is destroyed.</para> </effects> <postconditions><para><code>this->blocking() == true</code></para></postconditions> </constructor> <destructor> <effects><para>If <methodname>blocking</methodname>() is true, releases the connection block.</para></effects> </destructor> <method-group name="connection blocking"> <method name="unblock"> <type>void</type> <effects><para>If <methodname>blocking</methodname>() is true, releases the connection block. Note, the connection may remain blocked due to other <code>shared_connection_block</code> objects.</para></effects> <postconditions><para><code>this->blocking() == false</code>.</para></postconditions> </method> <method name="block"> <type>void</type> <effects><para>If <methodname>blocking</methodname>() is false, reasserts a block on the connection.</para></effects> <postconditions><para><code>this->blocking() == true</code>.</para></postconditions> </method> <method name="blocking" cv="const"> <type>bool</type> <returns><para><code>true</code> if <code>this</code> is asserting a block on the connection.</para></returns> <notes><para><code>this->blocking() == true</code> implies <code><methodname>connection::blocked</methodname>() == true</code> for the connection. However, <code>this->blocking() == false</code> does not necessarily imply <code>connection::blocked() == false</code>, since the connection may be blocked by another <code>shared_connection_block</code> objects.</para></notes> </method> </method-group> </class> </namespace> </namespace> </header> --- NEW FILE: single_threaded.xml --- <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE header PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> <header name="boost/signals/single_threaded.hpp" last-revision="$Date: 2007/03/06 21:51:55 $"> <using-namespace name="boost"/> <using-namespace name="boost::signals"/> <namespace name="boost"> <namespace name="signals"> <class name="single_threaded"> <purpose>Single-threaded choice for the ThreadingModel template parameter of a signal.</purpose> <description> <para>The <code>single_threaded</code> class will produce a multi-thread-unsafe signal class when used as the signal's <code>ThreadingModel</code> template parameter. The signal might still be used in a multi-threaded program, as long as the signal is only used by a single thread. The signal may have slightly better performance that a thread-safe signal, since it performs no locking. </para> </description> </class> </namespace> </namespace> </header> --- NEW FILE: predestructible.xml --- <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE header PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> <header name="boost/predestructible.hpp" last-revision="$Date: 2007/03/06 21:51:55 $"> <using-namespace name="boost"/> <namespace name="boost"> <class name="predestructible"> <destructor specifiers="[protected] virtual"/> <method name="predestruct" specifiers="virtual"> <type>void</type> <notes><para>Override <code>predestruct()</code> with your class' pre-destructor. It will be called automatically if you manage your objects with <code>shared_ptr</code>s that use <classname>predestructing_deleter</classname> as their deleter, such as those created with <functionname>deconstruct_ptr()</functionname></para> </notes> </method> <purpose>A base class for classes with predestructors, used in conjunction with <functionname>deconstruct_ptr</functionname>(). </purpose> </class> </namespace> </header> --- NEW FILE: postconstructible.xml --- <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE header PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> <header name="boost/postconstructible.hpp" last-revision="$Date: 2007/03/06 21:51:55 $"> <using-namespace name="boost"/> <namespace name="boost"> <class name="postconstructible"> <destructor specifiers="[protected] virtual"/> <method name="postconstruct" specifiers="[protected] virtual"> <type>void</type> <notes><para>Override <code>postconstruct()</code> with your class's post-constructor. It will be called automatically if you manage your objects with <code>shared_ptr</code>s created with <functionname>deconstruct_ptr()</functionname>. </para></notes> </method> <purpose>A base class for classes with postconstructors, used in conjunction with <functionname>deconstruct_ptr</functionname>(). </purpose> </class> </namespace> </header> Index: last_value.xml =================================================================== RCS file: /cvsroot/boost-sandbox/boost-sandbox/libs/thread_safe_signals/doc/reference/last_value.xml,v retrieving revision 1.1 retrieving revision 1.2 diff -u -d -r1.1 -r1.2 --- last_value.xml 5 Mar 2007 19:54:28 -0000 1.1 +++ last_value.xml 6 Mar 2007 21:51:55 -0000 1.2 @@ -27,9 +27,9 @@ </parameter> <effects><para>Attempts to dereference every iterator in the sequence <computeroutput>[first, last)</computeroutput>. - Swallows <class>boost::expired_slot</class> exceptions thrown by failed dereference attempts.</para></effects> + Swallows <classname>boost::expired_slot</classname> exceptions thrown by failed dereference attempts.</para></effects> <returns><para>The result of the last successful iterator dereference.</para></returns> - <throws><para><class>boost::no_slots_error</class> if no iterators were successfully dereferenced, + <throws><para><classname>boost::no_slots_error</classname> if no iterators were successfully dereferenced, unless the template type of <code>last_value</code> is <code>void</code> or <code>optional<T></code>.</para></throws> </method> </method-group> @@ -61,7 +61,7 @@ </parameter> <effects><para>Attempts to dereference every iterator in the sequence <computeroutput>[first, last)</computeroutput>. - Swallows <class>boost::expired_slot</class> exceptions thrown by failed dereference attempts.</para></effects> + Swallows <classname>boost::expired_slot</classname> exceptions thrown by failed dereference attempts.</para></effects> </method> </method-group> </class-specialization> @@ -94,11 +94,22 @@ </parameter> <effects><para>Attempts to dereference every iterator in the sequence <computeroutput>[first, last)</computeroutput>. - Swallows <class>boost::expired_slot</class> exceptions thrown by failed dereference attempts.</para></effects> - <returns><para>An <code>optional<T> containing the result of the last successful iterator dereference, - or an uninitalized optional<T> if no iterators were successfully dereferenced.</para></returns> + Swallows <classname>boost::expired_slot</classname> exceptions thrown by failed dereference attempts.</para></effects> + <returns><para>An <code>optional<T></code> containing the result of the last successful iterator dereference, + or an uninitalized <code>optional<T></code> if no iterators were successfully dereferenced.</para></returns> </method> </method-group> </class-specialization> + + <class name="no_slots_error"> + <inherit access="public"><classname>std::exception</classname></inherit> + <purpose>Indicates a combiner was unable to synthesize a return value.</purpose> + <description>The <code>no_slots_error</code> exception may be thrown by <classname>last_value</classname> + when it is run but unable to obtain any results from its input iterators. + </description> + <method name="what" cv="const" specifiers="virtual"> + <type>const char * </type> + </method> + </class> </namespace> </header> Index: visit_each.xml =================================================================== RCS file: /cvsroot/boost-sandbox/boost-sandbox/libs/thread_safe_signals/doc/reference/visit_each.xml,v retrieving revision 1.1 retrieving revision 1.2 diff -u -d -r1.1 -r1.2 --- visit_each.xml 5 Mar 2007 19:54:28 -0000 1.1 +++ visit_each.xml 6 Mar 2007 21:51:55 -0000 1.2 @@ -11,10 +11,10 @@ <type>void</type> <parameter name="visitor"> <paramtype>const Visitor&</paramtype> - </parameter> + </parameter> <parameter name="t"> <paramtype>const T&</paramtype> - </parameter> + </parameter> <parameter> <paramtype>int</paramtype> </parameter> @@ -24,7 +24,7 @@ <description> <para>The <functionname>visit_each</functionname> mechanism allows a visitor to be applied to every subobject in a given - object. It is used by the Signals library to discover + object. It was used by the Signals library to discover (now deprecated) <classname>signals::trackable</classname> objects within a function object, but other uses may surface if used universally (e.g., conservative garbage collection). To fit @@ -35,7 +35,7 @@ <effects><para><code>visitor(t)</code>, and for every subobject <code>x</code> of - <code>t</code>: + <code>t</code>: <itemizedlist> <listitem><para>If <code>x</code> is a reference, <code>visit_each(visitor, <functionname>ref</functionname>(x), 0)</code></para></listitem> <listitem><para>Otherwise, <code>visit_each(visitor, x, 0)</code></para></listitem> @@ -55,6 +55,6 @@ <para>Calls to visit_each are required to be unqualified, to enable argument-dependent lookup.</para></notes> - </function> + </function> </namespace> </header> Index: reference.xml =================================================================== RCS file: /cvsroot/boost-sandbox/boost-sandbox/libs/thread_safe_signals/doc/reference/reference.xml,v retrieving revision 1.1 retrieving revision 1.2 diff -u -d -r1.1 -r1.2 --- reference.xml 5 Mar 2007 19:54:28 -0000 1.1 +++ reference.xml 6 Mar 2007 21:51:55 -0000 1.2 @@ -6,6 +6,13 @@ <xi:include href="signal_header.xml"/> <xi:include href="slot.xml"/> <xi:include href="connection.xml"/> - <xi:include href="visit_each.xml"/> + <xi:include href="shared_connection_block.xml"/> <xi:include href="last_value.xml"/> + <xi:include href="auto_threaded.xml"/> + <xi:include href="single_threaded.xml"/> + <xi:include href="multi_threaded.xml"/> + <xi:include href="deconstruct_ptr.xml"/> + <xi:include href="postconstructible.xml"/> + <xi:include href="predestructible.xml"/> + <xi:include href="visit_each.xml"/> </library-reference> \ No newline at end of file --- NEW FILE: auto_threaded.xml --- <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE header PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> <header name="boost/signals/auto_threaded.hpp" last-revision="$Date: 2007/03/06 21:51:55 $"> <using-namespace name="boost"/> <using-namespace name="boost::signals"/> <namespace name="boost"> <namespace name="signals"> <class name="auto_threaded"> <purpose>Automatically enabled/disabled thread-safety for a signal.</purpose> <description> <para>The <code>auto_threaded</code> class will produce a thread-safe signal class when used as a signal's <code>ThreadingModel</code> template parameter if and only if boost has detected thread support in the compiler's current translation mode. The header file <code>boost/config.hpp</code> defines the macro BOOST_HAS_THREADS when boost detects threading support. The user may globally disable thread support in boost by defining BOOST_DISABLE_THREADS before any boost header files are included. </para> <para>When in thread-safe mode, the <code>auto_threaded</code> class uses a header-only mutex implementation. Thus, it has no dependence on the boost.threads library. If you are already using boost.threads, you may prefer to use the <classname>boost::signals::multi_threaded</classname> <code>ThreadingModel</code>, which uses a mutex class provided by boost.threads. </para> <para>You may wish to use a thread-unsafe signal in a multi-threaded program, if the signal is only used by a single thread. In that case, you may prefer to use the <classname>boost::signals::single_threaded</classname> class as your <code>ThreadingModel</code>. </para> </description> </class> </namespace> </namespace> </header> |
Thanks for helping keep SourceForge clean.
X