|
|
Boost-Commit : |
From: stipe_at_[hidden]
Date: 2007-11-24 19:33:46
Author: srajko
Date: 2007-11-24 19:33:46 EST (Sat, 24 Nov 2007)
New Revision: 41347
URL: http://svn.boost.org/trac/boost/changeset/41347
Log:
move concepts docs into subdirectory
Added:
sandbox/SOC/2007/signals/libs/dataflow/doc/concepts/component.qbk
- copied, changed from r41344, /sandbox/SOC/2007/signals/libs/dataflow/doc/concepts.qbk
sandbox/SOC/2007/signals/libs/dataflow/doc/concepts/port.qbk
- copied, changed from r41344, /sandbox/SOC/2007/signals/libs/dataflow/doc/port_concepts.qbk
Text files modified:
sandbox/SOC/2007/signals/libs/dataflow/doc/concepts/component.qbk | 8
sandbox/SOC/2007/signals/libs/dataflow/doc/concepts/port.qbk | 185 +++++++++++++++++++++++++--------------
2 files changed, 120 insertions(+), 73 deletions(-)
Copied: sandbox/SOC/2007/signals/libs/dataflow/doc/concepts/component.qbk (from r41344, /sandbox/SOC/2007/signals/libs/dataflow/doc/concepts.qbk)
==============================================================================
--- /sandbox/SOC/2007/signals/libs/dataflow/doc/concepts.qbk (original)
+++ sandbox/SOC/2007/signals/libs/dataflow/doc/concepts/component.qbk 2007-11-24 19:33:46 EST (Sat, 24 Nov 2007)
@@ -84,7 +84,7 @@
which it collects data from.
Operations between two ports such as /connect/, /connect_only/, /disconnect/,
-and /extract/ are captured by the [BinaryOperable] concept. Operations
+and /extract/ are captured by the [BinaryOperableConcept] concept. Operations
on a single port such as /disconnect_all/ are covered by the [UnaryOperableConcept]
concept.
@@ -319,7 +319,7 @@
[heading Header]
```
- #include <boost/dataflow/support/reflective_component.hpp> // or
+ #include <boost/dataflow/support/component.hpp> // or
#include <boost/dataflow/support.hpp>
```
@@ -419,7 +419,7 @@
]
[
[IsReflectiveComponent Trait]
- [`is_reflective_component<M, C>::type`]
+ [`is_component<M, C>::type`]
[Boolean metafunction that evaluates to true]
[
A trait encapsulating adherence to the ReflectiveComponent
@@ -458,7 +458,7 @@
In this case,
-* If `O` is operations::invoke, `P` is [Invocable]
+* If `O` is operations::invoke, `P` is [InvocableConcept]
[heading Notation]
The following expressions are used in this document:
Copied: sandbox/SOC/2007/signals/libs/dataflow/doc/concepts/port.qbk (from r41344, /sandbox/SOC/2007/signals/libs/dataflow/doc/port_concepts.qbk)
==============================================================================
--- /sandbox/SOC/2007/signals/libs/dataflow/doc/port_concepts.qbk (original)
+++ sandbox/SOC/2007/signals/libs/dataflow/doc/concepts/port.qbk 2007-11-24 19:33:46 EST (Sat, 24 Nov 2007)
@@ -44,91 +44,46 @@
[endsect][/portcategory]
-[section PortTraits]
+[section:port Port, PortTraits]
-A ['[PortTraitsConcept]] specifies the traits of a [PortConcept].
-
-[heading Notation]
-[variablelist
- [[PT] [A PortTraits type.]]
- [[P] [A [PortConcept] type with port traits `PC`.]]
-]
-
-[heading Requirements]
-[table
- [[Name] [Expression] [Result Type] [Semantics]]
- [
- [Mechanism]
- [`PT::mechanism`]
- [any type]
- [[MechanismConcept] type tag.]
- ]
- [
- [Port Category]
- [`PT::port_category`]
- [[PortCategoryConcept] type]
- [The category of the port]
- ]
- [
- [Port Concept]
- [`PT::port_concept`]
- [`concepts::port`, `concepts::keyed_port`]
- [The most refined producer concept that `P` satisfies.]
- ]
-]
-
-[heading Header]
-The types, templates, and functions shown here are declared in the following
-files:
-
-```
- #include <boost/dataflow/support/port.hpp> // or
- #include <boost/dataflow/support.hpp>
-```
-
-[heading Notes]
-
-[heading Examples]
-
-The following code defines a port traits type for vtk_algorithm_output,
-and associates it with this type. It is a part of
-the [vtk_example example showing how to provide a VTK support layer].
-
-[vtk_algorithm_output_producer]
-
-[endsect][/porttraits]
-
-
-[section:port Port (ProducerPort, ConsumerPort)]
-
-A type `P` is a ['[PortConcept]] for a mechanism `M` and port category `PC`
-if it specifies a [PortTraitsConcept] for that mechanism and port category.
-
-In that case,
+A ['[PortConcept]] is the fundamental point of data production or consumption.
+In order for a type `P` to satisfy the [PortConcept] concept requirements,
+a [PortTraitsConcept] type (specifying the traits of the port)
+must be registered for the port. Registration can be
+performed in multiple ways (see the examples below).
+
+[PortConcept] concept
+requirements are always relative to a particular a [MechanismConcept] `M` and
+[PortCategoryConcept] `PC`.
* If `PC` is `ports::producer`, then `P` is a [ProducerPortConcept]
* If `PC` If `ports::consumer`, then `P` is a [ConsumerPortConcept]
-[heading Refinements]
+A type can be a [PortConcept] for multiple mechanisms and/or port categories.
+
+[heading Port Refinements]
+* [KeyedPortConcept]
+* [ComplementedPortConcept]
[heading Notation]
The following expressions are used in this document:
[variablelist
- [[`P`] [A Port type.]]
[[`M`] [A [MechanismConcept] type.]]
[[`PC`] [A [PortCategoryConcept] type.]]
+ [[`P`] [A Port type, for [MechanismConcept] `M` and [PortCategoryConcept] `PC`.]]
+ [[`PT`] [[PortTraitsConcept] of `P` for `M` and `PC`.]]
[[`p`] [An object of type `P`]]
]
-[heading Requirements]
+[heading Port Requirements]
[table
[[Name] [Expression] [Result Type] [Semantics]]
[
[Port Traits]
[`port_traits_of<M, PC, P>::type`]
- [Any [PortTraitsConcept] type]
+ [`PT`]
[
The [PortTraitsConcept] of the port.
]
@@ -144,7 +99,7 @@
]
[
[Get Port]
- [`get_port<M,PC>()`]
+ [`get_port<M,PC>(p)`]
[`get_port_result_type<M,PC,P>::type`]
[
Returns the underlying port object. With regular ports,
@@ -154,6 +109,30 @@
]
]
+[heading PortTraits Requirements]
+[table
+ [[Name] [Expression] [Result Type] [Semantics]]
+ [
+ [Mechanism]
+ [`PT::mechanism`]
+ [any type]
+ [[MechanismConcept] type tag.]
+ ]
+ [
+ [Port Category]
+ [`PT::port_category`]
+ [[PortCategoryConcept] type]
+ [The category of the port]
+ ]
+ [
+ [Port Concept]
+ [`PT::port_concept`]
+ [`concepts::port`, `concepts::keyed_port`]
+ [The most refined producer concept that `P` satisfies.]
+ ]
+
+]
+
[heading Header]
The types, templates, and functions shown here are declared in the following
files:
@@ -169,7 +148,7 @@
[PortTraitsConcept] of a type `P`, thereby making it a [PortConcept].
Non-intrusive registration is done by providing a specialization of
-the `port_traits_of` template (either directly, or through the provided
+the `register_port_traits` template (either directly, or through the provided
macros DATAFLOW_PORT_TRAITS and DATAFLOW_PORT_TRAITS_ENABLE_IF).
Intrusive registration can be done by providing
@@ -196,8 +175,8 @@
[heading Non-intrusive registration]
-Non-intrusive registration is done by specializing the `port_traits_of`
-template. Since the `port_traits_of` template is keyed by [MechanismConcept]
+Non-intrusive registration is done by specializing the `register_port_traits`
+template. Since the `register_port_traits` template is keyed by [MechanismConcept]
and [PortCategoryConcept], this is rather verbose:
[port_registration_example_non_intrusive]
@@ -210,7 +189,7 @@
[heading Non-intrusive mass registration]
-The `port_traits_of` template has an Enable template parameter for use with
+The `register_port_traits` template has an Enable template parameter for use with
`boost::enable_if`. Hence, we can register a number of types at the same time:
[port_registration_example_non_intrusive_enable_if]
@@ -227,6 +206,74 @@
[endsect][/port]
+
+[section ComplementedPort]
+
+A ComplementedPort `P` is a [PortConcept] s.t. whenever it is
+[BinaryOperableConcept] with another [PortConcept] `P2`, `P2` is
+a particular type - `P`'s complement type.
+
+[ComplementedPortConcept]s are useful in situations where [PortConcept] types
+are [BinaryOperableConcept] in a one-to-one fashion (a pair of [PortConcept] types
+are each other's port complements), or in a one-to-many fashion (a number
+of [PortConcept] types have the same complement port). An example of the
+latter is [DataflowSignals], where any `signal` of signature `T` has
+a complement port of type `function<T>`, and can therefore model
+[ComplementedPortConcept], but `function<T>` is cannot because there are many `signal`
+types to which it can be connected.
+
+The traits of a [ComplementedPortConcept] are captured by the
+[ComplementedPortTraitsConcept], which refines the [PortTraitsConcept] with
+an additional member type specifying the complement port type.
+
+[heading ComplementedPort Refines]
+* [PortConcept]
+
+[heading ComplementedPortTraits Refines]
+* [PortTraitsConcept]
+
+[heading Notation]
+The following expressions are used in this document:
+
+[variablelist
+ [[`M`] [A [MechanismConcept] type.]]
+ [[`PC`] [A [PortCategoryConcept] type.]]
+ [[`P`] [A [ComplementedPortConcept] type, for [MechanismConcept] `M` and [PortCategoryConcept] `PC`.]]
+ [[`PT`] [[ComplementedPortTraitsConcept] of `P` for `M` and `PC`.]]
+]
+
+[heading ComplementedPort Requirements]
+[table
+ [[Name] [Expression] [Result Type] [Semantics]]
+ [
+ [Port Traits]
+ [`port_traits_of<M, PC, P>::type`]
+ [`PT`]
+ [
+ The [ComplementedPortTraitsConcept] of the port.
+ ]
+ ]
+]
+
+[heading ComplementedPortTraits Requirements]
+[table
+ [[Name] [Expression] [Result Type] [Semantics]]
+ [
+ [Complement Port Type]
+ [`PT::complement_port_type`]
+ [Any [PortConcept] type]
+ [
+ The complement port type of the port type `P`. `P` can only be
+ [BinaryOperableConcept] with the complement port type.
+ ]
+ ]
+]
+
+
+
+[endsect]
+
+
[section ProxyPortTraits]
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