Merge remote-tracking branch 'origin/master' into iox-eclipse-iceoryx…

…#743-fix-docu-generation

CHANGELOG.md

@@ -1,8 +1,8 @@
 # Change Log
 
-## [v1.0.0](https://github.com/eclipse-iceoryx/iceoryx/tree/v1.0.0) (2021-04-30)
+## [v1.0.0](https://github.com/eclipse-iceoryx/iceoryx/tree/v1.0.0) (2021-04-15)
 
-[Full Changelog](https://github.com/eclipse-iceoryx/iceoryx/compare/v0.90.0...v1.0.0)
+[Full Changelog](https://github.com/eclipse-iceoryx/iceoryx/compare/v0.90.7...v1.0.0)
 
 Description:
 This is the first major release for Eclipse iceoryx. That means it is the first release with long-term support and the adopters of iceoryx can rely on a stable API. The release called Almond allows for true zero-copy inter-process-communication on Linux, QNX and MacOS and provides C and modern C++ user APIs. This release is supported until 2022-04-01.

VERSION

@@ -1 +1 @@
-0.99.7
+1.0.0

cmake/package/package.cmake

@@ -14,7 +14,7 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 cmake_minimum_required(VERSION 3.5)
-set(IOX_VERSION_STRING "0.99.7")
+set(IOX_VERSION_STRING "1.0.0")
 
 project(iceoryx_package VERSION ${IOX_VERSION_STRING})
 

doc/aspice_swe3_4/CMakeLists.txt

@@ -16,7 +16,7 @@
 
 cmake_minimum_required(VERSION 3.10)
 
-set(IOX_VERSION_STRING "0.99.7")
+set(IOX_VERSION_STRING "1.0.0")
 
 #find_package(iceoryx_utils REQUIRED)
 

doc/design/chunk_header.md

@@ -45,7 +45,8 @@ class ChunkHeader
 {
     uint32_t chunkSize;
     uint8_t chunkHeaderVersion;
-    uint8_t reserved[3];
+    uint8_t reserved{0};
+    uint16_t userHeaderId;
     uint64_t originId;
     uint64_t sequenceNumber;
     uint32_t userHeaderSize{0U};
@@ -57,7 +58,8 @@ class ChunkHeader
 
 - **chunkSize** is the size of the whole chunk
 - **chunkHeaderVersion** is used to detect incompatibilities for record&replay functionality
-- **reserved[3]** is currently not used and set to `0`
+- **reserved** is currently not used and set to `0`
+- **userHeaderId** is currently not used and set to `NO_USER_HEADER`
 - **originId** is the unique identifier of the publisher the chunk was sent from
 - **sequenceNumber** is a serial number for the sent chunks
 - **userPayloadSize** is the size of the chunk occupied by the user-header
@@ -247,33 +249,7 @@ Furthermore, the `Publisher` and `Subscriber` have access to the `ChunkHeader` a
 
 ## Open Issues
 
-- the design was done with the intention to have a user-header of arbitrary size, if the size is limited to e.g. 32 bytes, some things could be simplified
-- publisher/subscriber API proposal
-```
-// publisher
-auto pub = iox::popo::Publisher<MyPayload, MyUserHeader>(serviceDescription);
-pub.loan()
-    .and_then([&](auto& sample) {
-        sample.getHeader()->userHeader<MyUserHeader>()->data = 42;
-        sample->a = 42;
-        sample->b = 13;
-        sample.publish();
-    })
-    .or_else([](iox::popo::AllocationError) {
-        // Do something with error.
-    });
-
-// subscriber
-auto sub = iox::popo::Subscriber<MyPayload, MyUserHeader>(serviceDescription);
-sub->take()
-    .and_then([](auto& sample){
-        std::cout << "User-Header data: " << sample.getHeader()->userHeader<MyUserHeader>()->data << std::endl;
-        std::cout << "User-Payload data: " << static_cast<const MyPayload*>(sample->get())->data << std::endl;
-    });
-```
-    - the publisher/subscriber would have a default parameter for the user-header to be source compatible with our current API
-    - the drawback is that the user could use the wrong user-header. Maybe `Sample` also needs an additional template parameter
-    - additionally, a `ChunkHeaderHook` could be used on the publisher side
+- a `ChunkHeaderHook` could be used on the publisher side
 ```
 template <typename UserHeader>
 class MyChunkHeaderHook : public ChunkHeaderHook
@@ -290,43 +266,6 @@ auto pub = iox::popo::Publisher<MyPayload>(serviceDescription, userHeaderHook);
 ```
         - alternatively, instead of the ChunkHeaderHook class, the publisher could have a method `registerDeliveryHook(std::function<void(ChunkHeader&)>)`
         - allow the user only read access to the `ChunkHeader` and write access to the `UserHeader`
-- untyped publisher/subscriber API proposal
-```
-// publisher option 1
-auto pub = iox::popo::UntypedPublisher<MyUserHeader>(serviceDescription);
-
-// publisher option 2
-auto userHeaderSize = sizeOf(MyUserHeader);
-auto pub = iox::popo::UntypedPublisher(serviceDescription, userHeaderSize);
-
-auto payloadSize = sizeof(MyPayload);
-auto payloadAlignment = alignof(MyPayload);
-pub.loan(payloadSize, payloadAlignment)
-    .and_then([&](auto& sample) {
-        sample.getHeader()->userHeader<MyUserHeader>()->data = 42;
-        auto payload = new (sample.get()) MyPayload();
-        payload->data = 73;
-        sample.publish();
-    })
-    .or_else([](iox::popo::AllocationError) {
-        // Do something with error.
-    });
-
-// subscriber option 1
-auto pub = iox::popo::UntypedPublisher<MyUserHeader>(serviceDescription);
-
-// subscriber option 2
-auto userHeaderSize = sizeOf(MyUserHeader);
-auto pub = iox::popo::UntypedSubscriber(serviceDescription, userHeaderSize);
-sub->take()
-    .and_then([](auto& sample){
-        std::cout << "User-Header data: " << sample.getHeader()->userHeader<MyUserHeader>()->data << std::endl;
-        std::cout << "User-Payload data: " << static_cast<const MyPayload*>(sample->get())->data << std::endl;
-    });
-```
-    - option 1 has the benefit to catch a wrong alignment of the user-header and would be necessary if we make the `Sample` aware of the user-header
-- C bindings
-    - PoC is needed
 - user defined sequence number
     - this can probably be done by a `ChunkHeaderHook`
     - alternatively, a flag could be introduce into the `ChunkHeader`

doc/website/getting-started/what-is-iceoryx.md

@@ -1 +1,64 @@
 # What is Eclipse iceoryx?
+
+The technology behind Eclipse iceoryx originated in the automotive domain. With the introduction of video-based driver
+assistance, the amount of data to be exchanged between different threads of execution increased to GBytes/sec. The
+resources on these embedded systems were constrained and a solution was needed to use precious runtime for functional
+computations, not for shifting around bytes in memory.
+
+The simple answer was to avoid copying of messages inside the middleware that manages the data communication between
+the different software nodes. This can be done by using shared memory that can be accessed by the producers and
+consumers of messages. On its own, this is not a new innovation as the approach has been used since the 1970s.
+However, iceoryx takes the approach further, ending up in an inter-process-communication technology with a
+publish/subscribe architecture that is fast, flexible and dependable.
+
+
+## Fast
+
+With the iceoryx API, a publisher can write the message directly into a chunk of memory that was previously requested
+from the middleware. When the message is delivered, subscribers receive reference counted pointers to these memory
+chunks, which are stored in queues with configurable capacities. With this iceoryx achieves what we refer to as true
+zero-copy — an end-to-end approach from publishers to subscribers without creating a single copy.
+
+Avoiding the copies on API level is crucial when GBytes of sensor data have to be processed per second on robotics and
+autonomous driving systems. Therefore the iceoryx team contributed to the standardization of true zero-copy capable
+APIs in [ROS 2](https://www.ros.org/) and [AUTOSAR Adaptive](https://www.autosar.org/standards/adaptive-platform/). 
+
+On modern processors iceoryx has a latency of less than 1 µs for transferring a message. And the best message is that
+this latency is constant as size doesn't matter. Want to give it a try? Then have a look at our
+[iceperf example](../examples/iceperf) after having made the first steps. 
+
+## Flexible
+
+iceoryx already supports Linux, QNX and MacOS as operating systems as well as C and C++ as user APIs. Windows and Rust
+are the next ones on the list. The typed C++ API is the most comfortable when you want to directly use the iceoryx API
+on the user side. The untyped C++ API and the C API provide a data agnostic interface that is often preferred when
+integrating iceoryx as shared memory backbone into a bigger framework.
+
+The APIs support polling access and event-driven interactions with the [Waitset](../overview/#waitset) and
+[Listener](../overview/#listener). Applications can be started and stopped flexibly as there is a service discovery
+behind the scenes that dynamically connects matching communication entities. 
+
+That iceoryx has the right set of features can be seen from the already existing integrations in middleware and
+frameworks such as [Eclipse Cyclone DDS](https://github.com/eclipse-cyclonedds/cyclonedds),
+ [eCAL from Continental](https://continental.github.io/ecal/),
+ [RTA-VRTE from ETAS](https://www.etas.com/en/products/rta-vrte.php) and
+ [Apex.OS from Apex.AI](https://www.apex.ai/apex-os).  
+
+## Dependable
+
+The predecessor of iceoryx is running in millions of vehicles worldwide. All iceoryx maintainers hail from the
+safety critical automotive domain. Hence, they know the necessary requirements and have these in mind for the
+design and implementation of features. The usage of heap, exceptions and any undefined behavior are to be avoided
+to increase the predictability. Instead a custom memory allocation is being used, based on static memory pools.
+Additionally, the handling of return values and error cases was inspired by upcoming C++ features and other
+languages like Rust (details can be found
+[here](../../advanced/how-optional-and-error-values-are-returned-in-iceoryx/)).
+
+As different processes are operating on shared data structures, avoiding deadlocks is becoming all the more important.
+iceoryx uses look-free data structures like the multi-producer multi-consumer (MPMC) queue that was written portably
+thanks to modern C++.  
+
+The tools available for automotive-compliant software development are always one or two releases behind the latest C++
+standard. This fact, combined with our already mentioned constraints, led to a bunch of STL like C++ classes that have
+the goal to combine modern C++ with the reliability needed for the domains iceoryx is used in. They can be found in
+the iceoryx utils which are introduced [here](../../advanced/iceoryx_utils/)

doc/website/index.md

@@ -8,9 +8,9 @@ title: Home
         width="50%">
 </p>
 
-Eclipse iceoryx™ is a true zero-copy inter-process communication that allows virtually limitless data transfer at constant time.
+Eclipse iceoryx™ is an inter-process-communication midddleware that enables virtually limitless data transmissions at constant time.
 
-| <h2>:octicons-stopwatch-16: Easy</h2> | <h2>:material-shield-half-full: Safe</h2> | <h2>:material-truck-fast: Fast</h2> |
+| <h2>:material-truck-fast: Fast</h2> | <h2>::material-puzzle: Flexible</h2> | <h2>:material-shield-half-full: Dependable</h2> |
 |----|----|-----|
-|<ul><li>Simple publish-subscribe API with service discovery</li><li>Straightforward usage for ROS2 and Adaptive AUTOSAR</li><li>Runs on QNX, Linux, MacOS and Windows</li></ul>|<ul><li>Automotive-grade (ISO26262 certification ongoing)</li><li>Lock-free algorithms prevent deadlocks</li><li>Huge library with safe STL implementations</li></ul>|<ul><li>Written in C++14</li><li>C binding available</li><li>Zero-copy data transmission with shared memory</li><li>Ultra low latency</li></ul>|
-|[Learn more](getting-started/what-is-iceoryx.md#easy){ .md-button }|[Learn more ](getting-started/what-is-iceoryx.md#safe){ .md-button }|[Learn more](getting-started/what-is-iceoryx.md#fast){ .md-button }|
+|<ul><li>True zero-copy shared memory communication</li><li>Message transfers with a latency of less than 1 µs</li><li>Made to handle GBytes/sec data transfers</li></ul>|<ul><li>Support of various operating systems, communication patterns and APIs</li><li>Service discovery enables the design of dynamic systems</li><li>Easy to integrate into frameworks like ROS 2 or AUTOSAR Adaptive</li></ul>|<ul><li>Developed according to automotive requirements</li><li>Implementation based on static memory and lock-free algorithms</li><li>Huge C++ library with safe STL implementations</li></ul>|
+|[Learn more](getting-started/what-is-iceoryx.md#fast){ .md-button }|[Learn more ](getting-started/what-is-iceoryx.md#flexible){ .md-button }|[Learn more](getting-started/what-is-iceoryx.md#dependable){ .md-button }|

iceoryx_binding_c/CMakeLists.txt

@@ -16,7 +16,7 @@
 # SPDX-License-Identifier: Apache-2.0
 cmake_minimum_required(VERSION 3.7)
 
-set(IOX_VERSION_STRING "0.99.7")
+set(IOX_VERSION_STRING "1.0.0")
 
 
 

iceoryx_binding_c/package.xml

@@ -2,7 +2,7 @@
 <?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
 <package format="3">
     <name>iceoryx_binding_c</name>
-    <version>0.99.7</version>
+    <version>1.0.0</version>
     <description>Eclipse iceoryx inter-process-communication (IPC) middleware C-Language Binding</description>
     <maintainer email="[email protected]">Eclipse Foundation, Inc.</maintainer>
     <license>Apache 2.0</license>

iceoryx_dds/CMakeLists.txt

@@ -16,7 +16,7 @@
 # SPDX-License-Identifier: Apache-2.0
 cmake_minimum_required(VERSION 3.7)
 
-set(IOX_VERSION_STRING "0.99.7")
+set(IOX_VERSION_STRING "1.0.0")
 
 project(iceoryx_dds VERSION ${IOX_VERSION_STRING})
 
@@ -90,6 +90,7 @@ if(USE_CYCLONE_DDS)
         source/iceoryx_dds/dds/cyclone_context.cpp
         source/iceoryx_dds/dds/cyclone_data_reader.cpp
         source/iceoryx_dds/dds/cyclone_data_writer.cpp
+        source/iceoryx_dds/dds/iox_chunk_datagram_header.cpp
     )
 
     # Generate IDL at configure time

iceoryx_dds/include/iceoryx_dds/dds/cyclone_data_reader.hpp

@@ -1,4 +1,5 @@
 // Copyright (c) 2020 by Robert Bosch GmbH. All rights reserved.
+// Copyright (c) 2021 by Apex.AI Inc. All rights reserved.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -46,12 +47,11 @@ class CycloneDataReader : public DataReader
 
     void connect() noexcept override;
 
-    iox::cxx::optional<uint32_t> peekNextSize() override;
-    bool hasSamples() override;
-    iox::cxx::expected<DataReaderError> takeNext(uint8_t* const buffer, const uint64_t& bufferSize) override;
-
-    iox::cxx::expected<uint64_t, DataReaderError>
-    take(uint8_t* const buffer, const uint64_t& bufferSize, const iox::cxx::optional<uint64_t>& maxSamples) override;
+    iox::cxx::optional<IoxChunkDatagramHeader> peekNextIoxChunkDatagramHeader() noexcept override;
+    bool hasSamples() noexcept override;
+    iox::cxx::expected<DataReaderError> takeNext(const IoxChunkDatagramHeader datagramHeader,
+                                                 uint8_t* const userHeaderBuffer,
+                                                 uint8_t* const userPayloadBuffer) noexcept override;
 
     capro::IdString_t getServiceId() const noexcept override;
     capro::IdString_t getInstanceId() const noexcept override;

iceoryx_dds/include/iceoryx_dds/dds/cyclone_data_writer.hpp

@@ -1,4 +1,5 @@
 // Copyright (c) 2020 by Robert Bosch GmbH. All rights reserved.
+// Copyright (c) 2021 by Apex.AI Inc. All rights reserved.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -44,7 +45,9 @@ class CycloneDataWriter : public iox::dds::DataWriter
     CycloneDataWriter& operator=(CycloneDataWriter&&) = default;
 
     void connect() noexcept override;
-    void write(const uint8_t* const bytes, const uint64_t size) noexcept override;
+    void write(iox::dds::IoxChunkDatagramHeader datagramHeader,
+               const uint8_t* const userHeaderBytes,
+               const uint8_t* const userPayloadBytes) noexcept override;
     capro::IdString_t getServiceId() const noexcept override;
     capro::IdString_t getInstanceId() const noexcept override;
     capro::IdString_t getEventId() const noexcept override;

iceoryx_dds/include/iceoryx_dds/dds/data_reader.hpp

@@ -18,6 +18,7 @@
 #ifndef IOX_DDS_DDS_DATA_READER_HPP
 #define IOX_DDS_DDS_DATA_READER_HPP
 
+#include "iceoryx_dds/dds/iox_chunk_datagram_header.hpp"
 #include "iceoryx_posh/iceoryx_posh_types.hpp"
 #include "iceoryx_utils/cxx/expected.hpp"
 #include "iceoryx_utils/cxx/optional.hpp"
@@ -30,13 +31,20 @@ enum class DataReaderError : uint8_t
 {
     INVALID_STATE,
     NOT_CONNECTED,
-    INVALID_RECV_BUFFER,
+    INVALID_DATAGRAM_HEADER_SIZE,
+    INVALID_BUFFER_PARAMETER_FOR_USER_HEADER,
+    INVALID_BUFFER_PARAMETER_FOR_USER_PAYLOAD,
     INVALID_DATA,
-    RECV_BUFFER_TOO_SMALL
+    BUFFER_SIZE_MISMATCH
 };
 
-constexpr char DataReaderErrorString[][64] = {
-    "NOT_CONNECTED", "INVALID_RECV_BUFFER", "INVALID_DATA", "RECV_BUFFER_TOO_SMALL"};
+constexpr const char* DataReaderErrorString[] = {"INVALID_STATE",
+                                                 "NOT_CONNECTED",
+                                                 "INVALID_DATAGRAM_HEADER_SIZE",
+                                                 "INVALID_BUFFER_PARAMETER_FOR_USER_HEADER",
+                                                 "INVALID_BUFFER_PARAMETER_FOR_USER_PAYLOAD",
+                                                 "INVALID_DATA",
+                                                 "BUFFER_SIZE_MISMATCH"};
 
 class DataReader
 {
@@ -47,37 +55,27 @@ class DataReader
     virtual void connect() noexcept = 0;
 
     ///
-    /// @brief peekNextSize Get the size of the next sample if one is available.
-    /// @return The size of the next sample if one is available.
+    /// @brief peekNextIoxChunkDatagramHeader Get the IoxChunkDatagramHeader of the next sample if one is available.
+    /// @return The IoxChunkDatagramHeader of the next sample if one is available.
     ///
-    virtual iox::cxx::optional<uint32_t> peekNextSize() = 0;
+    virtual iox::cxx::optional<IoxChunkDatagramHeader> peekNextIoxChunkDatagramHeader() noexcept = 0;
 
     ///
     /// @brief hasSamples Checks if new samples ready to take.
     /// @return True if new samples available.
     ///
-    virtual bool hasSamples() = 0;
+    virtual bool hasSamples() noexcept = 0;
 
     ///
     /// @brief take Take the next available sample from the DDS data space.
-    /// @param buffer Receive buffer in which sample will be stored.
-    /// @param bufferSize Size of the provided buffer.
+    /// @param datagramHeader with size information
+    /// @param userHeaderBuffer buffer for the user-header
+    /// @param userPayloadBuffer buffer for the user-payload
     /// @return Error if unsuccessful.
     ///
-    virtual iox::cxx::expected<DataReaderError> takeNext(uint8_t* const buffer, const uint64_t& bufferSize) = 0;
-
-
-    ///
-    /// @brief take Take up to a maximum number of samples from the DDS data space.
-    /// @param buffer Receive buffer in which samples will be stored.
-    /// @param bufferSize The size of the buffer (in bytes).
-    /// @param maxSamples The maximum number of samples to request from the network.
-    /// @return Number of samples taken if successful. Number of samples will be in the sange [0,maxSamples].
-    ///
-    /// @note Sample size must be known ahead of time & can be checked using @ref peekNextSize() .
-    ///
-    virtual iox::cxx::expected<uint64_t, DataReaderError>
-    take(uint8_t* const buffer, const uint64_t& bufferSize, const iox::cxx::optional<uint64_t>& maxSamples) = 0;
+    virtual iox::cxx::expected<DataReaderError> takeNext(const IoxChunkDatagramHeader datagramHeader,
+                                                         uint8_t* const userHeaderBuffer,
+                                                         uint8_t* const userPayloadBuffer) noexcept = 0;
 
     ///
     /// @brief getServiceId
@@ -98,7 +96,7 @@ class DataReader
     virtual capro::IdString_t getEventId() const noexcept = 0;
 
   protected:
-    DataReader() = default;
+    DataReader() noexcept = default;
 };
 } // namespace dds
 } // namespace iox