[#690] Add documentation for server, pending response and active request

Author: elfenpiff

iceoryx2/src/active_request.rs

@@ -428,6 +428,39 @@ impl<
         ResponseHeader: Debug + ZeroCopySend,
     > ActiveRequest<Service, RequestPayload, RequestHeader, [ResponsePayload], ResponseHeader>
 {
+    /// Loans/allocates a [`ResponseMut`] from the underlying data segment of the
+    /// [`Server`](crate::port::server::Server)
+    /// and initializes all slice elements with the default value. This can be a performance hit
+    /// and [`ActiveRequest::loan_slice_uninit()`] can be used to loan a slice of
+    /// [`core::mem::MaybeUninit<Payload>`].
+    ///
+    /// On failure it returns [`LoanError`] describing the failure.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use iceoryx2::prelude::*;
+    /// # fn main() -> Result<(), Box<dyn core::error::Error>> {
+    /// # let node = NodeBuilder::new().create::<ipc::Service>()?;
+    /// #
+    /// # let service = node.service_builder(&"Whatever6".try_into()?)
+    /// #     .request_response::<u64, [usize]>()
+    /// #     .open_or_create()?;
+    /// #
+    /// # let client = service.client_builder().create()?;
+    /// let server = service.server_builder()
+    ///                     .initial_max_slice_len(32)
+    ///                     .create()?;
+    /// # let pending_response = client.send_copy(0)?;
+    /// let active_request = server.receive()?.unwrap();
+    ///
+    /// let slice_length = 13;
+    /// let mut response = active_request.loan_slice(slice_length)?;
+    /// response.send()?;
+    ///
+    /// # Ok(())
+    /// # }
+    /// ```
     pub fn loan_slice(
         &self,
         slice_len: usize,
@@ -445,6 +478,41 @@ impl<
         ResponseHeader: Debug + ZeroCopySend,
     > ActiveRequest<Service, RequestPayload, RequestHeader, [ResponsePayload], ResponseHeader>
 {
+    /// Loans/allocates a [`ResponseMutUninit`] from the underlying data segment of the
+    /// [`Server`](crate::port::server::Server).
+    /// The user has to initialize the payload before it can be sent.
+    ///
+    /// On failure it returns [`LoanError`] describing the failure.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use iceoryx2::prelude::*;
+    /// # fn main() -> Result<(), Box<dyn core::error::Error>> {
+    /// # let node = NodeBuilder::new().create::<ipc::Service>()?;
+    /// #
+    /// # let service = node.service_builder(&"Whatever6".try_into()?)
+    /// #     .request_response::<u64, [usize]>()
+    /// #     .open_or_create()?;
+    /// #
+    /// # let client = service.client_builder().create()?;
+    /// let server = service.server_builder()
+    ///                     .initial_max_slice_len(32)
+    ///                     .create()?;
+    /// # let pending_response = client.send_copy(0)?;
+    /// let active_request = server.receive()?.unwrap();
+    ///
+    /// let slice_length = 13;
+    /// let mut response = active_request.loan_slice_uninit(slice_length)?;
+    /// for element in response.payload_mut() {
+    ///     element.write(1234);
+    /// }
+    /// let response = unsafe { response.assume_init() };
+    /// response.send()?;
+    ///
+    /// # Ok(())
+    /// # }
+    /// ```
     pub fn loan_slice_uninit(
         &self,
         slice_len: usize,

iceoryx2/src/pending_response.rs

@@ -300,6 +300,36 @@ impl<
         ResponseHeader: Debug + ZeroCopySend,
     > PendingResponse<Service, RequestPayload, RequestHeader, [ResponsePayload], ResponseHeader>
 {
+    /// Receives a [`Response`] from one of the [`Server`](crate::port::server::Server)s that
+    /// received the [`RequestMut`].
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use iceoryx2::prelude::*;
+    ///
+    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
+    /// # let node = NodeBuilder::new().create::<ipc::Service>()?;
+    /// #
+    /// # let service = node
+    /// #    .service_builder(&"My/Funk/ServiceName".try_into()?)
+    /// #    .request_response::<u64, [usize]>()
+    /// #    .open_or_create()?;
+    /// #
+    /// # let client = service.client_builder().create()?;
+    ///
+    /// # let request = client.loan_uninit()?;
+    /// # let request = request.write_payload(0);
+    ///
+    /// let pending_response = request.send()?;
+    ///
+    /// if let Some(response) = pending_response.receive()? {
+    ///     println!("received response: {:?}", response);
+    /// }
+    ///
+    /// # Ok(())
+    /// # }
+    /// ```
     pub fn receive(
         &self,
     ) -> Result<Option<Response<Service, [ResponsePayload], ResponseHeader>>, ReceiveError> {

iceoryx2/src/port/server.rs

@@ -543,6 +543,33 @@ impl<
         }
     }
 
+    /// Receives a [`RequestMut`](crate::request_mut::RequestMut) that was sent by a
+    /// [`Client`](crate::port::client::Client) and returns an [`ActiveRequest`] which
+    /// can be used to respond.
+    /// If no [`RequestMut`](crate::request_mut::RequestMut)s were received it
+    /// returns [`None`].
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use iceoryx2::prelude::*;
+    ///
+    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
+    /// # let node = NodeBuilder::new().create::<ipc::Service>()?;
+    /// #
+    /// let service = node
+    ///     .service_builder(&"My/Funk/ServiceName".try_into()?)
+    ///     .request_response::<[u64], u64>()
+    ///     .open_or_create()?;
+    ///
+    /// let server = service.server_builder().create()?;
+    ///
+    /// while let Some(active_request) = server.receive()? {
+    ///     println!("received request: {:?}", active_request);
+    /// }
+    /// # Ok(())
+    /// # }
+    /// ```
     pub fn receive(
         &self,
     ) -> Result<
@@ -596,6 +623,7 @@ impl<
         ResponseHeader: Debug + ZeroCopySend,
     > Server<Service, [CustomPayloadMarker], RequestHeader, ResponsePayload, ResponseHeader>
 {
+    #[doc(hidden)]
     pub unsafe fn receive_custom_payload(
         &self,
     ) -> Result<