diff --git a/iceoryx2-ffi/cxx/include/iox2/node_failure_enums.hpp b/iceoryx2-ffi/cxx/include/iox2/node_failure_enums.hpp index a27a994f4..f8d6ecf87 100644 --- a/iceoryx2-ffi/cxx/include/iox2/node_failure_enums.hpp +++ b/iceoryx2-ffi/cxx/include/iox2/node_failure_enums.hpp @@ -36,6 +36,8 @@ enum class NodeCreationFailure : uint8_t { InternalError }; +/// Failures of [`DeadNodeView::remove_stale_resources()`] that occur when the stale resources of +/// a dead [`Node`] are removed. enum class NodeCleanupFailure : uint8_t { /// The process received an interrupt signal while cleaning up all stale resources of a dead [`Node`]. Interrupt, diff --git a/iceoryx2-ffi/cxx/include/iox2/node_id.hpp b/iceoryx2-ffi/cxx/include/iox2/node_id.hpp index 2d78344c6..26f5e7271 100644 --- a/iceoryx2-ffi/cxx/include/iox2/node_id.hpp +++ b/iceoryx2-ffi/cxx/include/iox2/node_id.hpp @@ -21,6 +21,7 @@ #include namespace iox2 { +/// The system-wide unique id of a [`Node`] class NodeId { public: NodeId(const NodeId& rhs); @@ -29,10 +30,10 @@ class NodeId { auto operator=(NodeId&& rhs) noexcept -> NodeId&; ~NodeId(); - /// Returns high bits of the underlying value of the [`NodeId`]. + /// Returns the high bits of the underlying value of the [`NodeId`]. auto value_high() const -> uint64_t; - /// Returns low bits of the underlying value of the [`NodeId`]. + /// Returns the low bits of the underlying value of the [`NodeId`]. auto value_low() const -> uint64_t; /// Returns the [`ProcessId`] of the process that owns the [`Node`]. @@ -47,12 +48,9 @@ class NodeId { template friend class DeadNodeView; template - friend auto list_callback(iox2_node_state_e, - iox2_node_id_ptr, - const char*, - iox2_node_name_ptr, - iox2_config_ptr, - iox2_callback_context) -> iox2_callback_progression_e; + friend auto list_callback( + iox2_node_state_e, iox2_node_id_ptr, const char*, iox2_node_name_ptr, iox2_config_ptr, iox2_callback_context) + -> iox2_callback_progression_e; explicit NodeId(iox2_node_id_h handle); diff --git a/iceoryx2-ffi/cxx/include/iox2/node_state.hpp b/iceoryx2-ffi/cxx/include/iox2/node_state.hpp index 90124a08b..b1860add8 100644 --- a/iceoryx2-ffi/cxx/include/iox2/node_state.hpp +++ b/iceoryx2-ffi/cxx/include/iox2/node_state.hpp @@ -103,12 +103,9 @@ class NodeState { private: template // NOLINTBEGIN(readability-function-size) - friend auto list_callback(iox2_node_state_e, - iox2_node_id_ptr, - const char*, - iox2_node_name_ptr, - iox2_config_ptr, - iox2_callback_context) -> iox2_callback_progression_e; + friend auto list_callback( + iox2_node_state_e, iox2_node_id_ptr, const char*, iox2_node_name_ptr, iox2_config_ptr, iox2_callback_context) + -> iox2_callback_progression_e; explicit NodeState(const AliveNodeView& view); explicit NodeState(const DeadNodeView& view); diff --git a/iceoryx2-ffi/ffi/src/api/node.rs b/iceoryx2-ffi/ffi/src/api/node.rs index 0740261f0..48264c391 100644 --- a/iceoryx2-ffi/ffi/src/api/node.rs +++ b/iceoryx2-ffi/ffi/src/api/node.rs @@ -37,11 +37,15 @@ use super::{iox2_config_h_ref, iox2_node_id_h_ref, iox2_node_id_ptr, iox2_signal // BEGIN type definition +/// The failures that can occur when a list of node states is created with [`iox2_node_list()`]. #[repr(C)] #[derive(Copy, Clone, StringLiteral)] pub enum iox2_node_list_failure_e { + /// A list of all Nodes could not be created since the process does not have sufficient permissions. INSUFFICIENT_PERMISSIONS = IOX2_OK as isize + 1, + /// The process received an interrupt signal while acquiring the list of all Nodes. INTERRUPT, + /// Errors that indicate either an implementation issue or a wrongly configured system. INTERNAL_ERROR, } @@ -73,11 +77,16 @@ impl IntoCInt for NodeWaitFailure { } } +/// Failures of [`iox2_dead_node_remove_stale_resources()`] that occur when the stale resources of +/// a dead node are removed. #[repr(C)] #[derive(Copy, Clone, StringLiteral)] pub enum iox2_node_cleanup_failure_e { + /// The process received an interrupt signal while cleaning up all stale resources of a dead node. INTERRUPT = IOX2_OK as isize + 1, + /// Errors that indicate either an implementation issue or a wrongly configured system. INTERNAL_ERROR, + /// The stale resources of a dead node could not be removed since the process does not have sufficient permissions. INSUFFICIENT_PERMISSIONS, } @@ -348,6 +357,16 @@ pub unsafe extern "C" fn iox2_node_id( } } +/// Removes all stale resources of a dead node under a provided config. +/// +/// Returns [`IOX2_OK`] on success, otherwise [`iox2_node_cleanup_failure_e`]. +/// +/// # Safety +/// +/// * The `node_handle` must be valid and obtained by [`iox2_node_builder_create`](crate::iox2_node_builder_create)! +/// * The `node_id` must be valid +/// * The `config` must be valid +/// * `has_success` must point to a valid memory location #[no_mangle] pub unsafe extern "C" fn iox2_dead_node_remove_stale_resources( service_type: iox2_service_type_e, @@ -355,8 +374,12 @@ pub unsafe extern "C" fn iox2_dead_node_remove_stale_resources( config: iox2_config_h_ref, has_success: *mut bool, ) -> c_int { - let node_id = (&*node_id.as_type()).value.as_ref(); - let config = (&*config.as_type()).value.as_ref(); + node_id.assert_non_null(); + config.assert_non_null(); + debug_assert!(!has_success.is_null()); + + let node_id = (*node_id.as_type()).value.as_ref(); + let config = (*config.as_type()).value.as_ref(); let result = match service_type { iox2_service_type_e::IPC => { diff --git a/iceoryx2-ffi/ffi/src/api/node_id.rs b/iceoryx2-ffi/ffi/src/api/node_id.rs index db614e738..b89e6155d 100644 --- a/iceoryx2-ffi/ffi/src/api/node_id.rs +++ b/iceoryx2-ffi/ffi/src/api/node_id.rs @@ -80,6 +80,15 @@ impl HandleToType for iox2_node_id_h_ref { // END type definition // BEGIN C API + +/// Creates a new [`iox2_node_id_h`] by cloning a [`iox2_node_id_ptr`]. +/// +/// # Safety +/// +/// * `node_id_struct_ptr` - Must be either a NULL pointer or a pointer to a valid [`iox2_node_id_t`]. +/// If it is a NULL pointer, the storage will be allocated on the heap. +/// * `node_id_ptr` - Must be a valid [`iox2_node_id_ptr`] +/// * `node_id_handle_ptr` - Must point to a valid [`iox2_node_id_h`]. #[no_mangle] pub unsafe extern "C" fn iox2_node_id_clone_from_ptr( node_id_struct_ptr: *mut iox2_node_id_t, @@ -104,10 +113,18 @@ pub unsafe extern "C" fn iox2_node_id_clone_from_ptr( (*node_id_struct_ptr).deleter = deleter; } - (*node_id_struct_ptr).value.init((*node_id_ptr).clone()); + (*node_id_struct_ptr).value.init(*node_id_ptr); *node_id_handle_ptr = (*node_id_struct_ptr).as_handle(); } +/// Creates a new [`iox2_node_id_h`] by cloning a [`iox2_node_id_h_ref`]. +/// +/// # Safety +/// +/// * `node_id_struct_ptr` - Must be either a NULL pointer or a pointer to a valid [`iox2_node_id_t`]. +/// If it is a NULL pointer, the storage will be allocated on the heap. +/// * `node_id_handle` - Must be a valid [`iox2_node_id_h_ref`] +/// * `node_id_handle_ptr` - Must point to a valid [`iox2_node_id_h`]. #[no_mangle] pub unsafe extern "C" fn iox2_node_id_clone_from_handle( node_id_struct_ptr: *mut iox2_node_id_t, @@ -123,6 +140,11 @@ pub unsafe extern "C" fn iox2_node_id_clone_from_handle( iox2_node_id_clone_from_ptr(node_id_struct_ptr, node_id_ptr, node_id_handle_ptr); } +/// Returns the high bits of the underlying value of the [`iox2_node_id_h`]. +/// +/// # Safety +/// +/// * `node_id_handle` - Must be a valid [`iox2_node_id_h_ref`] #[no_mangle] pub unsafe extern "C" fn iox2_node_id_value_high(node_id_handle: iox2_node_id_h_ref) -> u64 { node_id_handle.assert_non_null(); @@ -131,6 +153,11 @@ pub unsafe extern "C" fn iox2_node_id_value_high(node_id_handle: iox2_node_id_h_ (node_id.value.as_ref().value() >> 64) as u64 } +/// Returns the low bits of the underlying value of the [`iox2_node_id_h`]. +/// +/// # Safety +/// +/// * `node_id_handle` - Must be a valid [`iox2_node_id_h_ref`] #[no_mangle] pub unsafe extern "C" fn iox2_node_id_value_low(node_id_handle: iox2_node_id_h_ref) -> u64 { node_id_handle.assert_non_null(); @@ -139,6 +166,11 @@ pub unsafe extern "C" fn iox2_node_id_value_low(node_id_handle: iox2_node_id_h_r ((node_id.value.as_ref().value() << 64) >> 64) as u64 } +/// Returns the process id of the [`iox2_node_id_h`]. +/// +/// # Safety +/// +/// * `node_id_handle` - Must be a valid [`iox2_node_id_h_ref`] #[no_mangle] pub unsafe extern "C" fn iox2_node_id_pid(node_id_handle: iox2_node_id_h_ref) -> i32 { node_id_handle.assert_non_null(); @@ -147,6 +179,13 @@ pub unsafe extern "C" fn iox2_node_id_pid(node_id_handle: iox2_node_id_h_ref) -> node_id.value.as_ref().pid().value() } +/// Returns the creation time of the [`iox2_node_id_h`]. +/// +/// # Safety +/// +/// * `node_id_handle` - Must be a valid [`iox2_node_id_h_ref`] +/// * `seconds` - Must point to a valid memory location +/// * `nanoseconds` - Must point to a valid memory location #[no_mangle] pub unsafe extern "C" fn iox2_node_id_creation_time( node_id_handle: iox2_node_id_h_ref, @@ -162,6 +201,12 @@ pub unsafe extern "C" fn iox2_node_id_creation_time( *nanoseconds = node_id.value.as_ref().creation_time().nanoseconds(); } +/// Takes ownership of the handle to delete and remove the underlying resources of a +/// [`iox2_node_id_h`]. +/// +/// # Safety +/// +/// * `node_id_handle` - Must be a valid [`iox2_node_id_h`] #[no_mangle] pub unsafe extern "C" fn iox2_node_id_drop(node_id_handle: iox2_node_id_h) { debug_assert!(!node_id_handle.is_null());