From 71d216b90256936a9638f325af9bc69d720e75de Mon Sep 17 00:00:00 2001 From: DongHun Kwak Date: Thu, 6 Oct 2016 10:30:07 +0900 Subject: Imported Upstream version 1.59.0 Change-Id: I2dde00f4eca71df3eea9d251dcaecde18a6c90a5 Signed-off-by: DongHun Kwak --- doc/html/signals2/api_changes.html | 21 ++++---- doc/html/signals2/examples.html | 1 + doc/html/signals2/faq.html | 13 ++--- doc/html/signals2/rationale.html | 47 ++++++++-------- doc/html/signals2/reference.html | 11 ++-- doc/html/signals2/tests.html | 7 +-- doc/html/signals2/thread-safety.html | 19 +++---- doc/html/signals2/tutorial.html | 101 ++++++++++++++++++----------------- 8 files changed, 114 insertions(+), 106 deletions(-) (limited to 'doc/html/signals2') diff --git a/doc/html/signals2/api_changes.html b/doc/html/signals2/api_changes.html index 1045508841..b165f640e9 100644 --- a/doc/html/signals2/api_changes.html +++ b/doc/html/signals2/api_changes.html @@ -1,3 +1,4 @@ + @@ -72,7 +73,7 @@

Automatic connection management is now achieved through the use of shared_ptr/weak_ptr - and signals2::slot::track(), as described in the + and signals2::slot::track(), as described in the tutorial. However, the old (thread-unsafe) Boost.Signals scheme of automatic connection management is still supported via the boost::signals2::trackable class. @@ -106,7 +107,7 @@ move the connection creation from the constructor to to the an adl_postconstruct function, where a reference to the owning shared_ptr is available for - passing to signals2::slot::track. + passing to signals2::slot::track. The deconstruct function would be used create objects of the class and run their associated adl_postconstruct function. You can enforce use of deconstruct by @@ -160,7 +161,7 @@

The signals2::signal class has an additional typedef signals2::signal::extended_slot_type - and new signals2::signal::connect_extended() + and new signals2::signal::connect_extended() methods. These allow connection of slots which take an additional signals2::connection argument, giving them thread-safe access to their signal/slot connection when they are invoked. There is also a @@ -173,7 +174,7 @@ if you have slots which need access to their signals2::connection to the signal invoking them (for example to block or disconnect their connection) you may wish to connect the slots with - signals2::signal::connect_extended(). + signals2::signal::connect_extended(). This also requires adding an additional connection argument to the slot. More information on how and why to use extended slots is available in the tutorial. @@ -196,14 +197,14 @@

  • The signal::combiner() method, which formerly returned a reference to the - signal's combiner has been replaced by signals2::signal::combiner - (which now returns the combiner by value) and signals2::signal::set_combiner. + signal's combiner has been replaced by signals2::signal::combiner + (which now returns the combiner by value) and signals2::signal::set_combiner.

    During porting it should be straightforward to replace uses of the old reference-returning signal::combiner() - function with the new "by-value" signals2::signal::combiner - and signals2::signal::set_combiner functions. + function with the new "by-value" signals2::signal::combiner + and signals2::signal::set_combiner functions. However, you will need to inspect each call of the combiner method in your code to determine if your program logic has been broken by the changed return type. @@ -270,7 +271,7 @@

    Version 1.45

    - Version 1.45 added slot::track_foreign(). This method allows tracking + Version 1.45 added slot::track_foreign(). This method allows tracking of objects owned by shared_ptr classes other than boost::shared_ptr, for example std::shared_ptr.

    @@ -291,7 +292,7 @@ immediately blocking its connection.

  • - The shared_connection_block::connection() query has been + The shared_connection_block::connection() query has been added, to provide access to the shared_connection_blocks associated connection.

    • diff --git a/doc/html/signals2/examples.html b/doc/html/signals2/examples.html index 7c1785745b..3cad7b5107 100644 --- a/doc/html/signals2/examples.html +++ b/doc/html/signals2/examples.html @@ -1,3 +1,4 @@ + diff --git a/doc/html/signals2/faq.html b/doc/html/signals2/faq.html index 7a6feaa771..b7f7c8188b 100644 --- a/doc/html/signals2/faq.html +++ b/doc/html/signals2/faq.html @@ -1,3 +1,4 @@ + @@ -26,11 +27,11 @@

    Frequently Asked Questions

    -
    -
    1. Don't noncopyable signal semantics mean that a class +
    +
    1. Don't noncopyable signal semantics mean that a class with a signal member will be noncopyable as well?
    -
    2. Is Boost.Signals2 thread-safe? +
    2. Is Boost.Signals2 thread-safe?
    @@ -41,7 +42,7 @@ @@ -56,7 +57,7 @@ @@ -70,7 +71,7 @@ with signal invocation, you will need to use automatic connection management. That is, the objects will need to be owned by shared_ptr and passed to the slot's - track() method before the slot is connected. + track() method before the slot is connected. The signals2::trackable scheme of automatic connection management is NOT thread-safe, and is only provided to ease porting of single-threaded code from Boost.Signals to Boost.Signals2. diff --git a/doc/html/signals2/rationale.html b/doc/html/signals2/rationale.html index 285cb8af08..57cf2a2ddd 100644 --- a/doc/html/signals2/rationale.html +++ b/doc/html/signals2/rationale.html @@ -1,3 +1,4 @@ + @@ -26,17 +27,17 @@

    Design Rationale

    -
    User-level Connection Management
    -
    Automatic Connection Management
    -
    optional_last_value as the Default Combiner
    -
    Combiner Interface
    -
    Connection Interfaces: += operator
    -
    Signals2 Mutex Classes
    -
    Comparison with other Signal/Slot implementations
    +
    User-level Connection Management
    +
    Automatic Connection Management
    +
    optional_last_value as the Default Combiner
    +
    Combiner Interface
    +
    Connection Interfaces: += operator
    +
    Signals2 Mutex Classes
    +
    Comparison with other Signal/Slot implementations

    -User-level Connection Management

    +User-level Connection Management

    Users need to have fine control over the connection of signals to slots and their eventual disconnection. The primary approach taken by Boost.Signals2 is to return a @@ -44,14 +45,14 @@ connected/disconnected query, manual disconnection, and an automatic disconnection on destruction mode (signals2::scoped_connection). In addition, two other interfaces are supported by the - signal::disconnect overloaded method:

    + signal::disconnect overloaded method:

    • Pass slot to disconnect: in this interface model, the disconnection of a slot connected with - sig.connect(typeof(sig)::slot_type(slot_func)) is + sig.connect(typeof(sig)::slot_type(slot_func)) is performed via - sig.disconnect(slot_func). Internally, + sig.disconnect(slot_func). Internally, a linear search using slot comparison is performed and the slot, if found, is removed from the list. Unfortunately, querying connectedness ends up as a @@ -79,14 +80,14 @@

    This type of interface is supported in Boost.Signals2 via the slot grouping mechanism, and the overload of - signal::disconnect + signal::disconnect which takes an argument of the signal's Group type.

    -Automatic Connection Management

    +Automatic Connection Management

    Automatic connection management in Signals2 depends on the use of boost::shared_ptr to manage the lifetimes of tracked objects. This is differs from @@ -128,7 +129,7 @@

    -optional_last_value as the Default Combiner

    +optional_last_value as the Default Combiner

    The default combiner for Boost.Signals2 has changed from the last_value combiner used by default in the original Boost.Signals library. @@ -144,7 +145,7 @@

    -Combiner Interface

    +Combiner Interface

    The Combiner interface was chosen to mimic a call to an algorithm in the C++ standard library. It is felt that by viewing slot call results as merely a sequence of values accessed by input @@ -272,9 +273,9 @@ private:

    -Connection Interfaces: += operator

    +Connection Interfaces: += operator

    Boost.Signals2 supports a connection syntax with the form - sig.connect(slot), but a + sig.connect(slot), but a more terse syntax sig += slot has been suggested (and has been used by other signals & slots implementations). There are several reasons as to why this syntax has been @@ -312,7 +313,7 @@ private:

    -Signals2 Mutex Classes

    +Signals2 Mutex Classes

    The Boost.Signals2 library provides 2 mutex classes: boost::signals2::mutex, and boost::signals2::dummy_mutex. The motivation for providing @@ -330,14 +331,14 @@ private:

    -Comparison with other Signal/Slot implementations

    +Comparison with other Signal/Slot implementations
    -
    libsigc++
    -
    .NET delegates
    +
    libsigc++
    +
    .NET delegates

    -libsigc++

    +libsigc++

    libsigc++ is a C++ signals & slots library that originally started as part of an initiative to wrap the C interfaces to GTK libraries in C++, and has @@ -367,7 +368,7 @@ private:

    -.NET delegates

    +.NET delegates

    Microsoft has introduced the .NET Framework and an associated set of languages and language extensions, one of which is the diff --git a/doc/html/signals2/reference.html b/doc/html/signals2/reference.html index ce8eb05cf9..dc7259fbe1 100644 --- a/doc/html/signals2/reference.html +++ b/doc/html/signals2/reference.html @@ -1,3 +1,4 @@ + @@ -55,7 +56,7 @@ 

    namespace boost {
   namespace signals2 {
     class connection;
-    void swap(connection&, connection&);
+    void swap(connection&, connection&);
     class scoped_connection;
   }
 }
    @@ -94,7 +95,7 @@ namespacesignals2{template<typename T>classlast_value; - template<>classlast_value<void>; + template<>classlast_value<void>;classno_slots_error;} @@ -116,7 +117,7 @@ namespacesignals2{template<typename T>classoptional_last_value; - template<>classoptional_last_value<void>; + template<>classoptional_last_value<void>;}} @@ -147,7 +148,7 @@ template<typename Signature,typename Combiner,typename Group,typename GroupCompare,typename SlotFunction,typename ExtendedSlotFunction,typename Mutex> - voidswap(signal<Signature,Combiner,Group,GroupCompare,SlotFunction,ExtendedSlotFunction,Mutex>&, + voidswap(signal<Signature,Combiner,Group,GroupCompare,SlotFunction,ExtendedSlotFunction,Mutex>&,signal<Signature,Combiner,Group,GroupCompare,SlotFunction,ExtendedSlotFunction,Mutex>&);}} @@ -179,7 +180,7 @@ template<typename Group>classgroup_type;template<typename GroupCompare>classgroup_compare_type;template<typename SlotFunction>classslot_function_type; - template<typename ExtendedSlotFunction>classextended_slot_function_type; + template<typename ExtendedSlotFunction>classextended_slot_function_type;template<typename Mutex>classmutex_type;}} diff --git a/doc/html/signals2/tests.html b/doc/html/signals2/tests.html index 4545b62e20..72fbb07ac9 100644 --- a/doc/html/signals2/tests.html +++ b/doc/html/signals2/tests.html @@ -1,3 +1,4 @@ + @@ -25,10 +26,10 @@

    Testsuite

    -
    Acceptance tests
    +
    Acceptance tests

    -Acceptance tests

    +Acceptance tests
    -

    1.

    +

    1.

    Don't noncopyable signal semantics mean that a class with a signal member will be noncopyable as well?

    -

    2.

    +

    2.

    Is Boost.Signals2 thread-safe?
    @@ -53,7 +54,7 @@ - diff --git a/doc/html/signals2/thread-safety.html b/doc/html/signals2/thread-safety.html index cf10d5b354..88a72f17c3 100644 --- a/doc/html/signals2/thread-safety.html +++ b/doc/html/signals2/thread-safety.html @@ -1,3 +1,4 @@ + @@ -26,13 +27,13 @@

    Thread-Safety

    -
    Introduction
    -
    Signals and combiners
    -
    Connections and other classes
    +
    Introduction
    +
    Signals and combiners
    +
    Connections and other classes

    -Introduction

    +Introduction

    The primary motivation for Boost.Signals2 is to provide a version of the original Boost.Signals library which can be used safely in a @@ -49,7 +50,7 @@

    -Signals and combiners

    +Signals and combiners

    Each signal object default-constructs a Mutex object to protect its internal state. Furthermore, a Mutex is created @@ -61,7 +62,7 @@ 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 - signal::operator(), + signal::operator(), 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 @@ -108,7 +109,7 @@ 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 - connection::disconnect(), if + connection::disconnect(), if the disconnect was called concurrently with signal invocation.

    @@ -125,7 +126,7 @@ 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 - signal::set_combiner + signal::set_combiner 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. @@ -163,7 +164,7 @@

    -Connections and other classes

    +Connections and other classes

    The methods of the signals2::connection class are thread-safe, with the exception of assignment and swap. This is achived via locking the mutex diff --git a/doc/html/signals2/tutorial.html b/doc/html/signals2/tutorial.html index 6824d15897..e3dfe8f4a8 100644 --- a/doc/html/signals2/tutorial.html +++ b/doc/html/signals2/tutorial.html @@ -1,3 +1,4 @@ + @@ -26,19 +27,19 @@

    Tutorial

    -
    How to Read this Tutorial
    -
    Hello, World! (Beginner)
    -
    Calling Multiple Slots
    -
    Passing Values to and from Slots
    -
    Connection Management
    +
    How to Read this Tutorial
    +
    Hello, World! (Beginner)
    +
    Calling Multiple Slots
    +
    Passing Values to and from Slots
    +
    Connection Management
    Example: Document-View
    Giving a Slot Access to its Connection (Advanced)
    Changing the Mutex Type of a Signal (Advanced).
    -
    Linking against the Signals2 library
    +
    Linking against the Signals2 library

    -How to Read this Tutorial

    +How to Read this Tutorial

    This tutorial is not meant to be read linearly. Its top-level structure roughly separates different concepts in the library (e.g., handling calling multiple slots, passing values to and from @@ -58,7 +59,7 @@ will not need to read the Advanced sectio

    -Hello, World! (Beginner)

    +Hello, World! (Beginner)

    The following example writes "Hello, World!" using signals and slots. First, we create a signal sig, a signal that takes no arguments and has a void return value. Next, we connect @@ -88,14 +89,14 @@ World!".

    -Calling Multiple Slots

    +Calling Multiple Slots
    -
    Connecting Multiple Slots (Beginner)
    -
    Ordering Slot Call Groups (Intermediate)
    +
    Connecting Multiple Slots (Beginner)
    +
    Ordering Slot Call Groups (Intermediate)

    -Connecting Multiple Slots (Beginner)

    +Connecting Multiple Slots (Beginner)

    Calling a single slot from a signal isn't very interesting, so we can make the Hello, World program more interesting by splitting the work of printing "Hello, World!" into two completely separate @@ -139,7 +140,7 @@ Hello, World!

    -Ordering Slot Call Groups (Intermediate)

    +Ordering Slot Call Groups (Intermediate)

    Slots are free to have side effects, and that can mean that some slots will have to be called before others even if they are not connected in that order. The Boost.Signals2 library allows slots to be placed into groups that are ordered in @@ -165,7 +166,7 @@ group parameter and those that don't? The "unnamed" slots (i.e., those that have been connected without specifying a group name) can be placed at the front or back of the slot list (by passing boost::signals2::at_front or boost::signals2::at_back -as the last parameter to connect, respectively), +as the last parameter to connect, respectively), and default to the end of the list. When a group is specified, the final at_front or at_back parameter describes where the slot @@ -203,14 +204,14 @@ Hello, World!

    -Passing Values to and from Slots

    +Passing Values to and from Slots
    -
    Slot Arguments (Beginner)
    -
    Signal Return Values (Advanced)
    +
    Slot Arguments (Beginner)
    +
    Signal Return Values (Advanced)

    -Slot Arguments (Beginner)

    +Slot Arguments (Beginner)

    Signals can propagate arguments to each of the slots they call. For instance, a signal that propagates mouse motion events might want to pass along the new mouse coordinates and whether the mouse @@ -271,7 +272,7 @@ connected to sig must therefore be able to t

    -Signal Return Values (Advanced)

    +Signal Return Values (Advanced)

    Just as slots can receive arguments, they can also return values. These values can then be returned back to the caller of the signal through a combiner. The combiner is a mechanism @@ -450,20 +451,20 @@ struct DistributeRequest {

    -Connection Management

    +Connection Management
    -
    Disconnecting Slots (Beginner)
    -
    Blocking Slots (Beginner)
    -
    Scoped Connections (Intermediate)
    -
    Disconnecting Equivalent Slots (Intermediate)
    +
    Disconnecting Slots (Beginner)
    +
    Blocking Slots (Beginner)
    +
    Scoped Connections (Intermediate)
    +
    Disconnecting Equivalent Slots (Intermediate)
    Automatic Connection Management (Intermediate)
    Postconstructors and Predestructors (Advanced)
    -
    When Can Disconnections Occur? (Intermediate)
    -
    Passing Slots (Intermediate)
    +
    When Can Disconnections Occur? (Intermediate)
    +
    Passing Slots (Intermediate)

    -Disconnecting Slots (Beginner)

    +Disconnecting Slots (Beginner)

    Slots aren't expected to exist indefinitely after they are connected. Often slots are only used to receive a few events and are then disconnected, and the programmer needs control to decide @@ -472,8 +473,8 @@ when a slot should no longer be connected.

    boost::signals2::connection class. The connection class uniquely represents the connection between a particular signal and a particular slot. The -connected() method checks if the signal and slot are -still connected, and the disconnect() method +connected() method checks if the signal and slot are +still connected, and the disconnect() method disconnects the signal and slot if they are connected before it is called. Each call to the signal's connect() method returns a connection object, which can be used to determine if the @@ -489,7 +490,7 @@ connection still exists or to disconnect the signal and slot.

    -Blocking Slots (Beginner)

    +Blocking Slots (Beginner)

    Slots can be temporarily "blocked", meaning that they will be ignored when the signal is invoked but have not been permanently disconnected. This is typically used to prevent infinite recursion in cases where @@ -498,7 +499,7 @@ invoked again. A boost::signals2::shared_connection_block object will temporarily block a slot. The connection is unblocked by either destroying or calling -unblock +unblock on all the shared_connection_block objects that reference the connection. Here is an example of @@ -518,7 +519,7 @@ blocking/unblocking slots:

    -Scoped Connections (Intermediate)

    +Scoped Connections (Intermediate)

    The boost::signals2::scoped_connection class references a signal/slot connection that will be disconnected when the scoped_connection class goes out of scope. This @@ -539,22 +540,22 @@ e.g.,

     // doesn't compile due to compiler attempting to copy a temporary scoped_connection object
-// boost::signals2::scoped_connection c0 = sig.connect(ShortLived());
+// boost::signals2::scoped_connection c0 = sig.connect(ShortLived());
 
 // okay
-boost::signals2::scoped_connection c1(sig.connect(ShortLived()));
+boost::signals2::scoped_connection c1(sig.connect(ShortLived()));
 
 // also okay
 boost::signals2::scoped_connection c2;
-c2 = sig.connect(ShortLived());
+c2 = sig.connect(ShortLived());

    -Disconnecting Equivalent Slots (Intermediate)

    +Disconnecting Equivalent Slots (Intermediate)

    One can disconnect slots that are equivalent to a given function object using a form of the -signal::disconnect method, so long as +signal::disconnect method, so long as the type of the function object has an accessible == operator. For instance: @@ -609,7 +610,7 @@ public: // ... NewsMessageArea *newsMessageArea = new NewsMessageArea(/* ... */); // ... -deliverNews.connect(boost::bind(&NewsMessageArea::displayNews, +deliverNews.connect(boost::bind(&NewsMessageArea::displayNews, newsMessageArea, _1));

    However, what if the user closes the news message area, @@ -617,21 +618,21 @@ destroying the newsMessageArea object that deliverNews knows about? Most likely, a segmentation fault will occur. However, with Boost.Signals2 one may track any object which is managed by a shared_ptr, by using -slot::track. A slot will automatically +slot::track. A slot will automatically disconnect when any of its tracked objects expire. In addition, Boost.Signals2 will ensure that no tracked object expires while the slot it is associated with is in mid-execution. It does so by creating temporary shared_ptr copies of the slot's tracked objects before executing it. To track NewsMessageArea, we use a shared_ptr to manage its lifetime, and pass the shared_ptr to the slot via its -slot::track +slot::track method before connecting it, e.g.:

     // ...
 boost::shared_ptr<NewsMessageArea> newsMessageArea(new NewsMessageArea(/* ... */));
 // ...
-deliverNews.connect(signal_type::slot_type(&NewsMessageArea::displayNews,
+deliverNews.connect(signal_type::slot_type(&NewsMessageArea::displayNews,
   newsMessageArea.get(), _1).track(newsMessageArea));

    @@ -646,14 +647,14 @@ deliverNews.newsMessageArea itself, a copy of the shared_ptr would have been bound into the slot function, preventing the shared_ptr from expiring. However, the use of - slot::track + slot::track implies we wish to allow the tracked object to expire, and automatically disconnect the connection when this occurs.

    shared_ptr classes other than boost::shared_ptr (such as std::shared_ptr) may also be tracked for connection management - purposes. They are supported by the slot::track_foreign method. + purposes. They are supported by the slot::track_foreign method.

    @@ -695,7 +696,7 @@ deliverNews.

    -When Can Disconnections Occur? (Intermediate)

    +When Can Disconnections Occur? (Intermediate)

    Signal/slot disconnections occur when any of these conditions occur:

      @@ -730,7 +731,7 @@ signal.

    -Passing Slots (Intermediate)

    +Passing Slots (Intermediate)

    Slots in the Boost.Signals2 library are created from arbitrary function objects, and therefore have no fixed type. However, it is commonplace to require that slots be passed through interfaces that @@ -919,7 +920,7 @@ private: access to a signals2::connection object which references the invoking signal-slot connection. The difficulty is, the connection object is returned by the - signal::connect + signal::connect method, and therefore is not available until after the slot is already connected to the signal. This can be particularly troublesome in a multi-threaded environment where the signal may be invoked @@ -927,11 +928,11 @@ private:

    Therefore, the signal classes provide - signal::connect_extended + signal::connect_extended methods, which allow slots which take an extra argument to be connected to a signal. The extra argument is a signals2::connection object which refers to the signal-slot connection currently invoking the slot. - signal::connect_extended + signal::connect_extended uses slots of the type given by the signal::extended_slot_type typedef. @@ -940,7 +941,7 @@ private: The examples section includes an extended_slot program which demonstrates the syntax for using - signal::connect_extended. + signal::connect_extended.

    @@ -979,7 +980,7 @@ bs2::signal_type<void (int), mutex_type<bs2::dummy_mutex> >::type si

    -Linking against the Signals2 library

    +Linking against the Signals2 library

    Unlike the original Boost.Signals library, Boost.Signals2 is currently header-only.

    -- cgit v1.2.3

    dead_slot_test.cpp

    run

    Ensure that calling connect with a slot +

    Ensure that calling connect with a slot that has already expired does not actually connect to the slot.