niklas/cyclonedds
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

consistently use Eclipse Cyclone DDS in documentation

Browse source 
Signed-off-by: Erik Boasson <eb@ilities.com>
This commit is contained in:
Erik Boasson 2019-02-14 13:03:42 +01:00
parent 753f910aad
commit c7906f296d
13 changed files with 151 additions and 322 deletions
Download patch file Download diff file Expand all files Collapse all files

4
src/docs/CMakeLists.txt
View file

@ -131,11 +131,9 @@ elseif(BUILD_DOCS)
endif()
# Process sphinx configuration file
set(sph_conf_author "ADLINK")
string(TIMESTAMP sph_conf_copyright "%Y, ADLINK")
set(sph_conf_author "Eclipse Cyclone DDS project")
set(sph_conf_version "${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}.${PROJECT_VERSION_PATCH}")
set(sph_conf_release "${PROJECT_VERSION}")
set(sph_logo "${PROJECT_SOURCE_DIR}/docs/_static/pictures/VORTEX_LOGO.png")
configure_file(conf.py.in conf.py @ONLY)
# Define a list of output formats (-b option for sphinx-build)

4
src/docs/Doxyfile.in
View file

@ -2037,7 +2037,7 @@ INCLUDE_FILE_PATTERNS =
# recursively expanded use the := operator instead of the = operator.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
PREDEFINED = __restrict= __attribute__(x)=
PREDEFINED = __restrict= __attribute__(x)= __declspec(x)=
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
# tag can be used to specify a list of macro names that should be expanded. The
@ -2046,7 +2046,7 @@ PREDEFINED = __restrict= __attribute__(x)=
# definition found in the source code.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
EXPAND_AS_DEFINED =
EXPAND_AS_DEFINED =
# If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will
# remove all references to function-like macros that are alone on a line, have

31
src/docs/GettingStartedGuide/helloworld.rst
View file

@ -15,9 +15,9 @@
\newpage
###############################
Building CycloneDDS applications
###############################
#########################################
Building Eclipse Cyclone DDS applications
#########################################
.. .. contents::
@ -36,15 +36,12 @@ to be done to code the *Hello World!* example.
The procedure used to build the *Hello World!* example can also be
used for building your own applications.
:Windows: It is advised to have the CycloneDDS examples component installed (see
:ref:`Windows installation <WindowsInstallMSI>`) when actively
building the CycloneDDS examples on Windows. This chapter refers to the
CycloneDDS examples installed in the User Profile directory on Windows.
:Windows: ...
:Linux: It is advised to have copied the CycloneDDS examples to a user-friendly
:Linux: It is advised to have copied the Eclipse Cyclone DDS examples to a user-friendly
location as described in :ref:`this <CopyLinuxExamplesToUserFriendlyLocation>`
paragraph when actively building the CycloneDDS examples on Linux.
This chapter refers to the CycloneDDS examples installed
paragraph when actively building the Eclipse Cyclone DDS examples on Linux.
This chapter refers to the Eclipse Cyclone DDS examples installed
in the user-defined location.
@ -116,8 +113,8 @@ Creating the *Hello World!* example executables is as simple as
selecting the required configuration and building the solution.
:code:`helloworld\vs\directories.props` contains the location of where
the CycloneDDS header files and libraries are be placed. These locations
are based on the default installation directory structure. When CycloneDDS
the Eclipse Cyclone DDS header files and libraries are be placed. These locations
are based on the default installation directory structure. When Eclipse Cyclone DDS
is installed in a different directory, the following paths in
:code:`helloworld\vs\directories.props` should be changed, like:
@ -191,7 +188,7 @@ scope of this document.
.. _`CycloneDdsPackage`:
Hello World! CMake (CycloneDDS Package)
======================================
=======================================
After the CMake digression, we're back with the *Hello World!*
example. Apart from the native build files, CMake build files
@ -304,13 +301,13 @@ using the binaries that were just build. Be sure to use the right directories.
Summary
*******
We've seen that a CycloneDDS application can be build by using a Makefile on Linux
or a Visual Studio Solutions on Windows. Also CMake can be used to build a CycloneDDS
We've seen that a Eclipse Cyclone DDS application can be build by using a Makefile on Linux
or a Visual Studio Solutions on Windows. Also CMake can be used to build a Eclipse Cyclone DDS
application. In fact, it is the preferred way of building.
In the end, a predefined way of generating and building the source code should
be followed when building CycloneDDS applications. The figure below shows how a
typical CycloneDDS application is build.
be followed when building Eclipse Cyclone DDS applications. The figure below shows how a
typical Eclipse Cyclone DDS application is build.
.. image:: ../_static/pictures/BuildSchema.png
:scale: 30 %

130
src/docs/GettingStartedGuide/installation.rst
View file

@ -15,9 +15,9 @@
\newpage
#################
Install CycloneDDS
#################
##############################
Installing Eclipse Cyclone DDS
##############################
.. .. contents::
@ -28,31 +28,12 @@ Install CycloneDDS
System requirements
*******************
Currently AdLink CycloneDDS is supported on the following platforms:
+-------------------+--------------+--------------------+
| Operating systems | Architecture | Compiler |
+===================+==============+====================+
| Ubuntu 16.04 LTS | 64-bit | gcc 5.4 or later |
+-------------------+--------------+--------------------+
| Windows 10 | 64 -bit | VS2015 |
+-------------------+--------------+--------------------+
At the time of writing, Eclipse Cyclone DDS is known to run on Linux, macOS and Windows. The build-process is not yet able to generate native packages.
*****
Linux
*****
Ubuntu
======
On Ubuntu and other debian-derived platforms, the product can be installed using a native package.
::
sudo dpkg -i cyclonedds_<version>_<architecture>.deb
sudo dpkg -i cyclonedds-dev_<version>_<architecture>.deb
***************
Linux and macOS
***************
.. _`CopyLinuxExamplesToUserFriendlyLocation`:
@ -60,11 +41,10 @@ On Ubuntu and other debian-derived platforms, the product can be installed using
Post install steps
~~~~~~~~~~~~~~~~~~
The installation package installs examples in system directories.
In order to have a better user experience when building the CycloneDDS
examples, it is advised to copy the examples to a user-defined location.
This is to be able to build the examples natively and experiment with
the example source code.
The installation package installs examples in system directories. In order to have a better user
experience when building the Eclipse Cyclone DDS examples, it is advised to copy the examples to a
user-defined location. This is to be able to build the examples natively and experiment with the
example source code.
For this, the installation package provides the vdds_install_examples
script, located in /usr/bin.
@ -76,42 +56,15 @@ and the examples will be installed in the current location.
Type :code:`vdds_install_examples -h` for more information.
Red Hat
=======
Not supported yet (CHAM-326).
Tarball
=======
For more generic Linux installations, different tar-balls (with the same
content) are provided.
+----------------------------------+---------------------------------------+
| Tarball | Description |
+==================================+=======================================+
| CycloneDDS-<version>-Linux.tar.Z | Tar Compress compression. |
+----------------------------------+---------------------------------------+
| CycloneDDS-<version>-Linux.tar.gz | Tar GZip compression. |
+----------------------------------+---------------------------------------+
| CycloneDDS-<version>-Linux.tar.sh | Self extracting Tar GZip compression. |
+----------------------------------+---------------------------------------+
By extracting one of them at any preferred location, CycloneDDS can be used.
.. _`LinuxSetLibPath`:
Paths
=====
To be able to run CycloneDDS executables, the required libraries (like
libddsc.so) need to be available to the executables.
Normally, these are installed in system default locations and it works
out-of-the-box. However, if they are not installed in those locations,
it is possible that the library search path has to be changed.
This can be achieved by executing the command:
::
To be able to run Eclipse Cyclone DDS executables, the required libraries (like libddsc.so) need to
be available to the executables. Normally, these are installed in system default locations and it
works out-of-the-box. However, if they are not installed in those locations, it is possible that the
library search path has to be changed. This can be achieved by executing the command: ::
export LD_LIBRARY_PATH=<install_dir>/lib:$LD_LIBRARY_PATH
@ -120,49 +73,19 @@ This can be achieved by executing the command:
Windows
*******
.. _`WindowsInstallMSI`:
MSI
===
The default deployment method on Windows is to install the product using the MSI installer.
The installation process is self-explanatory. Three components are available:
1. a runtime component, containing the runtime libraries
2. a development component, containing the header files, the IDL compiler,
a precompiled Hello Word! example and other examples.
3. an examples component, containing the source code of the CycloneDDS examples.
The runtime and development components are (by default) installed in "Program Files" while
the CycloneDDS example component will be installed in the User Profile directory.
The CycloneDDS example code in the User Profile directory can be changed by the user.
ZIP
===
The Windows installation is also provided as a ZIP file. By extracting it
at any preferred location, CycloneDDS can be used.
.. _`WindowsSetLibPath`:
Paths
~~~~~
To be able to run CycloneDDS executables, the required libraries (like
ddsc.dll) need to be available to the executables.
Normally, these are installed in system default locations and it works
out-of-the-box. However, if they are not installed on those locations,
it is possible that the library search path has to be changed.
This can be achieved by executing the command:
::
To be able to run Eclipse Cyclone DDS executables, the required libraries (like ddsc.dll) need to be
available to the executables. Normally, these are installed in system default locations and it
works out-of-the-box. However, if they are not installed on those locations, it is possible that the
library search path has to be changed. This can be achieved by executing the command: ::
set PATH=<install_dir>/bin;%PATH%
.. note::
The MSI installer will add this path to the PATH environment
variable automatically.
.. _`TestYourInstallation`:
@ -170,11 +93,9 @@ This can be achieved by executing the command:
Test your installation
**********************
The installation provides a simple prebuilt :ref:`Hello World! <HelloWorld>` application which
can be run in order to test your installation. The *Hello World!* application consists of two
executables: a so called HelloworldPublisher and a HelloworldSubscriber, typically located in
:code:`/usr/share/CycloneDDS/examples/helloworld/bin` on Linux and in
:code:`C:\Program Files\ADLINK\Cyclone DDS\share\CycloneDDS\examples\helloworld\bin` on Windows.
Eclipse Cyclone DDS includes a simple :ref:`Hello World! <HelloWorld>` application which can be run
in order to test your installation. The *Hello World!* application consists of two executables: a so
called HelloworldPublisher and a HelloworldSubscriber.
To run the example application, please open two console windows and navigate to the appropriate
directory in both console windows. Run the HelloworldSubscriber in one of the console windows by the
@ -199,10 +120,3 @@ while the HelloworldSubscriber will be looking like this
For more information on how to build this application your own and the code which has
been used, please have a look at the :ref:`Hello World! <HelloWorld>` chapter.
*******
License
*******
TODO: CHAM-325

71
src/docs/GettingStartedGuide/next_steps.rst
View file

@ -19,58 +19,25 @@
What's next?
############
Want to know more about CycloneDDS? Please consider following a tutorial or
visit some of the pages listed below.
Want to know more about DDS? The primary source of information is the
OMG website at http://www.omg.org and specifically the `DDS Getting
Started <http://www.omg.org/gettingstarted/omg_idl.htm>`_ page and the
`DDS specification <http://www.omg.org/spec/DDS/>`_ itself. The
specification is a bit wordy and of course deals with minute details,
but it is surprisingly easy to follow for a specification.
*************************
The OMG DDS Specification
*************************
There are also various resources on the web dealing with DDS in general,
as the various vendors have posted tutorials, presentations, general
information and documentation on their products. While the details
between the various implementations do differ, they have much more in
common than what separates them, and so this information is also
applicable to Eclipse Eclipse Cyclone DDS. The one thing in which
Eclipse Cyclone DDS really differs is in the details of API, but that's
just syntax.
PrismTech (aquired by AdLink) has been an active member of the Object Management
Group® (OMG®) for over several years and is heavily involved in the development of the
DDS specification. Please visit the OMG website at http://www.omg.org and
specifically the
`DDS Getting Started <http://www.omg.org/gettingstarted/omg_idl.htm>`_
page and the `DDS specification <http://www.omg.org/spec/DDS/>`_ itself.
Obviously there are also things specific to Eclipse Cyclone DDS. The
level of documentation of Eclipse is not nearly what it should be, but
that should improve over time.
*************************************
AdLink Documentation and Tutorials
*************************************
* `Documentation <http://www.prismtech.com/vortex/resources/documentation>`_
* `DDS Tutorial <http://download.prismtech.com/docs/Vortex/html/ospl/DDSTutorial/index.html>`_
********************************
AdLink on Youtube and Slideshare
********************************
AdLink is also active on Youtube and Slideshare. Please following
the links below to view some interesting videos and presentations.
* `Overview <http://www.prismtech.com/vortex/resources/presentations>`_
* `Vortex Youtube <https://www.youtube.com/channel/UCqADOYgcicDgASLjNxww-Ww>`_
* `Vortex Slideshare <https://www.slideshare.net/prismtech1/presentations>`_
* `Vortex Demo <http://www.prismtech.com/vortex/vortex-demo>`_
**********************
AdLink on Social Media
**********************
* `Twitter (@ADLINKTech_usa) <https://twitter.com/ADLINKTech_usa>`_
* `Facebook <https://www.facebook.com/ADLINKTECH/>`_
* `LinkedIn <https://www.linkedin.com/company/79111/>`_
*****************
The DDS community
*****************
* `The AdLink DDS-community <http://www.prismtech.com/dds-community>`_
* `The AdLink DDS Forum <http://www.prismtech.com/dds-community/community-interaction>`_
*******
Support
*******
* `Knowledge base <https://kb.prismtech.com/>`_
* `Support (registered users) <http://www.prismtech.com/support>`_
And last but note least: please always feel welcome to ask questions on
GitHub!

53
src/docs/GettingStartedGuide/uninstall.rst
View file

@ -15,53 +15,8 @@
\newpage
######################
Uninstalling CycloneDDS
######################
################################
Uninstalling Eclipse Cyclone DDS
################################
*****
Linux
*****
Uninstalling CycloneDDS on Linux can be established by invoking
the following two commands (of which the first is optional):
::
sudo dpkg --remove cyclonedds-dev
sudo dpkg --remove cyclonedds
.. note::
Mind the order in which these commands are run. The development
package (:code:`cyclonedds-dev`) need to be removed first since
it depends on the library version (:code:`cyclonedds`).
*******
Windows
*******
There are two ways to uninstall CycloneDDS from Windows
1. By using the original CycloneDDS :ref:`MSI <WindowsInstallMSI>` file
2. By using Windows "Apps & features"
Original MSI
============
Locate the original CycloneDDS MSI file on your system and start it.
After clicking :code:`Next`, an overview of options appears, amongst which
is the remove option. By clicking :code:`Remove`, all files and folders are
removed, except the CycloneDDS examples (if installed).
Apps & features
===============
Go to :code:`Windows Settings` by clicking the :code:`Settings`-icon ( |settings_icon| )
in the Windows Start Menu. Choose :code:`Apps` in the
:code:`Windows Settings` screen. A list of all installed apps
and programs pops up. Select :code:`CycloneDDS` and choose :code:`Uninstall`.
All installed files and folders will be removed, except the
CycloneDDS examples (if installed).
.. |settings_icon| image:: ../_static/pictures/settings-icon.png
:height: 9
:width: 9
TBD.

10
src/docs/conf.py.in
View file

@ -49,7 +49,7 @@ source_suffix = '.rst'
master_doc = 'index'
# General information about the project.
project = u'@CMAKE_PROJECT_NAME@'
project = u'@CMAKE_PROJECT_NAME_FULL@'
copyright = u'@sph_conf_copyright@'
author = u'@sph_conf_author@'
@ -119,7 +119,7 @@ html_sidebars = {
# -- Options for HTMLHelp output ------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = '@CMAKE_PROJECT_NAME@doc'
htmlhelp_basename = '@CMAKE_PROJECT_NAME_FULL@doc'
# -- Options for LaTeX output ---------------------------------------------
@ -147,7 +147,7 @@ latex_elements = {
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, '@CMAKE_PROJECT_NAME@.tex', u'@CMAKE_PROJECT_NAME@',
(master_doc, '@CMAKE_PROJECT_NAME@.tex', u'@CMAKE_PROJECT_NAME_FULL@',
u'@sph_conf_author@', 'manual'),
]
@ -158,7 +158,7 @@ latex_logo = u'@sph_logo@'
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
#man_pages = [
# (master_doc, 'cyclonedds', u'CycloneDDS Documentation',
# (master_doc, 'cyclonedds', u'Eclipse Cyclone DDS Documentation',
# [author], 1)
#]
@ -169,7 +169,7 @@ latex_logo = u'@sph_logo@'
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, '@CMAKE_PROJECT_NAME@', u'@CMAKE_PROJECT_NAME@ Documentation',
(master_doc, '@CMAKE_PROJECT_NAME_FULL@', u'@CMAKE_PROJECT_NAME_FULL@ Documentation',
author, '@CMAKE_PROJECT_NAME@', 'One line description of project.',
'Miscellaneous'),
]

123
src/docs/config.rst
View file

@ -1,14 +1,14 @@
###################################################
A guide to the configuration options of Cyclone DDS
###################################################
###########################################################
A guide to the configuration options of Eclipse Cyclone DDS
###########################################################
This document attempts to provide background information that will help in adjusting the
configuration of Cyclone DDS when the default settings do not give the desired behavior.
configuration of Eclipse Cyclone DDS when the default settings do not give the desired behavior.
A full listing of all settings is out of scope for this document, but can be extracted
from the sources.
.. _`DDSI Concepts`
.. _`DDSI Concepts`:
DDSI Concepts
*************
@ -18,10 +18,10 @@ correspondence between the entities in DDSI and those in DCPS. However, this
correspondence is not one-to-one.
In this section we give a high-level description of the concepts of the DDSI
specification, with hardly any reference to the specifics of the Cyclone DDS
specification, with hardly any reference to the specifics of the Eclipse Cyclone DDS
implementation, which are addressed in subsequent sections. This division was chosen to
aid readers interested in interoperability to understand where the specification ends
and the Cyclone DDS implementation begins.
and the Eclipse Cyclone DDS implementation begins.
.. _`Mapping of DCPS domains to DDSI domains`:
@ -89,7 +89,7 @@ are stored in the writer history cache (or *WHC*) of the DDSI writer. The DDSI
is required to periodically send *Heartbeats* to its readers to ensure that all readers
will learn of the presence of new samples in the WHC even when packets get lost. It is
allowed to suppress these periodic Heartbeats if there is all samples in the WHC have
been acknowledged by all matched readers and the Cyclone DDS exploits this freedom.
been acknowledged by all matched readers and the Eclipse Cyclone DDS exploits this freedom.
If a reader receives a Heartbeat and detects it did not receive all samples, it requests
a retransmission by sending an *AckNack* message to the writer. The timing of this is
@ -106,7 +106,7 @@ from its WHC when it fills up too far, and allows readers to always receive all
complication exists in the case of unresponsive readers, readers that do not respond to
a Heartbeat at all, or that for some reason fail to receive some samples despite
resending it. The specification leaves the way these get treated unspecified. The
default beahviour of Cyclone DDS is to never consider readers unresponsive, but it can
default beahviour of Eclipse Cyclone DDS is to never consider readers unresponsive, but it can
be configured to consider them so after a certain length of time has passed at which
point the participant containing the reader is undiscovered.
@ -135,7 +135,7 @@ sample for each existing instance.
Naturally, once the DCPS writer is deleted (or disappears for whatever reason), the DDSI
writer disappears as well, and with it, its history. For this reason, transient data is
generally much to be preferred over transient-local data. Cyclone DDS has a facility
generally much to be preferred over transient-local data. Eclipse Cyclone DDS has a facility
for retrieving transient data from an suitably configured OpenSplice node, but does not
yet include a native service for managing transient data.
@ -162,14 +162,14 @@ The protocol does allow for unicast-based discovery, which requires listing the
addresses of machines where participants may be located and ensuring each participant
uses one of a small set of port numbers. Because of this, some of the port numbers are
derived not only from the domain id, but also from a *participant index*, which is a
small non-negative integer, unique to a participant within a node. (Cyclone DDS adds an
small non-negative integer, unique to a participant within a node. (Eclipse Cyclone DDS adds an
indirection and uses at most one participant index for a domain for each process,
regardless of how many DCPS participants are created by the process.)
Once two participants have discovered each other and both have matched the DDSI built-in
endpoints their peer is advertising in the SPDP message, the *Simple Endpoint Discovery
Protocol* or *SEDP* takes over, exchanging information on the DCPS data readers and data
writers (and for Cyclone DDS, also publishers, subscribers and topics in a manner
writers (and for Eclipse Cyclone DDS, also publishers, subscribers and topics in a manner
compatible with OpenSplice) in the two participants.
The SEDP data is handled as reliable, transient-local data. Therefore, the SEDP writers
@ -183,10 +183,10 @@ participant is added to the system: *all* existing participants respond to the S
message, following which all start exchanging SEDP data.
.. _`Cyclone DDS specifics`:
.. _`Eclipse Cyclone DDS specifics`:
Cyclone DDS specifics
*********************
Eclipse Cyclone DDS specifics
*****************************
.. _`Discovery behaviour`:
@ -198,7 +198,7 @@ Discovery behaviour
Proxy participants and endpoints
--------------------------------
Cyclone DDS is what the DDSI specification calls a *stateful* implementation. Writers
Eclipse Cyclone DDS is what the DDSI specification calls a *stateful* implementation. Writers
only send data to discovered readers and readers only accept data from discovered
writers. (There is one exception: the writer may choose to multicast the data, and
anyone listening will be able to receive it, if a reader has already discovered the
@ -206,7 +206,7 @@ writer but not vice-versa; it may accept the data even though the connection is
fully established yet. At present, not only can such asymmetrical discovery cause data
to be delivered when it was perhaps not expected, it can also cause indefinite blocking
if the situation persists for a long time.) Consequently, for each remote participant
and reader or writer, Cyclone DDS internally creates a proxy participant, proxy reader
and reader or writer, Eclipse Cyclone DDS internally creates a proxy participant, proxy reader
or proxy writer. In the discovery process, writers are matched with proxy readers, and
readers are matched with proxy writers, based on the topic and type names and the QoS
settings.
@ -215,7 +215,7 @@ Proxies have the same natural hierarchy that ‘normal’ DDSI entities have: ea
endpoint is owned by some proxy participant, and once the proxy participant is deleted,
all of its proxy endpoints are deleted as well. Participants assert their liveliness
periodically (called *automic* liveliness in the DCPS specification and the only mode
currently supported by Cyclone DDS), and when nothing has been heard from a participant
currently supported by Eclipse Cyclone DDS), and when nothing has been heard from a participant
for the lease duration published by that participant in its SPDP message, the lease
becomes expired triggering a clean-up.
@ -230,11 +230,11 @@ to expire.
Sharing of discovery information
--------------------------------
As Cyclone DDS handles any number of participants in an integrated manner, the discovery
As Eclipse Cyclone DDS handles any number of participants in an integrated manner, the discovery
protocol as sketched earlier is rather wasteful: there is no need for each individual
participant in a Cyclone DDS process to run the full discovery protocol for itself.
participant in a Eclipse Cyclone DDS process to run the full discovery protocol for itself.
Instead of implementing the protocol as suggested by the standard, Cyclone DDS shares
Instead of implementing the protocol as suggested by the standard, Eclipse Cyclone DDS shares
all discovery activities amongst the participants, allowing one to add participants on a
process with only a minimal impact on the system. It is even possible to have only a
single DDSI participant in a process regardless of the number of DCPS participants
@ -246,7 +246,7 @@ affected.
Because other implementations of the DDSI specification may be written on the assumption
that all participants perform their own discovery, it is possible to simulate that with
Cyclone DDS. It will not actually perform the discovery for each participant
Eclipse Cyclone DDS. It will not actually perform the discovery for each participant
independently, but it will generate the network traffic *as if* it does. These are
controlled by the ``Internal/BuiltinEndpointSet`` and
``Internal/ConservativeBuiltinReaderStartup`` options. However, please note that at the
@ -267,12 +267,12 @@ Lingering writers
When an application deletes a reliable DCPS data writer, there is no guarantee that all
its readers have already acknowledged the correct receipt of all samples. In such a
case, Cyclone DDS lets the writer (and the owning participant if necessary) linger in
case, Eclipse Cyclone DDS lets the writer (and the owning participant if necessary) linger in
the system for some time, controlled by the ``Internal/WriterLingerDuration`` option.
The writer is deleted when all samples have been acknowledged by all readers or the
linger duration has elapsed, whichever comes first.
Note that the writer linger duration setting is currently not applied when Cyclone DDS
Note that the writer linger duration setting is currently not applied when Eclipse Cyclone DDS
is requested to terminate.
@ -281,7 +281,7 @@ is requested to terminate.
Start-up mode
-------------
A similar issue exists when starting Cyclone DDS: DDSI discovery takes time, and when
A similar issue exists when starting Eclipse Cyclone DDS: DDSI discovery takes time, and when
data is written immediately after the first participant was created, it is likely that
the discovery process hasn’t completed yet and some remote readers have not yet been
discovered. This would cause the writers to throw away samples for lack of interest,
@ -372,7 +372,7 @@ Network and discovery configuration
Networking interfaces
=====================
Cyclone DDS uses a single network interface, the *preferred* interface, for transmitting
Eclipse Cyclone DDS uses a single network interface, the *preferred* interface, for transmitting
its multicast packets and advertises only the address corresponding to this interface in
the DDSI discovery protocol.
@ -398,7 +398,7 @@ is always preferred and is the only option that allows selecting the desired one
multiple addresses are tied to a single interface.
The default address family is IPv4, setting General/UseIPv6 will change this to IPv6.
Currently, Cyclone DDS does not mix IPv4 and IPv6 addressing. Consequently, all DDSI
Currently, Eclipse Cyclone DDS does not mix IPv4 and IPv6 addressing. Consequently, all DDSI
participants in the network must use the same addressing mode. When interoperating,
this behaviour is the same, i.e., it will look at either IPv4 or IPv6 addresses in the
advertised address information in the SPDP and SEDP discovery protocols.
@ -412,7 +412,7 @@ DDS will operate in a *global addressing* mode and will only consider discovered
non-link-local addresses. In this mode, one can select any set of interface for
listening to multicasts. Note that this behaviour is essentially identical to that when
using IPv4, as IPv4 does not have the formal notion of address scopes that IPv6 has. If
instead only a link-local address is available, Cyclone DDS will run in a *link-local
instead only a link-local address is available, Eclipse Cyclone DDS will run in a *link-local
addressing* mode. In this mode it will accept any address in a discovery packet,
assuming that a link-local address is valid on the preferred interface. To minimise the
risk involved in this assumption, it only allows the preferred interface for listening
@ -431,7 +431,7 @@ in the same way as for network interfaces.
Multicasting
------------
Cyclone DDS allows configuring to what extent multicast (the regular, any-source
Eclipse Cyclone DDS allows configuring to what extent multicast (the regular, any-source
multicast as well as source-specific multicast) is to be used:
+ whether to use multicast for data communications,
@ -463,7 +463,7 @@ TCP support
The DDSI protocol is really a protocol designed for a transport providing
connectionless, unreliable datagrams. However, there are times where TCP is the only
practical network transport available (for example, across a WAN). Because of this,
Cyclone DDS can use TCP instead of UDP.
Eclipse Cyclone DDS can use TCP instead of UDP.
The differences in the model of operation between DDSI and TCP are quite large: DDSI is
based on the notion of peers, whereas TCP communication is based on the notion of a
@ -500,7 +500,7 @@ initiated.
Raw Ethernet support
--------------------
As an additional option, on Linux, Cyclone DDS can use a raw Ethernet network interface
As an additional option, on Linux, Eclipse Cyclone DDS can use a raw Ethernet network interface
to communicate without a configured IP stack.
@ -581,7 +581,7 @@ Endpoint discovery
..................
Although the SEDP protocol never requires any configuration, network partitioning does
interact with it: so-called ‘ignored partitions’ can be used to instruct Cyclone DDS to
interact with it: so-called ‘ignored partitions’ can be used to instruct Eclipse Cyclone DDS to
completely ignore certain DCPS topic and partition combinations, which will prevent data
for these topic/partition combinations from being forwarded to and from the network.
@ -623,8 +623,8 @@ received for a participant that has not yet been discovered.
Controlling port numbers
========================
The port numbers used by by Cyclone DDS are determined as follows, where the first two
items are given by the DDSI specification and the third is unique to Cyclone DDS as a
The port numbers used by by Eclipse Cyclone DDS are determined as follows, where the first two
items are given by the DDSI specification and the third is unique to Eclipse Cyclone DDS as a
way of serving multiple participants by a single DDSI instance:
+ 2 ‘well-known’ multicast ports: ``B`` and ``B+1``
@ -649,7 +649,7 @@ PI is the most interesting, as it relates to having multiple processes in the sa
domain on a single node. Its configured value is either *auto*, *none* or a non-negative
integer. This setting matters:
+ When it is *auto* (which is the default), Cyclone DDS probes UDP port numbers on
+ When it is *auto* (which is the default), Eclipse Cyclone DDS probes UDP port numbers on
start-up, starting with PI = 0, incrementing it by one each time until it finds a pair
of available port numbers, or it hits the limit. The maximum PI it will ever choose
is ``Discovery/MaxAutoParticipantIndex`` as a way of limiting the cost of unicast
@ -674,12 +674,12 @@ item in the list. These are used only because there exist some DDSI implementat
that assume each domain participant advertises a unique port number as part of the
discovery protocol, and hence that there is never any need for including an explicit
destination participant id when intending to address a single domain participant by
using its unicast locator. Cyclone DDS never makes this assumption, instead opting to
using its unicast locator. Eclipse Cyclone DDS never makes this assumption, instead opting to
send a few bytes extra to ensure the contents of a message are all that is needed. With
other implementations, you will need to check.
If all DDSI implementations in the network include full addressing information in the
messages like Cyclone DDS does, then the per-domain participant ports serve no purpose
messages like Eclipse Cyclone DDS does, then the per-domain participant ports serve no purpose
at all. The default ``false`` setting of ``Compatibility/ManySocketsMode`` disables the
creation of these ports.
@ -706,7 +706,7 @@ retransmitting the same sample over & over again to many different readers. Sim
while readers should try to avoid requesting retransmissions too often, in an
interoperable system the writers should be robust against it.
In Cyclone DDS, upon receiving a Heartbeat that indicates samples are missing, a reader
In Eclipse Cyclone DDS, upon receiving a Heartbeat that indicates samples are missing, a reader
will schedule the second and following retransmission requests to be sent after
``Internal/NackDelay`` or combine it with an already scheduled request if possible. Any
samples received in between receipt of the Heartbeat and the sending of the AckNack will
@ -734,7 +734,7 @@ the writer simply queues all these samples for retransmission, it may well resul
huge backlog of samples to be retransmitted. As a result, the ones near the end of the
queue may be delayed by so much that the reader issues another retransmit request.
Therefore, Cyclone DDS limits the number of samples queued for retransmission and
Therefore, Eclipse Cyclone DDS limits the number of samples queued for retransmission and
ignores (those parts of) retransmission requests that would cause the retransmit queue
to contain too many samples or take too much time to process. There are two settings
governing the size of these queues, and the limits are applied per timed-event thread.
@ -754,7 +754,7 @@ Samples in DDS can be arbitrarily large, and will not always fit within a single
datagram. DDSI has facilities to fragment samples so they can fit in UDP datagrams, and
similarly IP has facilities to fragment UDP datagrams to into network packets. The DDSI
specification states that one must not unnecessarily fragment at the DDSI level, but
Cyclone DDS simply provides a fully configurable behaviour.
Eclipse Cyclone DDS simply provides a fully configurable behaviour.
If the serialised form of a sample is at least ``Internal/FragmentSize``,
it will be fragmented using the DDSI fragmentation. All but the last fragment
@ -835,14 +835,14 @@ priority, effectively enabling synchronous delivery for all data.
Maximum sample size
===================
Cyclone DDS provides a setting, ``Internal/MaxSampleSize``, to control the maximum size
Eclipse Cyclone DDS provides a setting, ``Internal/MaxSampleSize``, to control the maximum size
of samples that the service is willing to process. The size is the size of the (CDR)
serialised payload, and the limit holds both for built-in data and for application data.
The (CDR) serialised payload is never larger than the in-memory representation of the
data.
On the transmitting side, samples larger than ``MaxSampleSize`` are dropped with a
warning in the. Cyclone DDS behaves as if the sample never existed.
warning in the. Eclipse Cyclone DDS behaves as if the sample never existed.
Similarly, on the receiving side, samples large than ``MaxSampleSize`` are dropped as
early as possible, immediately following the reception of a sample or fragment of one,
@ -904,10 +904,10 @@ partition mappings are specified in the configuration. The first matching mappi
the one that will be used. The ``*`` and ``?`` wildcards are available for the DCPS
partition/topic combination in the partition mapping.
As mentioned earlier (see `Local discovery and built-in topics`_), Cyclone DDS can be
instructed to ignore all DCPS data readers and writers for certain DCPS partition/topic
combinations through the use of *IgnoredPartitions*. The ignored partitions use the
same matching rules as normal mappings, and take precedence over the normal mappings.
As mentioned earlier, Eclipse Cyclone DDS can be instructed to ignore all DCPS data
readers and writers for certain DCPS partition/topic combinations through the use of
*IgnoredPartitions*. The ignored partitions use the same matching rules as normal
mappings, and take precedence over the normal mappings.
.. _`Multiple matching mappings`:
@ -926,7 +926,7 @@ data the reader will receive; it only affects the addressing on the network.
Thread configuration
********************
Cyclone DDS creates a number of threads and each of these threads has a number of
Eclipse Cyclone DDS creates a number of threads and each of these threads has a number of
properties that can be controlled individually. The properties that can be controlled
are:
@ -941,7 +941,7 @@ anything not specified explicitly is left at the default value.
The following threads exist:
+ *gc*: garbage collector, which sleeps until garbage collection is requested for an
entity, at which point it starts monitoring the state of Cyclone DDS, pushing the
entity, at which point it starts monitoring the state of Eclipse Cyclone DDS, pushing the
entity through whatever state transitions are needed once it is safe to do so, ending
with the freeing of the memory.
+ *recv*: accepts incoming network packets from all sockets/ports, performs all protocol
@ -949,7 +949,7 @@ The following threads exist:
timed-event thread, queues for delivery or, in special cases, delivers it directly to
the data readers.
+ *dq.builtins*: processes all discovery data coming in from the network.
+ *lease*: performs internal liveliness monitoring of Cyclone DDS.
+ *lease*: performs internal liveliness monitoring of Eclipse Cyclone DDS.
+ *tev*: timed-event handling, used for all kinds of things, such as: periodic
transmission of participant discovery and liveliness messages, transmission of control
messages for reliable writers and readers (except those that have their own
@ -973,7 +973,7 @@ When no channels are explicitly defined, there is one channel named *user*.
Reporting and tracing
*********************
Cyclone DDS can produce highly detailed traces of all traffic and internal activities.
Eclipse Cyclone DDS can produce highly detailed traces of all traffic and internal activities.
It enables individual categories of information, as well as having a simple verbosity
level that enables fixed sets of categories.
@ -1058,26 +1058,21 @@ Compatibility and conformance
Conformance modes
=================
Cyclone DDS operates in one of three modes: *pedantic*, *strict* and *lax*; the mode is
Eclipse Cyclone DDS operates in one of three modes: *pedantic*, *strict* and *lax*; the mode is
configured using the ``Compatibility/StandardsConformance`` setting. The default is
*lax*.
The first, *pedantic* mode, is of such limited utility that it will be removed.
The second mode, *strict*, attempts to follow the *intent* of the specification while
staying close to the letter of it. The points in which it deviates from the standard are
in all probability editing errors that will be rectified in the next update. When
operated in this mode, one would expect it to be fully interoperable with other vendors’
implementations, but this is not the case. The deviations in other vendors’
implementations are not required to implement DDSI 2.1 (or 2.2), as is proven by, e.g.,
the OpenSplice DDSI2 service, and they cannot rightly be considered ‘true’
implementations of the DDSI 2.1 (or 2.2) standard.
staying close to the letter of it. Recent developments at the OMG have resolved these
issues and this mode is no longer of any value.
The default mode, *lax*, attempts to work around (most of) the deviations of other
implementations, and generally provides good interoperability without any further
settings. In lax mode, the Cyclone DDS not only accepts some invalid messages, it will
settings. In lax mode, the Eclipse Cyclone DDS not only accepts some invalid messages, it will
even transmit them. The consequences for interoperability of not doing this are simply
too severe. It should be noted that if one configures two Cyclone DDS processes with
too severe. It should be noted that if one configures two Eclipse Cyclone DDS processes with
different compliancy modes, the one in the stricter mode will complain about messages
sent by the one in the less strict mode.
@ -1095,7 +1090,7 @@ establish bidirectional communication between the two.
Disposing data may also cause problems, as RTI DDS leaves out the serialised key value
and instead expects the reader to rely on an embedded hash of the key value. In the
strict modes, Cyclone DDS requires a proper key value to be supplied; in the relaxed
strict modes, Eclipse Cyclone DDS requires a proper key value to be supplied; in the relaxed
mode, it is willing to accept key hash, provided it is of a form that contains the key
values in an unmangled form.
@ -1106,14 +1101,14 @@ maximum length larger than 11 bytes. See the DDSI specification for details.
In *strict* mode, there is interoperation with RTI DDS, but at the cost of incredibly
high CPU and network load, caused by a Heartbeats and AckNacks going back-and-forth
between a reliable RTI DDS data writer and a reliable Cyclone DDS data reader. The
problem is that once Cyclone DDS informs the RTI writer that it has received all data
between a reliable RTI DDS data writer and a reliable Eclipse Cyclone DDS data reader. The
problem is that once Eclipse Cyclone DDS informs the RTI writer that it has received all data
(using a valid AckNack message), the RTI writer immediately publishes a message listing
the range of available sequence numbers and requesting an acknowledgement, which becomes
an endless loop.
There is furthermore also a difference of interpretation of the meaning of the
‘autodispose_unregistered_instances’ QoS on the writer. Cyclone DDS aligns with
‘autodispose_unregistered_instances’ QoS on the writer. Eclipse Cyclone DDS aligns with
OpenSplice.

4
src/docs/ddsc.rst
View file

@ -9,8 +9,8 @@
SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
Cyclone DDS C API Reference
==========================
Eclipse Cyclone DDS C API Reference
===================================
.. doxygenindex::
:project: ddsc_api

7
src/docs/index.rst
View file

@ -9,10 +9,10 @@
SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
.. CycloneDDS documentation master file
.. Eclipse Cyclone DDS documentation master file
Welcome to CycloneDDS's documentation!
=====================================
Welcome to Eclipse Cyclone DDS's documentation!
===============================================
.. toctree::
:maxdepth: 3
@ -20,6 +20,7 @@ Welcome to CycloneDDS's documentation!
GettingStartedGuide/index
ddsc
config
Indices and tables
==================