iox-eclipse-iceoryx#378 merge latest master

Signed-off-by: Dietrich Krönke <[email protected]>

doc/website/getting-started/examples/intermediate-examples.md

@@ -1,5 +1,6 @@
 # Intermediate examples
 
+{! ./../iceoryx_examples/callbacks/README.md !}
 {! ./../iceoryx_examples/waitset/README.md !}
 {! ./../iceoryx_examples/waitset_in_c/README.md !}
 {! ./../iceoryx_examples/singleprocess/README.md !}

doc/website/getting-started/installation.md

@@ -6,9 +6,10 @@ iceoryx_utils and iceoryx_posh are deployed as independent cmake packages. Posh
 
 ### Dependencies
 
+ - 64-bit hardware (e.g. x86_64 or aarch64; 32-bit hardware might work, but is not supported)
  - [cmake](https://cmake.org), 3.5 or later
  - One of the following compilers:
-   - [gcc](https://gcc.gnu.org), 7.4 or later 
+   - [gcc](https://gcc.gnu.org), 7.4 or later
    - [clang](https://clang.llvm.org), 9.0 or later
    - [msvc](https://visualstudio.microsoft.com/de/), part of Visual Studio 2019 or later
  - [libacl](http://download.savannah.gnu.org/releases/acl/), 2.2 or later. Only for Linux & QNX.

iceoryx_binding_c/CMakeLists.txt

@@ -1,4 +1,5 @@
-# Copyright (c) 2020 by Robert Bosch GmbH, Apex.AI Inc. All rights reserved.
+# Copyright (c) 2020 by Robert Bosch GmbH. All rights reserved.
+# Copyright (c) 2020 - 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.
@@ -53,6 +54,7 @@ add_library(${PROJECT_NAME}
     source/c_subscriber.cpp
     source/c_event_info.cpp
     source/c_wait_set.cpp
+    source/c_chunk.cpp
     source/cpp2c_enum_translation.cpp
     source/cpp2c_publisher.cpp
     source/cpp2c_subscriber.cpp
@@ -70,11 +72,22 @@ target_include_directories(${PROJECT_NAME}
     $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
     $<INSTALL_INTERFACE:include/${PREFIX}>
 )
-target_link_libraries(${PROJECT_NAME}
-    PRIVATE
-    iceoryx_posh::iceoryx_posh
-    iceoryx_utils::iceoryx_utils
-)
+
+if(NOT WIN32)
+    target_link_libraries(${PROJECT_NAME}
+      PUBLIC
+        pthread
+      PRIVATE
+        iceoryx_posh::iceoryx_posh
+        iceoryx_utils::iceoryx_utils
+    )
+else()
+    target_link_libraries(${PROJECT_NAME}
+      PRIVATE
+        iceoryx_posh::iceoryx_posh
+        iceoryx_utils::iceoryx_utils
+    )
+endif()
 
 target_compile_options(${PROJECT_NAME} PRIVATE ${ICEORYX_WARNINGS} ${ICEORYX_SANITIZER_FLAGS})
 

iceoryx_binding_c/include/iceoryx_binding_c/chunk.h

@@ -0,0 +1,35 @@
+// 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.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+#ifndef IOX_BINDING_C_CHUNK_H
+#define IOX_BINDING_C_CHUNK_H
+
+#include "iceoryx_binding_c/internal/c2cpp_binding.h"
+
+/// @brief handle of the chunk header
+typedef void* iox_chunk_header_t;
+
+/// @brief gets the payload from the chunk header
+/// @param[in] header pointer to the chunk header
+/// @return pointer to the payload
+void* iox_chunk_header_to_payload(iox_chunk_header_t const header);
+
+/// @brief gets the chunk header from the payload
+/// @param[in] payload pointer to the payload
+/// @return pointer to the chunk header
+iox_chunk_header_t iox_chunk_payload_to_header(const void* const payload);
+
+#endif

iceoryx_binding_c/include/iceoryx_binding_c/enums.h

@@ -1,4 +1,5 @@
-// Copyright (c) 2020 by Robert Bosch GmbH, Apex.AI Inc. All rights reserved.
+// Copyright (c) 2020 by Robert Bosch GmbH. All rights reserved.
+// Copyright (c) 2020 - 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.
@@ -38,7 +39,7 @@ enum iox_SubscribeState
 enum iox_ChunkReceiveResult
 {
     ChunkReceiveResult_TOO_MANY_CHUNKS_HELD_IN_PARALLEL,
-    ChunkReceiveResult_NO_CHUNK_RECEIVED,
+    ChunkReceiveResult_NO_CHUNK_AVAILABLE,
     ChunkReceiveResult_UNDEFINED_ERROR,
     ChunkReceiveResult_SUCCESS,
 };

iceoryx_binding_c/include/iceoryx_binding_c/publisher.h

@@ -1,4 +1,5 @@
-// Copyright (c) 2020, 2021 by Robert Bosch GmbH, Apex.AI Inc. All rights reserved.
+// Copyright (c) 2020 by Robert Bosch GmbH. All rights reserved.
+// Copyright (c) 2020 - 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.
@@ -24,20 +25,50 @@
 /// @brief publisher handle
 typedef struct cpp2c_Publisher* iox_pub_t;
 
+/// @brief options to be set for a publisher
+typedef struct
+{
+    // size of the history chunk queue
+    uint64_t historyCapacity;
+
+    // name of the node the publisher belongs to
+    // nullptr indicates that the default node name is used
+    const char* nodeName;
+
+    // The option whether the publisher should already be offered when creating it
+    bool offerOnCreate;
+
+    // this value will be set exclusively by iox_pub_options_init
+    // and is not supposed to be modified otherwise
+    uint64_t initCheck;
+} iox_pub_options_t;
+
+/// @brief initialize publisher options to default values
+/// @param[in] options pointer to options to be initialized,
+///                    emit warning if it is a null pointer
+/// @attention This must always be called on a newly created options struct to
+///            prevent uninitialized values. The options may get extended
+///            in the future.
+void iox_pub_options_init(iox_pub_options_t* options);
+
+/// @brief check whether the publisher options were initialized by iox_pub_options_init
+/// @param[in] options pointer to options to be checked
+/// @return true if options are not null and were initialized, false otherwise
+bool iox_pub_options_is_initialized(const iox_pub_options_t* const options);
+
 /// @brief creates a publisher handle
 /// @param[in] self pointer to preallocated memory of size = sizeof(iox_pub_storage_t)
 /// @param[in] service serviceString
 /// @param[in] instance instanceString
 /// @param[in] event eventString
-/// @param[in] historyCapacity size of the history chunk queue
-/// @param[in] nodeName name of the node the publisher belongs to
+/// @param[in] options publisher options set by the user,
+///                    if it is a null pointer default options are used
 /// @return handle of the publisher
 iox_pub_t iox_pub_init(iox_pub_storage_t* self,
                        const char* const service,
                        const char* const instance,
                        const char* const event,
-                       const uint64_t historyCapacity,
-                       const char* const nodeName);
+                       const iox_pub_options_t* const options);
 
 /// @brief removes a publisher handle
 /// @param[in] self the handle which should be removed
@@ -49,23 +80,23 @@ void iox_pub_deinit(iox_pub_t const self);
 /// @param[in] payloadSize size of the allocated chunk
 /// @return on success it returns AllocationResult_SUCCESS otherwise a value which
 ///         describes the error
-ENUM iox_AllocationResult iox_pub_allocate_chunk(iox_pub_t const self, void** const chunk, const uint32_t payloadSize);
+ENUM iox_AllocationResult iox_pub_loan_chunk(iox_pub_t const self, void** const chunk, const uint32_t payloadSize);
 
-/// @brief frees a previously allocated chunk without sending it
+/// @brief releases ownership of a previously allocated chunk without sending it
 /// @param[in] self handle of the publisher
 /// @param[in] chunk chunk which should be free'd
-void iox_pub_free_chunk(iox_pub_t const self, void* const chunk);
+void iox_pub_release_chunk(iox_pub_t const self, void* const chunk);
 
 /// @brief sends a previously allocated chunk
 /// @param[in] self handle of the publisher
 /// @param[in] chunk chunk which should be send
-void iox_pub_send_chunk(iox_pub_t const self, void* const chunk);
+void iox_pub_publish_chunk(iox_pub_t const self, void* const chunk);
 
 /// @brief returns the previously sended chunk
 /// @param[in] self handle of the publisher
 /// @return nullptr if no chunk was previously send otherwise a pointer to the
 ///           previous chunk
-const void* iox_pub_try_get_previous_chunk(iox_pub_t const self);
+const void* iox_pub_loan_previous_chunk(iox_pub_t const self);
 
 /// @brief offers the service
 /// @param[in] self handle of the publisher

iceoryx_binding_c/include/iceoryx_binding_c/subscriber.h

@@ -1,4 +1,5 @@
-// Copyright (c) 2020, 2021 by Robert Bosch GmbH, Apex.AI Inc. All rights reserved.
+// Copyright (c) 2020 by Robert Bosch GmbH. All rights reserved.
+// Copyright (c) 2020 - 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.
@@ -24,22 +25,53 @@
 /// @brief Subscriber handle
 typedef struct cpp2c_Subscriber* iox_sub_t;
 
+/// @brief options to be set for a subscriber
+typedef struct
+{
+    // size of the history chunk queue
+    uint64_t queueCapacity;
+
+    // number of chunks received after subscription if chunks are available
+    // nullptr indicates that the default node name is used
+    uint64_t historyRequest;
+
+    // name of the node the subscriber belongs to
+    const char* nodeName;
+
+    // The option whether the subscriber shall try to subscribe when creating it
+    bool subscribeOnCreate;
+
+    // this value will be set exclusively by iox_sub_options_init
+    // and is not supposed to be modified otherwise
+    uint64_t initCheck;
+} iox_sub_options_t;
+
+/// @brief initialize subscriber options to default values
+/// @param[in] options pointer to options to be initialized,
+///                    emit warning if it is a null pointer
+/// @attention This must always be called on a newly created options struct to
+///            prevent uninitialized values. The options may get extended
+///            in the future.
+void iox_sub_options_init(iox_sub_options_t* const options);
+
+/// @brief check whether the subscriber options were initialized by iox_sub_options_init
+/// @param[in] options pointer to options to be checked
+/// @return true if options are not null and were initialized, false otherwise
+bool iox_sub_options_is_initialized(const iox_sub_options_t* const options);
+
 /// @brief initialize subscriber handle
 /// @param[in] self pointer to preallocated memory of size = sizeof(iox_sub_storage_t)
 /// @param[in] service serviceString
 /// @param[in] instance instanceString
 /// @param[in] event eventString
-/// @param[in] queueCapacity size of the receiver queue
-/// @param[in] historyRequest of chunks received after subscription if chunks are available
-/// @param[in] nodeName name of node where the subscriber belongs to
+/// @param[in] options subscriber options set by the user,
+///                    if it is a null pointer default options are used
 /// @return handle of the subscriber
 iox_sub_t iox_sub_init(iox_sub_storage_t* self,
                        const char* const service,
                        const char* const instance,
                        const char* const event,
-                       const uint64_t queueCapacity,
-                       const uint64_t historyRequest,
-                       const char* const nodeName);
+                       const iox_sub_options_t* const options);
 
 /// @brief deinitialize a subscriber handle
 /// @param[in] self the handle which should be removed
@@ -64,7 +96,7 @@ ENUM iox_SubscribeState iox_sub_get_subscription_state(iox_sub_t const self);
 /// @param[in] chunk pointer in which the pointer to the chunk is stored
 /// @return if a chunk could be received it returns ChunkReceiveResult_SUCCESS otherwise
 ///         an enum which describes the error
-ENUM iox_ChunkReceiveResult iox_sub_get_chunk(iox_sub_t const self, const void** const chunk);
+ENUM iox_ChunkReceiveResult iox_sub_take_chunk(iox_sub_t const self, const void** const chunk);
 
 /// @brief release a previously acquired chunk (via iox_sub_getChunk)
 /// @param[in] self handle to the subscriber
@@ -77,12 +109,12 @@ void iox_sub_release_queued_chunks(iox_sub_t const self);
 
 /// @brief are new chunks available?
 /// @param[in] self handle to the subscriber
-/// @return true if there are chunks otherwise false
+/// @return true if there are chunks, otherwise false
 bool iox_sub_has_chunks(iox_sub_t const self);
 
 /// @brief are chunks lost?
 /// @param[in] self handle to the subscriber
-/// @return true if there are lost chunks otherwise false
+/// @return true if there are lost chunks due to overflowing queue, otherwise false
 bool iox_sub_has_lost_chunks(iox_sub_t const self);
 
 #endif

iceoryx_binding_c/include/iceoryx_binding_c/types.h

@@ -39,7 +39,7 @@ struct iox_user_trigger_storage_t_
     // the value of the array size is the result of the following formula:
     // sizeof(UserTrigger) / 8
 #if defined(__APPLE__)
-    uint64_t do_not_touch_me[16];
+    uint64_t do_not_touch_me[17];
 #else
     uint64_t do_not_touch_me[14];
 #endif
@@ -51,7 +51,7 @@ struct iox_sub_storage_t_
     // the value of the array size is the result of the following formula:
     // sizeof(cpp2c_Subscriber) / 8
 #if defined(__APPLE__)
-    uint64_t do_not_touch_me[16];
+    uint64_t do_not_touch_me[17];
 #else
     uint64_t do_not_touch_me[14];
 #endif

iceoryx_binding_c/source/c_chunk.cpp

@@ -0,0 +1,34 @@
+// 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.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+#include "iceoryx_posh/mepoo/chunk_header.hpp"
+
+
+extern "C" {
+#include "iceoryx_binding_c/chunk.h"
+}
+
+using namespace iox::mepoo;
+
+void* iox_chunk_header_to_payload(iox_chunk_header_t const header)
+{
+    return reinterpret_cast<ChunkHeader*>(header)->payload();
+}
+
+iox_chunk_header_t iox_chunk_payload_to_header(const void* const payload)
+{
+    return ChunkHeader::fromPayload(payload);
+}