|
|
Boost-Commit : |
From: stipe_at_[hidden]
Date: 2008-09-03 15:00:31
Author: srajko
Date: 2008-09-03 15:00:30 EDT (Wed, 03 Sep 2008)
New Revision: 48567
URL: http://svn.boost.org/trac/boost/changeset/48567
Log:
updated generic support layer docs
Text files modified:
sandbox/SOC/2007/signals/boost/dataflow/vtk/support.hpp | 7 +---
sandbox/SOC/2007/signals/libs/dataflow/doc/dataflow.qbk | 6 +++-
sandbox/SOC/2007/signals/libs/dataflow/doc/support/concepts/binary_operable.qbk | 39 +++++++++++++++--------------
sandbox/SOC/2007/signals/libs/dataflow/doc/support/concepts/component.qbk | 53 +++++++++++++++++++++++++--------------
sandbox/SOC/2007/signals/libs/dataflow/doc/support/concepts/general.qbk | 41 ++++++++++++++++++++++++++++++
sandbox/SOC/2007/signals/libs/dataflow/doc/support/concepts/port.qbk | 29 ++++++++++++++++-----
sandbox/SOC/2007/signals/libs/dataflow/doc/support/concepts/unary_operable.qbk | 9 +++---
sandbox/SOC/2007/signals/libs/dataflow/doc/support/examples.qbk | 11 ++++++++
sandbox/SOC/2007/signals/libs/dataflow/doc/support/examples/vtk_example.qbk | 20 +++++++++++---
9 files changed, 154 insertions(+), 61 deletions(-)
Modified: sandbox/SOC/2007/signals/boost/dataflow/vtk/support.hpp
==============================================================================
--- sandbox/SOC/2007/signals/boost/dataflow/vtk/support.hpp (original)
+++ sandbox/SOC/2007/signals/boost/dataflow/vtk/support.hpp 2008-09-03 15:00:30 EDT (Wed, 03 Sep 2008)
@@ -39,14 +39,11 @@
//[ vtk_algorithm_output_producer
namespace boost { namespace dataflow { namespace vtk {
-struct vtk_algorithm_consumer;
-
// PortTraits for vtkAlgorithmOutput objects, which produce data.
// We specify the PortCategory (ports::producer) and Tag (vtk::tag).
struct vtk_algorithm_output_producer
- : public complemented_port_traits<ports::producer,
- port_adapter<vtkAlgorithm, vtk::vtk_algorithm_consumer, vtk::tag>, tag> {};
+ : public port_traits<ports::producer, vtk::tag> {};
} } } // namespace boost::dataflow::vtk
@@ -62,7 +59,7 @@
namespace boost { namespace dataflow { namespace vtk {
struct vtk_algorithm_consumer
- : public port_traits<ports::consumer, vtk::tag> {};
+ : public complemented_port_traits<ports::consumer, vtkAlgorithmOutput, vtk::tag> {};
typedef port_adapter<vtkAlgorithm, vtk::vtk_algorithm_consumer, vtk::tag>
vtk_algorithm_consumer_adapter;
Modified: sandbox/SOC/2007/signals/libs/dataflow/doc/dataflow.qbk
==============================================================================
--- sandbox/SOC/2007/signals/libs/dataflow/doc/dataflow.qbk (original)
+++ sandbox/SOC/2007/signals/libs/dataflow/doc/dataflow.qbk 2008-09-03 15:00:30 EDT (Wed, 03 Sep 2008)
@@ -15,6 +15,7 @@
[template concepts[] [link dataflow.support.concepts concepts]]
[template Tag[] [link dataflow.support.concepts.general.tag [^Tag]]]
[template Traits[] [link dataflow.support.concepts.general.entity [^Traits]]]
+[template Side[] [link dataflow.support.concepts.general.side [^Side]]]
[template Entity[] [link dataflow.support.concepts.general.entity [^Entity]]]
[template PortCategory[] [link dataflow.support.concepts.port_related.portcategory [^PortCategory]]]
[template Mechanism[] [link dataflow.support.concepts.port_related.mechanism [^Mechanism]]]
@@ -24,8 +25,8 @@
[template ConsumerPort[] [link dataflow.support.concepts.port_related.port [^ConsumerPort]]]
[template ComplementedPort[] [link dataflow.support.concepts.port_related.complementedport [^ComplementedPort]]]
[template ComplementedPortTraits[] [link dataflow.support.concepts.port_related.complementedport [^ComplementedPortTraits]]]
-[template PortVector[] [link dataflow.support.concepts.component.portvector [^PortVector]]]
-[template PortVectorTraits[] [link dataflow.support.concepts.component.portvector [^PortVectorTraits]]]
+[template PortVector[] [link dataflow.support.concepts.component_related.portvector [^PortVector]]]
+[template PortVectorTraits[] [link dataflow.support.concepts.component_related.portvector [^PortVectorTraits]]]
[template VectorPort[] [link dataflow.support.concepts.port_related.vectorport [^VectorPort]]]
[template VectorPortTraits[] [link dataflow.support.concepts.port_related.vectorport [^VectorPortTraits]]]
[template KeyedPort[] [link dataflow.support.concepts.port_related.keyedport [^KeyedPort]]]
@@ -194,6 +195,7 @@
[import ../example/blueprint/blueprint_example.cpp]
[import ../example/glv_gui/glvgui_example.cpp]
+[import ../example/glv_gui/glvgui_graph.cpp]
[include introduction/introduction.qbk]
Modified: sandbox/SOC/2007/signals/libs/dataflow/doc/support/concepts/binary_operable.qbk
==============================================================================
--- sandbox/SOC/2007/signals/libs/dataflow/doc/support/concepts/binary_operable.qbk (original)
+++ sandbox/SOC/2007/signals/libs/dataflow/doc/support/concepts/binary_operable.qbk 2008-09-03 15:00:30 EDT (Wed, 03 Sep 2008)
@@ -1,8 +1,8 @@
[section:binaryoperable BinaryOperable (Connectable, OnlyConnectable, Disconnectable, Extractable) ]
-A producer [Port] `P` and consumer [Port] `C` are /BinaryOperable/
-for a binary operation `O`, and mechanism `M`, if the implementation of
-the binary operation `O` has been specialized for `M`, `P`, and `C`.
+[Port]s `P` and `C` of [Tag] `T` are /BinaryOperable/
+for a binary operation `O` if the implementation of
+the binary operation `O` has been specialized for `P`, and `C`.
In this case,
@@ -15,11 +15,12 @@
The following expressions are used in this document:
[variablelist
- [[P] [A producer [Port] type.]]
- [[C_C] [A consumer [Port] [Connectable] with `P`]]
- [[C_O] [A consumer [Port] [OnlyConnectable] with `P`]]
- [[C_D] [A consumer [Port] [Disconnectable] with `P`]]
- [[C_E] [A consumer [Port] [Extractable] with `P`]]
+ [[`T`] [A [Tag] type. If omitted, `T` defaults to [default_tag].]]
+ [[P] [A [Port] type.]]
+ [[C_C] [A [Port] [Connectable] with `P`]]
+ [[C_O] [A [Port] [OnlyConnectable] with `P`]]
+ [[C_D] [A [Port] [Disconnectable] with `P`]]
+ [[C_E] [A [Port] [Extractable] with `P`]]
[[p] [An object of type P.]]
[[c_c] [An object of type C_C.]]
[[c_o] [An object of type C_O.]]
@@ -32,37 +33,37 @@
[[Name] [Expression] [Result Type] [Description]]
[
[Connect]
- [`binary_operation<operations::connect, M>(p,c_c)`]
+ [`binary_operation<operations::connect, T>(p,c_c)`]
[void]
[
- Creates a lasting connection between the `p` and `c`.
+ Creates a lasting connection between the `p` and `c_c`.
]
]
[
[OnlyConnect]
- [`binary_operation<operations::connect_only, M>(p,c_o)`]
+ [`binary_operation<operations::connect_only, T>(p,c_o)`]
[void]
[
- Discards any lasting connections stored by `p` or `c`,
- and creates a lasting connection between `p` and `c`.
- Note that `p` or `c` could still be connected to other ports,
- as long as these connections are not stored in `p` or `c`.
+ Discards any lasting connections stored by `p` or `c_o`,
+ and creates a lasting connection between `p` and `c_o`.
+ Note that `p` or `c_o` could still be connected to other ports,
+ as long as these connections are not stored in `p` or `c_o`.
]
]
[
[Disconnect]
- [`binary_operation<operations::disconnect, M>(p,c_d)`]
+ [`binary_operation<operations::disconnect, T>(p,c_d)`]
[void]
[
- Discards any existing connection between `p` and `c`.
+ Discards any existing connection between `p` and `c_d`.
]
]
[
[Extract]
- [`binary_operation<operations::extract, M>(p,c_e)`]
+ [`binary_operation<operations::extract, T>(p,c_e)`]
[void]
[
- Perfoms a one time transfer of data from `p` to `c`.
+ Perfoms a one time transfer of data from `p` to `c_e`.
]
]
]
Modified: sandbox/SOC/2007/signals/libs/dataflow/doc/support/concepts/component.qbk
==============================================================================
--- sandbox/SOC/2007/signals/libs/dataflow/doc/support/concepts/component.qbk (original)
+++ sandbox/SOC/2007/signals/libs/dataflow/doc/support/concepts/component.qbk 2008-09-03 15:00:30 EDT (Wed, 03 Sep 2008)
@@ -17,26 +17,26 @@
[[Name] [Expression] [Result Type] [Semantics]]
[
[PortVector Traits]
- [`traits_of<>::type`]
+ [`traits_of<PV>::type`]
[`PVT`]
[
- The [ComponentTraits] of the component.
+ The [PortVectorTraits] of the [PortVector].
]
]
[
[ GetPort ]
- [`get_port_c<M, I>(c)`]
+ [`get_port_c<I,T>(pv)`]
[]
[
- Returns the I'th [PortVectorTraits] exposed by `C`
+ Returns the I'th [Port] exposed by `pv`.
]
]
[
[ GetPort ]
- [`get_port<M, IC>(c)`]
+ [`get_port<IC,T>(pv)`]
[]
[
- Returns the IC'th [PortVectorTraits] exposed by `C`
+ Returns the IC'th [Port] exposed by `pv`
]
]
]
@@ -80,16 +80,21 @@
[variablelist
[[C] [A [Component] type.]]
[[CT] [The [ComponentTraits] type of `C`.]]
- [[I] [An MPL Integral Constant in the range \[0, number of ports exposed by C).]]
[[c] [An object of type C.]]
+ [[`S`] [A [Side] type.]]
+ [[`M`] [A [Mechanism] type.]]
]
+[heading Refines]
+
+* [PortVector]
+
[heading Component Requirements]
[table
[[Name] [Expression] [Result Type] [Semantics]]
[
[Component Traits]
- [`traits_of<M, C>::type`]
+ [`traits_of<C, T>::type`]
[`CT`]
[
The [ComponentTraits] of the component.
@@ -97,7 +102,7 @@
]
[
[IsComponent Trait]
- [`is_component<M, C>::type`]
+ [`is_component<C, T>::type`]
[Boolean metafunction that evaluates to true]
[
A trait encapsulating adherence to the Component
@@ -105,11 +110,21 @@
]
]
[
- [ GetComponentPort ]
- [`get_port<M, I>(c)`]
- []
+ [Has Default Port]
+ [`has_default_port<C,S,M,T>::type`]
+ [ Boolean MPL Metafunction ]
[
- Returns the I'th [Port] exposed by `C`
+ Specifies whether the component has a default port for the provided
+ [Side] and [Mechanism].
+ ]
+ ]
+ [
+ [Get Default Port]
+ [`get_default_port<S,M,T>(c)`]
+ [A [Port] type]
+ [
+ Returns the component's default port for the provided
+ [Side] and [Mechanism], if the component has one.
]
]
]
@@ -146,20 +161,20 @@
[section:componentoperable ComponentOperable (Invocable) ]
-A [Component] `P` is /ComponentOperable/
-for a component operation `O`, and mechanism `M`, if the implementation of
-the component operation `O` has been specialized for `M` and `P`
+A [Component] `C` of [Tag] `T` is /ComponentOperable/
+for a component operation `O`, if the implementation of
+the component operation `O` has been specialized for `C`
In this case,
-* If `O` is operations::invoke, `P` is [Invocable]
+* If `O` is operations::invoke, `C` is [Invocable]
[heading Notation]
The following expressions are used in this document:
[variablelist
[[C] [A [Component] type.]]
- [[c] [An object of type P.]]
+ [[c] [An object of type C.]]
]
[heading Requirements]
@@ -167,7 +182,7 @@
[[Name] [Expression] [Result Type] [Description]]
[
[Invoke]
- [`component_operation<operations::invoke, M>(p)`]
+ [`component_operation<operations::invoke, T>(c)`]
[Any type]
[
Invokes `c` - this typically causes a component to consume its
Modified: sandbox/SOC/2007/signals/libs/dataflow/doc/support/concepts/general.qbk
==============================================================================
--- sandbox/SOC/2007/signals/libs/dataflow/doc/support/concepts/general.qbk (original)
+++ sandbox/SOC/2007/signals/libs/dataflow/doc/support/concepts/general.qbk 2008-09-03 15:00:30 EDT (Wed, 03 Sep 2008)
@@ -188,4 +188,45 @@
[endsect][/entity]
+
+[section Side]
+
+A [Side] type is used to specify the side on which an object appears in a
+binary expression or in the parameter list of a binary function.
+It can be one of the following two types:
+
+* `boost::dataflow::args::left`, and
+* `boost::dataflow::args::right`.
+
+In the Dataflow library, it is used to access the default port of a [Port]
+or [Component]
+for the underlying operation (but note that the default port of a [Port] object
+is always the port itself). For example, in an expression such as
+[^connect(a,b)], the operation would connect the default port of `a` keyed
+by `boost::dataflow::args::left` and the default port of `b` keyed by
+`boost::dataflow::args::right`. See [Port] and [Component] documentation
+for more details.
+
+[heading Notation]
+
+[variablelist
+ [[S] [A [Side] type.]]
+]
+
+[heading Requirements]
+
+[table
+ [[Name] [Expression] [Result Type] [Semantics]]
+ [
+ [Type]
+ [`or<is_same<S, boost::dataflow::args::left>::type, is_same<S, boost::dataflow::args::right> >::type` ]
+ [ [true] ]
+ [
+ These are the only two types allowed for [Side].
+ ]
+ ]
+]
+
+[endsect]
+
[endsect]
Modified: sandbox/SOC/2007/signals/libs/dataflow/doc/support/concepts/port.qbk
==============================================================================
--- sandbox/SOC/2007/signals/libs/dataflow/doc/support/concepts/port.qbk (original)
+++ sandbox/SOC/2007/signals/libs/dataflow/doc/support/concepts/port.qbk 2008-09-03 15:00:30 EDT (Wed, 03 Sep 2008)
@@ -1,10 +1,11 @@
[section PortCategory]
A [PortCategory] designates a category of [Port] in the Dataflow library.
-The library currently defines two [PortCategory]s:
+The library currently defines three [PortCategory]s:
-* `boost::dataflow::ports::producer`, and
-* `boost::dataflow::ports::consumer`.
+* `boost::dataflow::ports::producer`,
+* `boost::dataflow::ports::consumer`, and
+* `boost::dataflow::ports::producer_consumer`, and
[heading Notation]
The following expressions are used in this document:
@@ -52,7 +53,11 @@
[section:mechanism Mechanism]
-A [Mechanism] type is used to select a default port.
+A [Mechanism] type is used together with a [Side] type to select a default port
+for an operation. Typically, each operation (e.g., connect or extract)
+will have a specific [Mechanism] associated with it. Multiple operations can
+share the same [Mechanism], which implies they will access the same default
+ports. See the [Port] and [Component] documentation for more information.
[heading Notation]
@@ -105,6 +110,7 @@
[variablelist
[[`T`] [A [Tag] type. If omitted, `T` defaults to [default_tag].]]
[[`PC`] [A [PortCategory] type.]]
+ [[`S`] [A [Side] type.]]
[[`M`] [A [Mechanism] type.]]
[[`P`] [A Port type, for [Tag] `T`.]]
[[`PT`] [[PortTraits] of `P` for `T`.]]
@@ -134,11 +140,21 @@
]
]
[
+ [Has Default Port]
+ [`has_default_port<P,S,M,T>::type`]
+ [ [true] ]
+ [
+ A [Port] has a default port for any [Side] and [Mechanism] (it is
+ the port object itself).
+ ]
+ ]
+ [
[Get Default Port]
- [`get_default_port<D,M,T>(p)`]
+ [`get_default_port<S,M,T>(p)`]
[p]
[
- Returns the port object.
+ Returns the port object (the default port of a [Port] object is
+ the object itself).
]
]
]
@@ -205,7 +221,6 @@
[variablelist
[[`T`] [A [Tag] type. If omitted, `T` defaults to [default_tag].]]
- [[`PC`] [A [PortCategory] type.]]
[[`P`] [A [ComplementedPort] type, for [Tag] `T`.]]
[[`PT`] [[ComplementedPortTraits] of `P` for `T`.]]
]
Modified: sandbox/SOC/2007/signals/libs/dataflow/doc/support/concepts/unary_operable.qbk
==============================================================================
--- sandbox/SOC/2007/signals/libs/dataflow/doc/support/concepts/unary_operable.qbk (original)
+++ sandbox/SOC/2007/signals/libs/dataflow/doc/support/concepts/unary_operable.qbk 2008-09-03 15:00:30 EDT (Wed, 03 Sep 2008)
@@ -1,9 +1,9 @@
[section:unaryoperable UnnaryOperable (AllDisconnectable) ]
-A [Port] `P` is /UnnaryOperable/
-for a unary operation `O`, and mechanism `M`, if the implementation of
-the unnary operation `O` has been specialized for `M` and `P`
+A [Port] `P` of [Tag] `T` is /UnaryOperable/
+for a unary operation `O`, if the implementation of
+the unnary operation `O` has been specialized for `P`
In this case,
@@ -13,6 +13,7 @@
The following expressions are used in this document:
[variablelist
+ [[`T`] [A [Tag] type. If omitted, `T` defaults to [default_tag].]]
[[P] [A [Port] type.]]
[[p] [An object of type P.]]
]
@@ -22,7 +23,7 @@
[[Name] [Expression] [Result Type] [Description]]
[
[Disconnect All]
- [`unnary_operation<operations::disconnect_all, M>(p)`]
+ [`unary_operation<operations::disconnect_all, T>(p)`]
[void]
[
Destroys any connections stored by `p`.
Modified: sandbox/SOC/2007/signals/libs/dataflow/doc/support/examples.qbk
==============================================================================
--- sandbox/SOC/2007/signals/libs/dataflow/doc/support/examples.qbk (original)
+++ sandbox/SOC/2007/signals/libs/dataflow/doc/support/examples.qbk 2008-09-03 15:00:30 EDT (Wed, 03 Sep 2008)
@@ -2,4 +2,15 @@
[include examples/vtk_example.qbk]
+[section:graph Implementing support for a new framework (BGL)]
+
+There is a support layer implemented for a simple framework based on a [BoostGraph]
+graph as a part of a GUI editor example.
+
+It is not documented, but you can see the source below:
+
+[glvgui_graph]
+
+[endsect]
+
[endsect][/examples]
Modified: sandbox/SOC/2007/signals/libs/dataflow/doc/support/examples/vtk_example.qbk
==============================================================================
--- sandbox/SOC/2007/signals/libs/dataflow/doc/support/examples/vtk_example.qbk (original)
+++ sandbox/SOC/2007/signals/libs/dataflow/doc/support/examples/vtk_example.qbk 2008-09-03 15:00:30 EDT (Wed, 03 Sep 2008)
@@ -43,7 +43,7 @@
Once we have the [VTK] support layer built, we can include it in any
[VTK] application and start using the Dataflow library with [VTK] objects.
In addition to
-the simpler syntax, this also allows us to use anything build on top of the
+the simpler syntax, this also allows us to use anything built on top of the
generic layer - like [DataflowBlueprint], or
the [gui_example GUI editor] currently under development.
@@ -68,7 +68,7 @@
[section:producerconsumer Setting up a producer Port and a consumer Port]
-Now that we have the mechanism, let's cover the basic data pipeline,
+Now that we have the tag, let's cover the basic data pipeline,
which is implemented using the
[vtkAlgorithm] class. This class provides input and output ports. Output ports
are accessible via `GetOuptutPort` member functions, which return a proxy
@@ -93,6 +93,15 @@
[vtk_algorithm_consumer]
+Note that for the consumer traits, we inherited `complemented_port_traits`
+rather than `port_traits`. In doing so, we made `vtk_algorithm_consumer`
+a [ComplementedPortTraits]. This basically states that any [Port] with
+`vtk_algorithm_consumer` traits is intended for connections with `vtkAlgorithmOutput`
+[Port]s. This piece of information can make things easier for the Dataflow
+library in certain cases (e.g., the prototype [DataflowBlueprint] layer currently
+only knows how to connect two blueprint ports if at least one of them is a
+[ComplementedPort]).
+
[heading Next]
[link dataflow.support.examples.new_layer.connectable
@@ -110,8 +119,9 @@
[vtk_connect_impl_algorithm]
Connections are done through the `boost::dataflow::binary_operation` function
-with either `operation::connect` or `operation::connect_only` operation tag,
-and the specified mechanism. In the next step, we'll set up forwarding functions
+with either `operation::connect` or `operation::connect_only` operation, and
+a specified framework tag.
+In the next step, we'll set up forwarding functions
and operators that will make connections easier.
[heading What we can do with what we have so far]
@@ -129,7 +139,7 @@
To make connecting
easier, we'll add forwarding connect and connect_only
functions in the global namespace (where vtk classes live) specific
-to the vtk mechanism. The Dataflow library provides inlcude file templates
+to the vtk framework. The Dataflow library provides include file templates
for this purpose.
Including `<boost/dataflow/templates/binary_operation.hpp>` with `#define`d
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