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/CMakeLists.txt
View file

@ -38,8 +38,8 @@ execute_process(COMMAND git submodule update
# Set module path before defining project so platform files will work. # Set module path before defining project so platform files will work.
set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/cmake/modules") set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/cmake/modules")
set(CMAKE_PROJECT_NAME_FULL "Cyclone DDS") set(CMAKE_PROJECT_NAME_FULL "Eclipse Cyclone DDS")
string(REPLACE " " "" PROJECT_NAME "${CMAKE_PROJECT_NAME_FULL}") set(PROJECT_NAME "CycloneDDS")
project(${PROJECT_NAME} VERSION 0.1.0) project(${PROJECT_NAME} VERSION 0.1.0)
# Set some convenience variants of the project-name # Set some convenience variants of the project-name

4
src/docs/CMakeLists.txt
View file

@ -131,11 +131,9 @@ elseif(BUILD_DOCS)
endif() endif()
# Process sphinx configuration file # Process sphinx configuration file
set(sph_conf_author "ADLINK") set(sph_conf_author "Eclipse Cyclone DDS project")
string(TIMESTAMP sph_conf_copyright "%Y, ADLINK")
set(sph_conf_version "${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}.${PROJECT_VERSION_PATCH}") set(sph_conf_version "${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}.${PROJECT_VERSION_PATCH}")
set(sph_conf_release "${PROJECT_VERSION}") 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) configure_file(conf.py.in conf.py @ONLY)
# Define a list of output formats (-b option for sphinx-build) # Define a list of output formats (-b option for sphinx-build)

2
src/docs/Doxyfile.in
View file

@ -2037,7 +2037,7 @@ INCLUDE_FILE_PATTERNS =
# recursively expanded use the := operator instead of the = operator. # recursively expanded use the := operator instead of the = operator.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. # 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 # 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 # tag can be used to specify a list of macro names that should be expanded. The

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

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

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

@ -15,9 +15,9 @@
\newpage \newpage
################# ##############################
Install CycloneDDS Installing Eclipse Cyclone DDS
################# ##############################
.. .. contents:: .. .. contents::
@ -28,31 +28,12 @@ Install CycloneDDS
System requirements System requirements
******************* *******************
Currently AdLink CycloneDDS is supported on the following platforms: 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.
+-------------------+--------------+--------------------+
| Operating systems | Architecture | Compiler |
+===================+==============+====================+
| Ubuntu 16.04 LTS | 64-bit | gcc 5.4 or later |
+-------------------+--------------+--------------------+
| Windows 10 | 64 -bit | VS2015 |
+-------------------+--------------+--------------------+
***************
***** Linux and macOS
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
.. _`CopyLinuxExamplesToUserFriendlyLocation`: .. _`CopyLinuxExamplesToUserFriendlyLocation`:
@ -60,11 +41,10 @@ On Ubuntu and other debian-derived platforms, the product can be installed using
Post install steps Post install steps
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~
The installation package installs examples in system directories. The installation package installs examples in system directories. In order to have a better user
In order to have a better user experience when building the CycloneDDS experience when building the Eclipse Cyclone DDS examples, it is advised to copy the examples to a
examples, it is advised to copy the examples to a user-defined location. user-defined location. This is to be able to build the examples natively and experiment with the
This is to be able to build the examples natively and experiment with example source code.
the example source code.
For this, the installation package provides the vdds_install_examples For this, the installation package provides the vdds_install_examples
script, located in /usr/bin. 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. 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`: .. _`LinuxSetLibPath`:
Paths Paths
===== =====
To be able to run CycloneDDS executables, the required libraries (like To be able to run Eclipse Cyclone DDS executables, the required libraries (like libddsc.so) need to
libddsc.so) need to be available to the executables. be available to the executables. Normally, these are installed in system default locations and it
Normally, these are installed in system default locations and it works works out-of-the-box. However, if they are not installed in those locations, it is possible that the
out-of-the-box. However, if they are not installed in those locations, library search path has to be changed. This can be achieved by executing the command: ::
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 export LD_LIBRARY_PATH=<install_dir>/lib:$LD_LIBRARY_PATH
@ -120,49 +73,19 @@ This can be achieved by executing the command:
Windows 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`: .. _`WindowsSetLibPath`:
Paths Paths
~~~~~ ~~~~~
To be able to run CycloneDDS executables, the required libraries (like To be able to run Eclipse Cyclone DDS executables, the required libraries (like ddsc.dll) need to be
ddsc.dll) need to be available to the executables. available to the executables. Normally, these are installed in system default locations and it
Normally, these are installed in system default locations and it works works out-of-the-box. However, if they are not installed on those locations, it is possible that the
out-of-the-box. However, if they are not installed on those locations, library search path has to be changed. This can be achieved by executing the command: ::
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% set PATH=<install_dir>/bin;%PATH%
.. note::
The MSI installer will add this path to the PATH environment
variable automatically.
.. _`TestYourInstallation`: .. _`TestYourInstallation`:
@ -170,11 +93,9 @@ This can be achieved by executing the command:
Test your installation Test your installation
********************** **********************
The installation provides a simple prebuilt :ref:`Hello World! <HelloWorld>` application which Eclipse Cyclone DDS includes a simple :ref:`Hello World! <HelloWorld>` application which can be run
can be run in order to test your installation. The *Hello World!* application consists of two in order to test your installation. The *Hello World!* application consists of two executables: a so
executables: a so called HelloworldPublisher and a HelloworldSubscriber, typically located in called HelloworldPublisher and a HelloworldSubscriber.
: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.
To run the example application, please open two console windows and navigate to the appropriate 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 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 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. 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? What's next?
############ ############
Want to know more about CycloneDDS? Please consider following a tutorial or Want to know more about DDS? The primary source of information is the
visit some of the pages listed below. 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.
************************* There are also various resources on the web dealing with DDS in general,
The OMG DDS Specification 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 Obviously there are also things specific to Eclipse Cyclone DDS. The
Group® (OMG®) for over several years and is heavily involved in the development of the level of documentation of Eclipse is not nearly what it should be, but
DDS specification. Please visit the OMG website at http://www.omg.org and that should improve over time.
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.
************************************* And last but note least: please always feel welcome to ask questions on
AdLink Documentation and Tutorials GitHub!
*************************************
* `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>`_

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

@ -15,53 +15,8 @@
\newpage \newpage
###################### ################################
Uninstalling CycloneDDS Uninstalling Eclipse Cyclone DDS
###################### ################################
***** TBD.
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

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

@ -49,7 +49,7 @@ source_suffix = '.rst'
master_doc = 'index' master_doc = 'index'
# General information about the project. # General information about the project.
project = u'@CMAKE_PROJECT_NAME@' project = u'@CMAKE_PROJECT_NAME_FULL@'
copyright = u'@sph_conf_copyright@' copyright = u'@sph_conf_copyright@'
author = u'@sph_conf_author@' author = u'@sph_conf_author@'
@ -119,7 +119,7 @@ html_sidebars = {
# -- Options for HTMLHelp output ------------------------------------------ # -- Options for HTMLHelp output ------------------------------------------
# Output file base name for HTML help builder. # 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 --------------------------------------------- # -- Options for LaTeX output ---------------------------------------------
@ -147,7 +147,7 @@ latex_elements = {
# (source start file, target name, title, # (source start file, target name, title,
# author, documentclass [howto, manual, or own class]). # author, documentclass [howto, manual, or own class]).
latex_documents = [ 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'), u'@sph_conf_author@', 'manual'),
] ]
@ -158,7 +158,7 @@ latex_logo = u'@sph_logo@'
# One entry per manual page. List of tuples # One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section). # (source start file, name, description, authors, manual section).
#man_pages = [ #man_pages = [
# (master_doc, 'cyclonedds', u'CycloneDDS Documentation', # (master_doc, 'cyclonedds', u'Eclipse Cyclone DDS Documentation',
# [author], 1) # [author], 1)
#] #]
@ -169,7 +169,7 @@ latex_logo = u'@sph_logo@'
# (source start file, target name, title, author, # (source start file, target name, title, author,
# dir menu entry, description, category) # dir menu entry, description, category)
texinfo_documents = [ 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.', author, '@CMAKE_PROJECT_NAME@', 'One line description of project.',
'Miscellaneous'), '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 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 A full listing of all settings is out of scope for this document, but can be extracted
from the sources. from the sources.
.. _`DDSI Concepts` .. _`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. correspondence is not one-to-one.
In this section we give a high-level description of the concepts of the DDSI 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 implementation, which are addressed in subsequent sections. This division was chosen to
aid readers interested in interoperability to understand where the specification ends 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`: .. _`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 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 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 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 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 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 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 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 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 be configured to consider them so after a certain length of time has passed at which
point the participant containing the reader is undiscovered. 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 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 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 for retrieving transient data from an suitably configured OpenSplice node, but does not
yet include a native service for managing transient data. 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 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 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 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, 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.) 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 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 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 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. compatible with OpenSplice) in the two participants.
The SEDP data is handled as reliable, transient-local data. Therefore, the SEDP writers 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. message, following which all start exchanging SEDP data.
.. _`Cyclone DDS specifics`: .. _`Eclipse Cyclone DDS specifics`:
Cyclone DDS specifics Eclipse Cyclone DDS specifics
********************* *****************************
.. _`Discovery behaviour`: .. _`Discovery behaviour`:
@ -198,7 +198,7 @@ Discovery behaviour
Proxy participants and endpoints 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 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 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 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 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 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 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 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 readers are matched with proxy writers, based on the topic and type names and the QoS
settings. 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, 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 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 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 for the lease duration published by that participant in its SPDP message, the lease
becomes expired triggering a clean-up. becomes expired triggering a clean-up.
@ -230,11 +230,11 @@ to expire.
Sharing of discovery information 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 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 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 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 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 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 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 independently, but it will generate the network traffic *as if* it does. These are
controlled by the ``Internal/BuiltinEndpointSet`` and controlled by the ``Internal/BuiltinEndpointSet`` and
``Internal/ConservativeBuiltinReaderStartup`` options. However, please note that at the ``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 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 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 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 The writer is deleted when all samples have been acknowledged by all readers or the
linger duration has elapsed, whichever comes first. 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. is requested to terminate.
@ -281,7 +281,7 @@ is requested to terminate.
Start-up mode 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 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 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, discovered. This would cause the writers to throw away samples for lack of interest,
@ -372,7 +372,7 @@ Network and discovery configuration
Networking interfaces 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 its multicast packets and advertises only the address corresponding to this interface in
the DDSI discovery protocol. 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. multiple addresses are tied to a single interface.
The default address family is IPv4, setting General/UseIPv6 will change this to IPv6. 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, 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 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. 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 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 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 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, 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 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 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 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: multicast as well as source-specific multicast) is to be used:
+ whether to use multicast for data communications, + 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 The DDSI protocol is really a protocol designed for a transport providing
connectionless, unreliable datagrams. However, there are times where TCP is the only connectionless, unreliable datagrams. However, there are times where TCP is the only
practical network transport available (for example, across a WAN). Because of this, 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 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 based on the notion of peers, whereas TCP communication is based on the notion of a
@ -500,7 +500,7 @@ initiated.
Raw Ethernet support 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. to communicate without a configured IP stack.
@ -581,7 +581,7 @@ Endpoint discovery
.................. ..................
Although the SEDP protocol never requires any configuration, network partitioning does 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 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. 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 Controlling port numbers
======================== ========================
The port numbers used by by Cyclone DDS are determined as follows, where the first two 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 Cyclone DDS as a 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: way of serving multiple participants by a single DDSI instance:
+ 2 ‘well-known’ multicast ports: ``B`` and ``B+1`` + 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 domain on a single node. Its configured value is either *auto*, *none* or a non-negative
integer. This setting matters: 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 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 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 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 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 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 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 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. other implementations, you will need to check.
If all DDSI implementations in the network include full addressing information in the 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 at all. The default ``false`` setting of ``Compatibility/ManySocketsMode`` disables the
creation of these ports. 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 while readers should try to avoid requesting retransmissions too often, in an
interoperable system the writers should be robust against it. 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 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 ``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 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 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. 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 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 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. 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 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 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 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``, 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 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 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) 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. 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 The (CDR) serialised payload is never larger than the in-memory representation of the
data. data.
On the transmitting side, samples larger than ``MaxSampleSize`` are dropped with a 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 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, 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 the one that will be used. The ``*`` and ``?`` wildcards are available for the DCPS
partition/topic combination in the partition mapping. partition/topic combination in the partition mapping.
As mentioned earlier (see `Local discovery and built-in topics`_), Cyclone DDS can be As mentioned earlier, Eclipse Cyclone DDS can be instructed to ignore all DCPS data
instructed to ignore all DCPS data readers and writers for certain DCPS partition/topic readers and writers for certain DCPS partition/topic combinations through the use of
combinations through the use of *IgnoredPartitions*. The ignored partitions use the *IgnoredPartitions*. The ignored partitions use the same matching rules as normal
same matching rules as normal mappings, and take precedence over the normal mappings. mappings, and take precedence over the normal mappings.
.. _`Multiple matching mappings`: .. _`Multiple matching mappings`:
@ -926,7 +926,7 @@ data the reader will receive; it only affects the addressing on the network.
Thread configuration 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 properties that can be controlled individually. The properties that can be controlled
are: are:
@ -941,7 +941,7 @@ anything not specified explicitly is left at the default value.
The following threads exist: The following threads exist:
+ *gc*: garbage collector, which sleeps until garbage collection is requested for an + *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 entity through whatever state transitions are needed once it is safe to do so, ending
with the freeing of the memory. with the freeing of the memory.
+ *recv*: accepts incoming network packets from all sockets/ports, performs all protocol + *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 timed-event thread, queues for delivery or, in special cases, delivers it directly to
the data readers. the data readers.
+ *dq.builtins*: processes all discovery data coming in from the network. + *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 + *tev*: timed-event handling, used for all kinds of things, such as: periodic
transmission of participant discovery and liveliness messages, transmission of control transmission of participant discovery and liveliness messages, transmission of control
messages for reliable writers and readers (except those that have their own 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 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 It enables individual categories of information, as well as having a simple verbosity
level that enables fixed sets of categories. level that enables fixed sets of categories.
@ -1058,26 +1058,21 @@ Compatibility and conformance
Conformance modes 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 configured using the ``Compatibility/StandardsConformance`` setting. The default is
*lax*. *lax*.
The first, *pedantic* mode, is of such limited utility that it will be removed. 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 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 staying close to the letter of it. Recent developments at the OMG have resolved these
in all probability editing errors that will be rectified in the next update. When issues and this mode is no longer of any value.
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.
The default mode, *lax*, attempts to work around (most of) the deviations of other The default mode, *lax*, attempts to work around (most of) the deviations of other
implementations, and generally provides good interoperability without any further 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 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 different compliancy modes, the one in the stricter mode will complain about messages
sent by the one in the less strict mode. 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 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 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 mode, it is willing to accept key hash, provided it is of a form that contains the key
values in an unmangled form. 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 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 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 between a reliable RTI DDS data writer and a reliable Eclipse Cyclone DDS data reader. The
problem is that once Cyclone DDS informs the RTI writer that it has received all data 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 (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 the range of available sequence numbers and requesting an acknowledgement, which becomes
an endless loop. an endless loop.
There is furthermore also a difference of interpretation of the meaning of the 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. OpenSplice.

4
src/docs/ddsc.rst
View file

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

7
src/docs/index.rst
View file

@ -9,10 +9,10 @@
SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause 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:: .. toctree::
:maxdepth: 3 :maxdepth: 3
@ -20,6 +20,7 @@ Welcome to CycloneDDS's documentation!
GettingStartedGuide/index GettingStartedGuide/index
ddsc ddsc
config
Indices and tables Indices and tables
================== ==================

30
src/examples/examples.rst
View file

@ -23,24 +23,26 @@ Examples
Configuration Configuration
************* *************
Cyclone DDS has various configuration parameters and comes with a default built-in configuration. Eclipse Cyclone DDS has various configuration parameters and comes with a default built-in
To run an example, or any application that uses Cyclone DDS for its data exchange, this default configuration. To run an example, or any application that uses Eclipse Cyclone DDS for its data
configuration is usually fine and no further action is required. exchange, this default configuration is usually fine and no further action is required.
Configuration parameters for CycloneDDS are expressed in XML and grouped together in a single XML file. Configuration parameters for Eclipse CycloneDDS are expressed in XML and grouped together in a
To use a custom XML configuration in an application, the ``CYCLONEDDS_URI`` environment variable needs single XML file. To use a custom XML configuration in an application, the ``CYCLONEDDS_URI``
to be set prior to starting the application and pointed to the location of the configuration file to environment variable needs to be set prior to starting the application and pointed to the location
be used. of the configuration file to be used.
| *Example* | *Example*
| **Windows:** ``set CYCLONEDDS_URI=file://%USERPROFILE%/CycloneDDS/my-config.xml`` | **Windows:** ``set CYCLONEDDS_URI=file://%USERPROFILE%/CycloneDDS/my-config.xml``
| **Linux:** ``export CYCLONEDDS_URI="file://$HOME/CycloneDDS/my-config.xml"`` | **Linux:** ``export CYCLONEDDS_URI="file://$HOME/CycloneDDS/my-config.xml"``
The CycloneDDS installation comes with a set of standard configuration files for common use cases. The Eclipse CycloneDDS installation comes with a configuration file that corresponds to the default
You update existing configuration files or create your own by using the CycloneDDS Configurator tool, behaviour. You can modify it or add your using any text or XML editor, or using by using the
which provides context-sensitive help on available configuration parameters and their applicability. Eclipse CycloneDDS Configurator tool, which provides context-sensitive help on available
configuration parameters and their applicability.
You can start the CycloneDDS Configuration tool through the CycloneDDS Launcher, or from your command-prompt One very important part of the configuration settings are the "tracing" settings: these allow
by entering the tools directory and running ``java -jar cycloneddsconf.jar``. The default location of the tools letting Eclipse Cyclone DDS trace very detailed information to a file, and this includes the actual
directory is ``/usr/share/CycloneDDS/tools`` on Linux or ``C:\Program Files\ADLINK\Vortex DDS\share\CycloneDDS\tools`` configuration settings in use, including all those that are set at the default. When editing
on Windows. configuration files by hand, this overview can be very useful. Increasing the Verbosity from
"warning" to, e.g., "config" already suffices for getting this information written to the log.

2
src/examples/helloworld/readme.rst
View file

@ -16,7 +16,7 @@ Description
*********** ***********
The basic HelloWorld example is used to illustrate the necessary steps to setup DCPS entities. The basic HelloWorld example is used to illustrate the necessary steps to setup DCPS entities.
Note it is also used in the Getting Started Guide to explain the usage of CycloneDDS. Note it is also used in the Getting Started Guide to explain the usage of Eclipse Cyclone DDS.
Design Design
****** ******