diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index 08a48ad..d2de2ce 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -38,8 +38,8 @@ execute_process(COMMAND git submodule update # Set module path before defining project so platform files will work. set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/cmake/modules") -set(CMAKE_PROJECT_NAME_FULL "Cyclone DDS") -string(REPLACE " " "" PROJECT_NAME "${CMAKE_PROJECT_NAME_FULL}") +set(CMAKE_PROJECT_NAME_FULL "Eclipse Cyclone DDS") +set(PROJECT_NAME "CycloneDDS") project(${PROJECT_NAME} VERSION 0.1.0) # Set some convenience variants of the project-name diff --git a/src/docs/CMakeLists.txt b/src/docs/CMakeLists.txt index 79e14b0..0ce07fd 100644 --- a/src/docs/CMakeLists.txt +++ b/src/docs/CMakeLists.txt @@ -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) diff --git a/src/docs/Doxyfile.in b/src/docs/Doxyfile.in index ea6b34a..32aebfe 100644 --- a/src/docs/Doxyfile.in +++ b/src/docs/Doxyfile.in @@ -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 diff --git a/src/docs/GettingStartedGuide/helloworld.rst b/src/docs/GettingStartedGuide/helloworld.rst index 71e51ea..3b0169f 100644 --- a/src/docs/GettingStartedGuide/helloworld.rst +++ b/src/docs/GettingStartedGuide/helloworld.rst @@ -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 `) 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 ` - 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 % diff --git a/src/docs/GettingStartedGuide/installation.rst b/src/docs/GettingStartedGuide/installation.rst index 2e09ba6..b55eaee 100644 --- a/src/docs/GettingStartedGuide/installation.rst +++ b/src/docs/GettingStartedGuide/installation.rst @@ -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__.deb - sudo dpkg -i cyclonedds-dev__.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--Linux.tar.Z | Tar Compress compression. | -+----------------------------------+---------------------------------------+ -| CycloneDDS--Linux.tar.gz | Tar GZip compression. | -+----------------------------------+---------------------------------------+ -| CycloneDDS--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=/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=/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! ` 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! ` 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! ` chapter. - -******* -License -******* - -TODO: CHAM-325 - diff --git a/src/docs/GettingStartedGuide/next_steps.rst b/src/docs/GettingStartedGuide/next_steps.rst index 7c98511..8b0b9a9 100644 --- a/src/docs/GettingStartedGuide/next_steps.rst +++ b/src/docs/GettingStartedGuide/next_steps.rst @@ -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 `_ page and the +`DDS specification `_ 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 `_ -page and the `DDS specification `_ 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 `_ -* `DDS Tutorial `_ - -******************************** -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 `_ -* `Vortex Youtube `_ -* `Vortex Slideshare `_ -* `Vortex Demo `_ - -********************** -AdLink on Social Media -********************** - -* `Twitter (@ADLINKTech_usa) `_ -* `Facebook `_ -* `LinkedIn `_ - - -***************** -The DDS community -***************** - -* `The AdLink DDS-community `_ -* `The AdLink DDS Forum `_ - -******* -Support -******* - -* `Knowledge base `_ -* `Support (registered users) `_ +And last but note least: please always feel welcome to ask questions on +GitHub! diff --git a/src/docs/GettingStartedGuide/uninstall.rst b/src/docs/GettingStartedGuide/uninstall.rst index b1fac60..8656953 100644 --- a/src/docs/GettingStartedGuide/uninstall.rst +++ b/src/docs/GettingStartedGuide/uninstall.rst @@ -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 ` 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. diff --git a/src/docs/conf.py.in b/src/docs/conf.py.in index 5c80038..5e0694f 100644 --- a/src/docs/conf.py.in +++ b/src/docs/conf.py.in @@ -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'), ] diff --git a/src/docs/config.rst b/src/docs/config.rst index 8425ab5..7223357 100644 --- a/src/docs/config.rst +++ b/src/docs/config.rst @@ -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. diff --git a/src/docs/ddsc.rst b/src/docs/ddsc.rst index 3469f93..8df7fba 100644 --- a/src/docs/ddsc.rst +++ b/src/docs/ddsc.rst @@ -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 diff --git a/src/docs/index.rst b/src/docs/index.rst index f174ebb..0d729a9 100644 --- a/src/docs/index.rst +++ b/src/docs/index.rst @@ -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 ================== diff --git a/src/examples/examples.rst b/src/examples/examples.rst index 96e6fe0..b9ee6d4 100644 --- a/src/examples/examples.rst +++ b/src/examples/examples.rst @@ -23,24 +23,26 @@ Examples Configuration ************* -Cyclone DDS has various configuration parameters and comes with a default built-in configuration. -To run an example, or any application that uses Cyclone DDS for its data exchange, this default -configuration is usually fine and no further action is required. +Eclipse Cyclone DDS has various configuration parameters and comes with a default built-in +configuration. To run an example, or any application that uses Eclipse Cyclone DDS for its data +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. -To use a custom XML configuration in an application, the ``CYCLONEDDS_URI`` environment variable needs -to be set prior to starting the application and pointed to the location of the configuration file to -be used. +Configuration parameters for Eclipse CycloneDDS are expressed in XML and grouped together in a +single XML file. To use a custom XML configuration in an application, the ``CYCLONEDDS_URI`` +environment variable needs to be set prior to starting the application and pointed to the location +of the configuration file to be used. | *Example* | **Windows:** ``set CYCLONEDDS_URI=file://%USERPROFILE%/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. -You update existing configuration files or create your own by using the CycloneDDS Configurator tool, -which provides context-sensitive help on available configuration parameters and their applicability. +The Eclipse CycloneDDS installation comes with a configuration file that corresponds to the default +behaviour. You can modify it or add your using any text or XML editor, or using by using the +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 -by entering the tools directory and running ``java -jar cycloneddsconf.jar``. The default location of the tools -directory is ``/usr/share/CycloneDDS/tools`` on Linux or ``C:\Program Files\ADLINK\Vortex DDS\share\CycloneDDS\tools`` -on Windows. +One very important part of the configuration settings are the "tracing" settings: these allow +letting Eclipse Cyclone DDS trace very detailed information to a file, and this includes the actual +configuration settings in use, including all those that are set at the default. When editing +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. diff --git a/src/examples/helloworld/readme.rst b/src/examples/helloworld/readme.rst index 7bb4954..80e24bf 100644 --- a/src/examples/helloworld/readme.rst +++ b/src/examples/helloworld/readme.rst @@ -16,7 +16,7 @@ Description *********** 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 ******