[eclipse-iceoryx#264] Add C/C++ config docu

iceoryx2-ffi/cxx/include/iox2/config.hpp

@@ -16,6 +16,7 @@
 #include "iox/duration.hpp"
 #include "iox/file_name.hpp"
 #include "iox/path.hpp"
+#include "iox2/config_creation_error.hpp"
 #include "iox2/internal/iceoryx2.hpp"
 #include "iox2/unable_to_deliver_strategy.hpp"
 
@@ -25,19 +26,36 @@ class Config;
 namespace config {
 class Global;
 
+/// All configurable settings of a [`Node`].
 class Node {
   public:
+    /// The directory in which all node files are stored
     auto directory() && -> const char*;
+    /// Set the directory in which all node files are stored
     void set_directory(const iox::Path& value) &&;
+    /// The suffix of the monitor token
     auto monitor_suffix() && -> const char*;
+    /// Set the suffix of the monitor token
     void set_monitor_suffix(const iox::FileName& value) &&;
+    /// The suffix of the files where the node configuration is stored.
     auto static_config_suffix() && -> const char*;
+    /// Set the suffix of the files where the node configuration is stored.
     void set_static_config_suffix(const iox::FileName& value) &&;
+    /// The suffix of the service tags.
     auto service_tag_suffix() && -> const char*;
+    /// Set the suffix of the service tags.
     void set_service_tag_suffix(const iox::FileName& value) &&;
+    /// When true, the [`NodeBuilder`](NodeBuilder) checks for dead nodes and
+    /// cleans up all their stale resources whenever a new [`Node`](Node) is
+    /// created.
     auto cleanup_dead_nodes_on_creation() && -> bool;
+    /// Enable/disable the cleanup dead nodes on creation
     void set_cleanup_dead_nodes_on_creation(bool value) &&;
+    /// When true, the [`NodeBuilder`](NodeBuilder) checks for dead nodes and
+    /// cleans up all their stale resources whenever an existing [`Node`](Node) is
+    /// going out of scope.
     auto cleanup_dead_nodes_on_destruction() && -> bool;
+    /// Enable/disable the cleanup dead nodes on destruction
     void set_cleanup_dead_nodes_on_destruction(bool value) &&;
 
   private:
@@ -47,21 +65,37 @@ class Node {
     iox2_config_h* m_config;
 };
 
+/// All configurable settings of a [`Service`].
 class Service {
   public:
+    /// The directory in which all service files are stored
     auto directory() && -> const char*;
+    /// Set the directory in which all service files are stored
     void set_directory(const iox::Path& value) &&;
+    /// The suffix of the publishers data segment
     auto publisher_data_segment_suffix() && -> const char*;
+    /// Set the suffix of the publishers data segment
     void set_publisher_data_segment_suffix(const iox::FileName& value) &&;
+    /// The suffix of the static config file
     auto static_config_storage_suffix() && -> const char*;
+    /// Set the suffix of the static config file
     void set_static_config_storage_suffix(const iox::FileName& value) &&;
+    /// The suffix of the dynamic config file
     auto dynamic_config_storage_suffix() && -> const char*;
+    /// Set the suffix of the dynamic config file
     void set_dynamic_config_storage_suffix(const iox::FileName& value) &&;
+    /// Defines the time of how long another process will wait until the service creation is
+    /// finalized
     auto creation_timeout() && -> iox::units::Duration;
+    /// Set the creation timeout
     void set_creation_timeout(const iox::units::Duration& value) &&;
+    /// The suffix of a one-to-one connection
     auto connection_suffix() && -> const char*;
+    /// Set the suffix of a one-to-one connection
     void set_connection_suffix(const iox::FileName& value) &&;
+    /// The suffix of a one-to-one connection
     auto event_connection_suffix() && -> const char*;
+    /// Set the suffix of a one-to-one connection
     void set_event_connection_suffix(const iox::FileName& value) &&;
 
   private:
@@ -71,14 +105,22 @@ class Service {
     iox2_config_h* m_config;
 };
 
+/// The global settings
 class Global {
   public:
+    /// Prefix used for all files created during runtime
     auto prefix() && -> const char*;
+    /// Set the prefix used for all files created during runtime
     void set_prefix(const iox::FileName& value) &&;
+    /// The path under which all other directories or files will be created
     auto root_path() && -> const char*;
+    /// Defines the path under which all other directories or files will be created
     void set_root_path(const iox::Path& value) &&;
 
+    /// Returns the service part of the global configuration
     auto service() -> Service;
+
+    /// Returns the node part of the global configuration
     auto node() -> Node;
 
   private:
@@ -88,27 +130,57 @@ class Global {
     iox2_config_h* m_config;
 };
 
+/// Default settings for the publish-subscribe messaging pattern. These settings are used unless
+/// the user specifies custom QoS or port settings.
 class PublishSubscribe {
   public:
+    /// The maximum amount of supported [`Subscriber`]s
     auto max_subscribers() && -> size_t;
+    /// Set the maximum amount of supported [`Subscriber`]s
     void set_max_subscribers(size_t value) &&;
+    /// The maximum amount of supported [`Publisher`]s
     auto max_publishers() && -> size_t;
+    /// Set the maximum amount of supported [`Publisher`]s
     void set_max_publishers(size_t value) &&;
+    /// The maximum amount of supported [`Node`]s. Defines indirectly how many
+    /// processes can open the service at the same time.
     auto max_nodes() && -> size_t;
+    /// Set the maximum amount of supported [`Node`]s.
     void set_max_nodes(size_t value) &&;
+    /// The maximum buffer size a [`Subscriber`] can have
     auto subscriber_max_buffer_size() && -> size_t;
+    /// Set the maximum buffer size a [`Subscriber`] can have
     void set_subscriber_max_buffer_size(size_t value) &&;
+    /// The maximum amount of [`Sample`]s a [`Subscriber`] can hold at the same time.
     auto subscriber_max_borrowed_samples() && -> size_t;
+    /// Set the maximum amount of [`Sample`]s a [`Subscriber`] can hold at the same time.
     void set_subscriber_max_borrowed_samples(size_t value) &&;
+    /// The maximum amount of [`SampleMut`]s a [`Publisher`] can loan at the same time.
     auto publisher_max_loaned_samples() && -> size_t;
+    /// The maximum amount of [`SampleMut`]s a [`Publisher`] can loan at the same time.
     void set_publisher_max_loaned_samples(size_t value) &&;
+    /// The maximum history size a [`Subscriber`] can request from a [`Publisher`].
     auto publisher_history_size() && -> size_t;
+    /// Set the maximum history size a [`Subscriber`] can request from a [`Publisher`].
     void set_publisher_history_size(size_t value) &&;
+    /// Defines how the [`Subscriber`] buffer behaves when it is
+    /// full. When safe overflow is activated, the [`Publisher`] will
+    /// replace the oldest [`Sample`] with the newest one.
     auto enable_safe_overflow() && -> bool;
+    /// Enables/disables safe overflow
     void set_enable_safe_overflow(bool value) &&;
+    /// If safe overflow is deactivated it defines the deliver strategy of the
+    /// [`Publisher`] when the [`Subscriber`]s buffer is full.
     auto unable_to_deliver_strategy() && -> UnableToDeliverStrategy;
+    /// Define the unable to deliver strategy
     void set_unable_to_deliver_strategy(UnableToDeliverStrategy value) &&;
+    /// Defines the size of the internal [`Subscriber`]
+    /// buffer that contains expired connections. An
+    /// connection is expired when the [`Publisher`]
+    /// disconnected from a service and the connection
+    /// still contains unconsumed [`Sample`]s.
     auto subscriber_expired_connection_buffer() && -> size_t;
+    /// Set the expired connection buffer size
     void set_subscriber_expired_connection_buffer(size_t value) &&;
 
   private:
@@ -118,15 +190,26 @@ class PublishSubscribe {
     iox2_config_h* m_config;
 };
 
+/// Default settings for the event messaging pattern. These settings are used unless
+/// the user specifies custom QoS or port settings.
 class Event {
   public:
+    /// The maximum amount of supported [`Listener`]
     auto max_listeners() && -> size_t;
+    /// Set the maximum amount of supported [`Listener`]
     void set_max_listeners(size_t value) &&;
+    /// The maximum amount of supported [`Notifier`]
     auto max_notifiers() && -> size_t;
+    /// Set the maximum amount of supported [`Notifier`]
     void set_max_notifiers(size_t value) &&;
+    /// The maximum amount of supported [`Node`]s. Defines indirectly how many
+    /// processes can open the service at the same time.
     auto max_nodes() && -> size_t;
+    /// Set the maximum amount of supported [`Node`]s.
     void set_max_nodes(size_t value) &&;
+    /// The largest event id supported by the event service
     auto event_id_max_value() && -> size_t;
+    /// Set the largest event id supported by the event service
     void set_event_id_max_value(size_t value) &&;
 
   private:
@@ -136,9 +219,13 @@ class Event {
     iox2_config_h* m_config;
 };
 
+/// Default settings. These values are used when the user in the code does not specify anything
+/// else.
 class Defaults {
   public:
+    /// Returns the publish_subscribe part of the default settings
     auto publish_subscribe() && -> PublishSubscribe;
+    /// Returns the event part of the default settings
     auto event() && -> Event;
 
   private:
@@ -173,6 +260,10 @@ class ConfigView {
     iox2_config_ptr m_ptr;
 };
 
+/// Represents the configuration that iceoryx2 will utilize. It is divided into two sections:
+/// the [Global] settings, which must align with the iceoryx2 instance the application intends to
+/// join, and the [Defaults] for communication within that iceoryx2 instance. The user has the
+/// flexibility to override both sections.
 class Config {
   public:
     Config();
@@ -183,7 +274,13 @@ class Config {
     auto operator=(const Config& rhs) -> Config&;
     auto operator=(Config&& rhs) noexcept -> Config&;
 
+    /// Loads a configuration from a file. On success it returns a [`Config`] object otherwise a
+    /// [`ConfigCreationError`] describing the failure.
+    static auto from_file(const iox::FilePath& file) -> iox::expected<Config, ConfigCreationError>;
+
+    /// Returns the [`config::Global`] part of the config
     auto global() -> config::Global;
+    /// Returns the [`config::Defaults`] part of the config
     auto defaults() -> config::Defaults;
 
     /// Returns a [`ConfigView`] to the current global config.

iceoryx2-ffi/cxx/include/iox2/config_creation_error.hpp

@@ -0,0 +1,28 @@
+// Copyright (c) 2024 Contributors to the Eclipse Foundation
+//
+// See the NOTICE file(s) distributed with this work for additional
+// information regarding copyright ownership.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Apache Software License 2.0 which is available at
+// https://www.apache.org/licenses/LICENSE-2.0, or the MIT license
+// which is available at https://opensource.org/licenses/MIT.
+//
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+
+#ifndef IOX2_CONFIG_CREATION_ERROR_HPP
+#define IOX2_CONFIG_CREATION_ERROR_HPP
+
+namespace iox2 {
+/// Failures occurring while creating a new [`Config`] object with [`Config::from_file()`].
+enum class ConfigCreationError {
+    /// The config file could not be opened.
+    FailedToOpenConfigFile,
+    /// The config file could not be read.
+    FailedToReadConfigFileContents,
+    /// Parts of the config file could not be deserialized. Indicates some kind of syntax error.
+    UnableToDeserializeContents
+};
+} // namespace iox2
+
+#endif

iceoryx2-ffi/cxx/include/iox2/enum_translation.hpp

@@ -16,6 +16,7 @@
 #include "iox/assertions.hpp"
 #include "iox/into.hpp"
 #include "iox2/callback_progression.hpp"
+#include "iox2/config_creation_error.hpp"
 #include "iox2/connection_failure.hpp"
 #include "iox2/iceoryx2.h"
 #include "iox2/listener_error.hpp"
@@ -623,6 +624,24 @@ constexpr auto from<int, iox2::ConnectionFailure>(const int value) noexcept -> i
 
     IOX_UNREACHABLE();
 }
+
+template <>
+constexpr auto from<int, iox2::ConfigCreationError>(const int value) noexcept -> iox2::ConfigCreationError {
+    const auto variant = static_cast<iox2_config_creation_error_e>(value);
+    switch (variant) {
+    case iox2_config_creation_error_e_FAILED_TO_OPEN_CONFIG_FILE:
+        return iox2::ConfigCreationError::FailedToOpenConfigFile;
+    case iox2_config_creation_error_e_FAILED_TO_READ_CONFIG_FILE_CONTENTS:
+        return iox2::ConfigCreationError::FailedToReadConfigFileContents;
+    case iox2_config_creation_error_e_UNABLE_TO_DESERIALIZE_CONTENTS:
+        return iox2::ConfigCreationError::UnableToDeserializeContents;
+    case iox2_config_creation_error_e_INVALID_FILE_PATH:
+        // unreachable since this error case is excluded by using the strong type iox::FilePath
+        IOX_UNREACHABLE();
+    }
+
+    IOX_UNREACHABLE();
+}
 } // namespace iox
 
 #endif

iceoryx2-ffi/cxx/src/config.cpp

@@ -83,6 +83,16 @@ Config::Config(iox2_config_h handle)
     : m_handle { handle } {
 }
 
+auto Config::from_file(const iox::FilePath& file) -> iox::expected<Config, ConfigCreationError> {
+    iox2_config_h handle = nullptr;
+    auto result = iox2_config_from_file(nullptr, &handle, file.as_string().c_str());
+    if (result == IOX2_OK) {
+        return iox::ok(Config(handle));
+    }
+
+    return iox::err(iox::into<ConfigCreationError>(result));
+}
+
 auto Config::global() -> config::Global {
     return config::Global(&this->m_handle);
 }

iceoryx2-ffi/ffi/src/api/config.rs

@@ -147,12 +147,10 @@ pub unsafe extern "C" fn iox2_config_default(
 
 #[no_mangle]
 pub unsafe extern "C" fn iox2_config_from_file(
-    handle: iox2_config_ref_h,
     struct_ptr: *mut iox2_config_t,
     handle_ptr: *mut iox2_config_h,
     config_file: *const c_char,
 ) -> c_int {
-    debug_assert!(!handle.is_null());
     debug_assert!(!handle_ptr.is_null());
 
     let file = match FilePath::from_c_str(config_file) {

iceoryx2-ffi/ffi/src/api/quirks_correction.rs

@@ -16,9 +16,9 @@
 pub type c_size_t = usize;
 
 use crate::{
-    iox2_event_open_or_create_error_e, iox2_listener_create_error_e, iox2_listener_wait_error_e,
-    iox2_node_creation_failure_e, iox2_node_event_e, iox2_node_list_failure_e,
-    iox2_notifier_create_error_e, iox2_notifier_notify_error_e,
+    iox2_config_creation_error_e, iox2_event_open_or_create_error_e, iox2_listener_create_error_e,
+    iox2_listener_wait_error_e, iox2_node_creation_failure_e, iox2_node_event_e,
+    iox2_node_list_failure_e, iox2_notifier_create_error_e, iox2_notifier_notify_error_e,
     iox2_pub_sub_open_or_create_error_e, iox2_publisher_create_error_e,
     iox2_publisher_loan_error_e, iox2_publisher_send_error_e, iox2_semantic_string_error_e,
     iox2_service_details_error_e, iox2_service_list_error_e, iox2_subscriber_create_error_e,
@@ -172,3 +172,11 @@ pub unsafe extern "C" fn __iox2_internal_service_list_error_stub() -> iox2_servi
 pub unsafe extern "C" fn __iox2_internal_connection_failure_stub() -> iox2_connection_failure_e {
     iox2_connection_failure_e::FAILED_TO_ESTABLISH_CONNECTION
 }
+
+#[doc(hidden)]
+#[no_mangle]
+// TODO: enums are only exported when they are actually used by some function
+pub unsafe extern "C" fn __iox2_internal_config_creation_error_stub() -> iox2_config_creation_error_e
+{
+    iox2_config_creation_error_e::INVALID_FILE_PATH
+}

iceoryx2/src/config.rs

@@ -232,15 +232,15 @@ pub struct PublishSubscribe {
     /// The maximum amount of supported [`crate::port::publisher::Publisher`]
     pub max_publishers: usize,
     /// The maximum amount of supported [`crate::node::Node`]s. Defines indirectly how many
-    /// processes can open the service in parallel.
+    /// processes can open the service at the same time.
     pub max_nodes: usize,
     /// The maximum buffer size a [`crate::port::subscriber::Subscriber`] can have
     pub subscriber_max_buffer_size: usize,
     /// The maximum amount of [`crate::sample::Sample`]s a [`crate::port::subscriber::Subscriber`] can
-    /// hold in parallel.
+    /// hold at the same time.
     pub subscriber_max_borrowed_samples: usize,
     /// The maximum amount of [`crate::sample_mut::SampleMut`]s a [`crate::port::publisher::Publisher`] can
-    /// loan in parallel.
+    /// loan at the same time.
     pub publisher_max_loaned_samples: usize,
     /// The maximum history size a [`crate::port::subscriber::Subscriber`] can request from a
     /// [`crate::port::publisher::Publisher`].
@@ -249,7 +249,7 @@ pub struct PublishSubscribe {
     /// full. When safe overflow is activated, the [`crate::port::publisher::Publisher`] will
     /// replace the oldest [`crate::sample::Sample`] with the newest one.
     pub enable_safe_overflow: bool,
-    /// If no safe overflow is activated it defines the deliver strategy of the
+    /// If safe overflow is deactivated it defines the deliver strategy of the
     /// [`crate::port::publisher::Publisher`] when the [`crate::port::subscriber::Subscriber`]s
     /// buffer is full.
     pub unable_to_deliver_strategy: UnableToDeliverStrategy,
@@ -272,7 +272,7 @@ pub struct Event {
     /// The maximum amount of supported [`crate::port::notifier::Notifier`]
     pub max_notifiers: usize,
     /// The maximum amount of supported [`crate::node::Node`]s. Defines indirectly how many
-    /// processes can open the service in parallel.
+    /// processes can open the service at the same time.
     pub max_nodes: usize,
     /// The largest event id supported by the event service
     pub event_id_max_value: usize,