From f57bb27d51e94ed85ef68cf1724aeb3c858ae579 Mon Sep 17 00:00:00 2001 From: Jeff Ithier Date: Mon, 18 Nov 2024 12:41:43 +0100 Subject: [PATCH] [#491] Document new C functions --- iceoryx2-ffi/cxx/src/error_string.cpp | 4 -- .../cxx/tests/src/error_string_tests.cpp | 8 --- iceoryx2-ffi/ffi/src/api/config.rs | 14 ++++++ iceoryx2-ffi/ffi/src/api/listener.rs | 14 ++++++ iceoryx2-ffi/ffi/src/api/mod.rs | 14 ++++++ iceoryx2-ffi/ffi/src/api/node.rs | 25 ++++++++++ iceoryx2-ffi/ffi/src/api/node_builder.rs | 14 ++++++ iceoryx2-ffi/ffi/src/api/notifier.rs | 14 ++++++ .../src/api/port_factory_listener_builder.rs | 14 ++++++ .../src/api/port_factory_notifier_builder.rs | 14 ++++++ .../src/api/port_factory_publisher_builder.rs | 14 ++++++ .../api/port_factory_subscriber_builder.rs | 14 ++++++ iceoryx2-ffi/ffi/src/api/publisher.rs | 28 +++++++++++ iceoryx2-ffi/ffi/src/api/service.rs | 28 +++++++++++ .../ffi/src/api/service_builder_event.rs | 14 ++++++ .../ffi/src/api/service_builder_pub_sub.rs | 14 ++++++ iceoryx2-ffi/ffi/src/api/subscriber.rs | 28 +++++++++++ iceoryx2-ffi/ffi/src/api/waitset.rs | 49 ++++++++++++++++--- 18 files changed, 305 insertions(+), 19 deletions(-) diff --git a/iceoryx2-ffi/cxx/src/error_string.cpp b/iceoryx2-ffi/cxx/src/error_string.cpp index 81a3d0fb8..56f54b473 100644 --- a/iceoryx2-ffi/cxx/src/error_string.cpp +++ b/iceoryx2-ffi/cxx/src/error_string.cpp @@ -132,8 +132,4 @@ auto error_string(const iox2::WaitSetRunError& error) -> const char* { return iox2_waitset_run_error_string(iox::into(error)); } -auto error_string(const iox2::WaitSetRunResult& error) -> const char* { - return iox2_waitset_run_result_string(iox::into(error)); -} - } // namespace iox2 diff --git a/iceoryx2-ffi/cxx/tests/src/error_string_tests.cpp b/iceoryx2-ffi/cxx/tests/src/error_string_tests.cpp index a481f6363..2fe5e05ce 100644 --- a/iceoryx2-ffi/cxx/tests/src/error_string_tests.cpp +++ b/iceoryx2-ffi/cxx/tests/src/error_string_tests.cpp @@ -257,14 +257,6 @@ TEST(ErrorStringTest, waitset_create_error_string) { ASSERT_GT(strlen(error_string(Sut::InternalError)), 1U); } -TEST(ErrorStringTest, waitset_run_result_string) { - using Sut = iox2::WaitSetRunResult; - ASSERT_GT(strlen(error_string(Sut::TerminationRequest)), 1U); - ASSERT_GT(strlen(error_string(Sut::Interrupt)), 1U); - ASSERT_GT(strlen(error_string(Sut::StopRequest)), 1U); - ASSERT_GT(strlen(error_string(Sut::AllEventsHandled)), 1U); -} - TEST(ErrorStringTest, waitset_attachment_error_string) { using Sut = iox2::WaitSetAttachmentError; ASSERT_GT(strlen(error_string(Sut::InsufficientCapacity)), 1U); diff --git a/iceoryx2-ffi/ffi/src/api/config.rs b/iceoryx2-ffi/ffi/src/api/config.rs index 847fbc925..3b99e99c7 100644 --- a/iceoryx2-ffi/ffi/src/api/config.rs +++ b/iceoryx2-ffi/ffi/src/api/config.rs @@ -136,6 +136,20 @@ impl HandleToType for iox2_config_h_ref { // BEGIN C API +/// Returns a string literal describing the provided [`iox2_config_creation_error_e`]. +/// +/// # Arguments +/// +/// * `error` - The error value for which a description should be returned +/// +/// # Returns +/// +/// A pointer to a null-terminated string containing the error message. +/// The string is stored in the .rodata section of the binary. +/// +/// # Safety +/// +/// The returned pointer must not be modified or freed and is valid as long as the program runs. #[no_mangle] pub unsafe extern "C" fn iox2_config_creation_error_string( error: iox2_config_creation_error_e, diff --git a/iceoryx2-ffi/ffi/src/api/listener.rs b/iceoryx2-ffi/ffi/src/api/listener.rs index 21002f0fe..e45f04079 100644 --- a/iceoryx2-ffi/ffi/src/api/listener.rs +++ b/iceoryx2-ffi/ffi/src/api/listener.rs @@ -140,6 +140,20 @@ pub type iox2_listener_wait_all_callback = // BEGIN C API +/// Returns a string representation of the provided [`iox2_listener_wait_error_e`] error code. +/// +/// # Arguments +/// +/// * `error` - The error code that should be converted into a string +/// +/// # Returns +/// +/// A pointer to a null-terminated string containing the error message. +/// The string is stored in the .rodata section of the binary. +/// +/// # Safety +/// +/// * The returned pointer must not be modified or freed and is only valid as long as the program runs #[no_mangle] pub unsafe extern "C" fn iox2_listener_wait_error_string( error: iox2_listener_wait_error_e, diff --git a/iceoryx2-ffi/ffi/src/api/mod.rs b/iceoryx2-ffi/ffi/src/api/mod.rs index 5c113dbcd..d8101b1de 100644 --- a/iceoryx2-ffi/ffi/src/api/mod.rs +++ b/iceoryx2-ffi/ffi/src/api/mod.rs @@ -189,6 +189,20 @@ trait AssertNonNullHandle { fn assert_non_null(self); } +/// Returns a string literal describing the provided [`iox2_semantic_string_error_e`]. +/// +/// # Arguments +/// +/// * `error` - The error value for which a description should be returned +/// +/// # Returns +/// +/// A pointer to a null-terminated string containing the error message. +/// The string is stored in the .rodata section of the binary. +/// +/// # Safety +/// +/// The returned pointer must not be modified or freed and is valid as long as the program runs. #[no_mangle] pub unsafe extern "C" fn iox2_semantic_string_error_string( error: iox2_semantic_string_error_e, diff --git a/iceoryx2-ffi/ffi/src/api/node.rs b/iceoryx2-ffi/ffi/src/api/node.rs index c1d0a5cca..f4ad36f56 100644 --- a/iceoryx2-ffi/ffi/src/api/node.rs +++ b/iceoryx2-ffi/ffi/src/api/node.rs @@ -187,6 +187,17 @@ pub type iox2_node_list_callback = extern "C" fn( // BEGIN C API +/// Returns a string representation of the [`iox2_node_list_failure_e`] error code. +/// +/// # Arguments +/// +/// * `error` - The error value for which a description should be returned +/// +/// Returns a pointer to a null-terminated string containing the error description. +/// +/// # Safety +/// +/// * The returned pointer is valid as long as the program runs and must not be modified or freed #[no_mangle] pub unsafe extern "C" fn iox2_node_list_failure_string( error: iox2_node_list_failure_e, @@ -194,6 +205,20 @@ pub unsafe extern "C" fn iox2_node_list_failure_string( error.as_str_literal().as_ptr() as *const c_char } +/// Returns a string representation of the [`iox2_node_wait_failure_e`] error code. +/// +/// # Arguments +/// +/// * `error` - The error value for which a description should be returned +/// +/// # Returns +/// +/// A pointer to a null-terminated string containing the error message. +/// The string is stored in the .rodata section of the binary. +/// +/// # Safety +/// +/// * The returned pointer is valid as long as the program runs and must not be modified or freed #[no_mangle] pub unsafe extern "C" fn iox2_node_wait_failure_string( error: iox2_node_wait_failure_e, diff --git a/iceoryx2-ffi/ffi/src/api/node_builder.rs b/iceoryx2-ffi/ffi/src/api/node_builder.rs index b505e1215..1b0e3f7df 100644 --- a/iceoryx2-ffi/ffi/src/api/node_builder.rs +++ b/iceoryx2-ffi/ffi/src/api/node_builder.rs @@ -101,6 +101,20 @@ impl HandleToType for iox2_node_builder_h_ref { // BEGIN C API +/// Returns a string literal describing the provided [`iox2_node_creation_failure_e`]. +/// +/// # Arguments +/// +/// * `error` - The error value for which a description should be returned +/// +/// # Returns +/// +/// A pointer to a null-terminated string containing the error message. +/// The string is stored in the .rodata section of the binary. +/// +/// # Safety +/// +/// The returned pointer must not be modified or freed and is valid as long as the program runs. #[no_mangle] pub unsafe extern "C" fn iox2_node_creation_failure_string( error: iox2_node_creation_failure_e, diff --git a/iceoryx2-ffi/ffi/src/api/notifier.rs b/iceoryx2-ffi/ffi/src/api/notifier.rs index 79c472e2c..9b43cde9f 100644 --- a/iceoryx2-ffi/ffi/src/api/notifier.rs +++ b/iceoryx2-ffi/ffi/src/api/notifier.rs @@ -131,6 +131,20 @@ impl HandleToType for iox2_notifier_h_ref { // BEGIN C API +/// Returns a string literal describing the provided [`iox2_notifier_notify_error_e`]. +/// +/// # Arguments +/// +/// * `error` - The error value for which a description should be returned +/// +/// # Returns +/// +/// A pointer to a null-terminated string containing the error message. +/// The string is stored in the .rodata section of the binary. +/// +/// # Safety +/// +/// The returned pointer must not be modified or freed and is valid as long as the program runs. #[no_mangle] pub unsafe extern "C" fn iox2_notifier_notify_error_string( error: iox2_notifier_notify_error_e, diff --git a/iceoryx2-ffi/ffi/src/api/port_factory_listener_builder.rs b/iceoryx2-ffi/ffi/src/api/port_factory_listener_builder.rs index 4a64218f7..5e6445883 100644 --- a/iceoryx2-ffi/ffi/src/api/port_factory_listener_builder.rs +++ b/iceoryx2-ffi/ffi/src/api/port_factory_listener_builder.rs @@ -136,6 +136,20 @@ impl HandleToType for iox2_port_factory_listener_builder_h_ref { // BEGIN C API +/// Returns a string literal describing the provided [`iox2_listener_create_error_e`]. +/// +/// # Arguments +/// +/// * `error` - The error value for which a description should be returned +/// +/// # Returns +/// +/// A pointer to a null-terminated string containing the error message. +/// The string is stored in the .rodata section of the binary. +/// +/// # Safety +/// +/// The returned pointer must not be modified or freed and is valid as long as the program runs. #[no_mangle] pub unsafe extern "C" fn iox2_listener_create_error_string( error: iox2_listener_create_error_e, diff --git a/iceoryx2-ffi/ffi/src/api/port_factory_notifier_builder.rs b/iceoryx2-ffi/ffi/src/api/port_factory_notifier_builder.rs index 4ff73e1c6..ca4a8824f 100644 --- a/iceoryx2-ffi/ffi/src/api/port_factory_notifier_builder.rs +++ b/iceoryx2-ffi/ffi/src/api/port_factory_notifier_builder.rs @@ -132,6 +132,20 @@ impl HandleToType for iox2_port_factory_notifier_builder_h_ref { // BEGIN C API +/// Returns a string literal describing the provided [`iox2_notifier_create_error_e`]. +/// +/// # Arguments +/// +/// * `error` - The error value for which a description should be returned +/// +/// # Returns +/// +/// A pointer to a null-terminated string containing the error message. +/// The string is stored in the .rodata section of the binary. +/// +/// # Safety +/// +/// The returned pointer must not be modified or freed and is valid as long as the program runs. #[no_mangle] pub unsafe extern "C" fn iox2_notifier_create_error_string( error: iox2_notifier_create_error_e, diff --git a/iceoryx2-ffi/ffi/src/api/port_factory_publisher_builder.rs b/iceoryx2-ffi/ffi/src/api/port_factory_publisher_builder.rs index 1cd0c27f5..79bc069ba 100644 --- a/iceoryx2-ffi/ffi/src/api/port_factory_publisher_builder.rs +++ b/iceoryx2-ffi/ffi/src/api/port_factory_publisher_builder.rs @@ -175,6 +175,20 @@ impl HandleToType for iox2_port_factory_publisher_builder_h_ref { // BEGIN C API +/// Returns a string literal describing the provided [`iox2_publisher_create_error_e`]. +/// +/// # Arguments +/// +/// * `error` - The error value for which a description should be returned +/// +/// # Returns +/// +/// A pointer to a null-terminated string containing the error message. +/// The string is stored in the .rodata section of the binary. +/// +/// # Safety +/// +/// The returned pointer must not be modified or freed and is valid as long as the program runs. #[no_mangle] pub unsafe extern "C" fn iox2_publisher_create_error_string( error: iox2_publisher_create_error_e, diff --git a/iceoryx2-ffi/ffi/src/api/port_factory_subscriber_builder.rs b/iceoryx2-ffi/ffi/src/api/port_factory_subscriber_builder.rs index 7764dea19..9f7e61874 100644 --- a/iceoryx2-ffi/ffi/src/api/port_factory_subscriber_builder.rs +++ b/iceoryx2-ffi/ffi/src/api/port_factory_subscriber_builder.rs @@ -140,6 +140,20 @@ impl HandleToType for iox2_port_factory_subscriber_builder_h_ref { // BEGIN C API +/// Returns a string literal describing the provided [`iox2_subscriber_create_error_e`]. +/// +/// # Arguments +/// +/// * `error` - The error value for which a description should be returned +/// +/// # Returns +/// +/// A pointer to a null-terminated string containing the error message. +/// The string is stored in the .rodata section of the binary. +/// +/// # Safety +/// +/// The returned pointer must not be modified or freed and is valid as long as the program runs. #[no_mangle] pub unsafe extern "C" fn iox2_subscriber_create_error_string( error: iox2_subscriber_create_error_e, diff --git a/iceoryx2-ffi/ffi/src/api/publisher.rs b/iceoryx2-ffi/ffi/src/api/publisher.rs index c5481f5a7..f70b07167 100644 --- a/iceoryx2-ffi/ffi/src/api/publisher.rs +++ b/iceoryx2-ffi/ffi/src/api/publisher.rs @@ -246,6 +246,20 @@ unsafe fn send_slice_copy( // BEGIN C API +/// Returns a string literal describing the provided [`iox2_publisher_send_error_e`]. +/// +/// # Arguments +/// +/// * `error` - The error value for which a description should be returned +/// +/// # Returns +/// +/// A pointer to a null-terminated string containing the error message. +/// The string is stored in the .rodata section of the binary. +/// +/// # Safety +/// +/// The returned pointer must not be modified or freed and is valid as long as the program runs. #[no_mangle] pub unsafe extern "C" fn iox2_publisher_send_error_string( error: iox2_publisher_send_error_e, @@ -253,6 +267,20 @@ pub unsafe extern "C" fn iox2_publisher_send_error_string( error.as_str_literal().as_ptr() as *const c_char } +/// Returns a string literal describing the provided [`iox2_publisher_loan_error_e`]. +/// +/// # Arguments +/// +/// * `error` - The error value for which a description should be returned +/// +/// # Returns +/// +/// A pointer to a null-terminated string containing the error message. +/// The string is stored in the .rodata section of the binary. +/// +/// # Safety +/// +/// The returned pointer must not be modified or freed and is valid as long as the program runs. #[no_mangle] pub unsafe extern "C" fn iox2_publisher_loan_error_string( error: iox2_publisher_loan_error_e, diff --git a/iceoryx2-ffi/ffi/src/api/service.rs b/iceoryx2-ffi/ffi/src/api/service.rs index 3ec4d6695..91d7e0c5c 100644 --- a/iceoryx2-ffi/ffi/src/api/service.rs +++ b/iceoryx2-ffi/ffi/src/api/service.rs @@ -134,6 +134,20 @@ pub type iox2_service_list_callback = extern "C" fn( // BEGIN C API +/// Returns a string literal describing the provided [`iox2_service_details_error_e`]. +/// +/// # Arguments +/// +/// * `error` - The error value for which a description should be returned +/// +/// # Returns +/// +/// A pointer to a null-terminated string containing the error message. +/// The string is stored in the .rodata section of the binary. +/// +/// # Safety +/// +/// The returned pointer must not be modified or freed and is valid as long as the program runs. #[no_mangle] pub unsafe extern "C" fn iox2_service_details_error_string( error: iox2_service_details_error_e, @@ -141,6 +155,20 @@ pub unsafe extern "C" fn iox2_service_details_error_string( error.as_str_literal().as_ptr() as *const c_char } +/// Returns a string literal describing the provided [`iox2_service_list_error_e`]. +/// +/// # Arguments +/// +/// * `error` - The error value for which a description should be returned +/// +/// # Returns +/// +/// A pointer to a null-terminated string containing the error message. +/// The string is stored in the .rodata section of the binary. +/// +/// # Safety +/// +/// The returned pointer must not be modified or freed and is valid as long as the program runs. #[no_mangle] pub unsafe extern "C" fn iox2_service_list_error_string( error: iox2_service_list_error_e, diff --git a/iceoryx2-ffi/ffi/src/api/service_builder_event.rs b/iceoryx2-ffi/ffi/src/api/service_builder_event.rs index cddf408e1..18eca1ccb 100644 --- a/iceoryx2-ffi/ffi/src/api/service_builder_event.rs +++ b/iceoryx2-ffi/ffi/src/api/service_builder_event.rs @@ -157,6 +157,20 @@ impl IntoCInt for EventOpenOrCreateError { // BEGIN C API +/// Returns a string literal describing the provided [`iox2_event_open_or_create_error_e`]. +/// +/// # Arguments +/// +/// * `error` - The error value for which a description should be returned +/// +/// # Returns +/// +/// A pointer to a null-terminated string containing the error message. +/// The string is stored in the .rodata section of the binary. +/// +/// # Safety +/// +/// The returned pointer must not be modified or freed and is valid as long as the program runs. #[no_mangle] pub unsafe extern "C" fn iox2_event_open_or_create_error_string( error: iox2_event_open_or_create_error_e, diff --git a/iceoryx2-ffi/ffi/src/api/service_builder_pub_sub.rs b/iceoryx2-ffi/ffi/src/api/service_builder_pub_sub.rs index 439050aa9..d80bb6c25 100644 --- a/iceoryx2-ffi/ffi/src/api/service_builder_pub_sub.rs +++ b/iceoryx2-ffi/ffi/src/api/service_builder_pub_sub.rs @@ -227,6 +227,20 @@ pub enum iox2_type_detail_error_e { // BEGIN C API +/// Returns a string literal describing the provided [`iox2_pub_sub_open_or_create_error_e`]. +/// +/// # Arguments +/// +/// * `error` - The error value for which a description should be returned +/// +/// # Returns +/// +/// A pointer to a null-terminated string containing the error message. +/// The string is stored in the .rodata section of the binary. +/// +/// # Safety +/// +/// The returned pointer must not be modified or freed and is valid as long as the program runs. #[no_mangle] pub unsafe extern "C" fn iox2_pub_sub_open_or_create_error_string( error: iox2_pub_sub_open_or_create_error_e, diff --git a/iceoryx2-ffi/ffi/src/api/subscriber.rs b/iceoryx2-ffi/ffi/src/api/subscriber.rs index 18a56a9d5..1fbbad121 100644 --- a/iceoryx2-ffi/ffi/src/api/subscriber.rs +++ b/iceoryx2-ffi/ffi/src/api/subscriber.rs @@ -163,6 +163,20 @@ impl HandleToType for iox2_subscriber_h_ref { // BEGIN C API +/// Returns a string literal describing the provided [`iox2_subscriber_receive_error_e`]. +/// +/// # Arguments +/// +/// * `error` - The error value for which a description should be returned +/// +/// # Returns +/// +/// A pointer to a null-terminated string containing the error message. +/// The string is stored in the .rodata section of the binary. +/// +/// # Safety +/// +/// The returned pointer must not be modified or freed and is valid as long as the program runs. #[no_mangle] pub unsafe extern "C" fn iox2_subscriber_receive_error_string( error: iox2_subscriber_receive_error_e, @@ -170,6 +184,20 @@ pub unsafe extern "C" fn iox2_subscriber_receive_error_string( error.as_str_literal().as_ptr() as *const c_char } +/// Returns a string literal describing the provided [`iox2_connection_failure_e`]. +/// +/// # Arguments +/// +/// * `error` - The error value for which a description should be returned +/// +/// # Returns +/// +/// A pointer to a null-terminated string containing the error message. +/// The string is stored in the .rodata section of the binary. +/// +/// # Safety +/// +/// The returned pointer must not be modified or freed and is valid as long as the program runs. #[no_mangle] pub unsafe extern "C" fn iox2_connection_failure_string( error: iox2_connection_failure_e, diff --git a/iceoryx2-ffi/ffi/src/api/waitset.rs b/iceoryx2-ffi/ffi/src/api/waitset.rs index b5835cb1f..85646e16a 100644 --- a/iceoryx2-ffi/ffi/src/api/waitset.rs +++ b/iceoryx2-ffi/ffi/src/api/waitset.rs @@ -211,6 +211,20 @@ pub type iox2_waitset_run_callback = extern "C" fn( // BEGIN C API +/// Returns a string literal describing the provided [`iox2_waitset_create_error_e`]. +/// +/// # Arguments +/// +/// * `error` - The error value for which a description should be returned +/// +/// # Returns +/// +/// A pointer to a null-terminated string containing the error message. +/// The string is stored in the .rodata section of the binary. +/// +/// # Safety +/// +/// The returned pointer must not be modified or freed and is valid as long as the program runs. #[no_mangle] pub unsafe extern "C" fn iox2_waitset_create_error_string( error: iox2_waitset_create_error_e, @@ -218,6 +232,20 @@ pub unsafe extern "C" fn iox2_waitset_create_error_string( error.as_str_literal().as_ptr() as *const c_char } +/// Returns a string literal describing the provided [`iox2_waitset_attachment_error_e`]. +/// +/// # Arguments +/// +/// * `error` - The error value for which a description should be returned +/// +/// # Returns +/// +/// A pointer to a null-terminated string containing the error message. +/// The string is stored in the .rodata section of the binary. +/// +/// # Safety +/// +/// The returned pointer must not be modified or freed and is valid as long as the program runs. #[no_mangle] pub unsafe extern "C" fn iox2_waitset_attachment_error_string( error: iox2_waitset_attachment_error_e, @@ -225,13 +253,20 @@ pub unsafe extern "C" fn iox2_waitset_attachment_error_string( error.as_str_literal().as_ptr() as *const c_char } -#[no_mangle] -pub unsafe extern "C" fn iox2_waitset_run_result_string( - error: iox2_waitset_run_result_e, -) -> *const c_char { - error.as_str_literal().as_ptr() as *const c_char -} - +/// Returns a string literal describing the provided [`iox2_waitset_run_error_e`]. +/// +/// # Arguments +/// +/// * `error` - The error value for which a description should be returned +/// +/// # Returns +/// +/// A pointer to a null-terminated string containing the error message. +/// The string is stored in the .rodata section of the binary. +/// +/// # Safety +/// +/// The returned pointer must not be modified or freed and is valid as long as the program runs. #[no_mangle] pub unsafe extern "C" fn iox2_waitset_run_error_string( error: iox2_waitset_run_error_e,