iceoryx2 0.9.0

iceoryx2: Lock-Free Zero-Copy Interprocess Communication
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

// 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

use iceoryx2_cal::{
    shared_memory::SharedMemoryOpenError, zero_copy_connection::ZeroCopyCreationError,
};

/// Describes the errors that can occur when a connection between two endpoints (ports) is
/// established
#[derive(Debug, Eq, PartialEq, Copy, Clone, Hash)]
pub enum ConnectionFailure {
    /// Failures when creating the connection
    FailedToEstablishConnection(ZeroCopyCreationError),
    /// Failures when mapping the corresponding data segment
    UnableToMapSendersDataSegment(SharedMemoryOpenError),
}

impl From<ZeroCopyCreationError> for ConnectionFailure {
    fn from(value: ZeroCopyCreationError) -> Self {
        ConnectionFailure::FailedToEstablishConnection(value)
    }
}

impl From<SharedMemoryOpenError> for ConnectionFailure {
    fn from(value: SharedMemoryOpenError) -> Self {
        ConnectionFailure::UnableToMapSendersDataSegment(value)
    }
}

impl core::fmt::Display for ConnectionFailure {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        write!(f, "ConnectionFailure::{self:?}")
    }
}

impl core::error::Error for ConnectionFailure {}

/// Explicitly triggers and update of all connections and performs underlying management work.
pub trait UpdateConnections {
    /// Explicitly updates all connections to the [`crate::port::subscriber::Subscriber`]s. This is
    /// required to be called whenever a new [`crate::port::subscriber::Subscriber`] connected to
    /// the service. It is done implicitly whenever [`crate::sample_mut::SampleMut::send()`] or
    /// [`crate::port::publisher::Publisher::send_copy()`] is called.
    /// When a [`crate::port::subscriber::Subscriber`] is connected that requires a history this
    /// call will deliver it.
    ///
    /// # Example
    ///
    /// ```
    /// use iceoryx2::prelude::*;
    /// use iceoryx2::port::update_connections::UpdateConnections;
    ///
    /// # fn main() -> Result<(), Box<dyn core::error::Error>> {
    /// # let node = NodeBuilder::new().create::<ipc::Service>()?;
    /// #
    /// # let service = node.service_builder(&"My/Funk/ServiceName".try_into()?)
    /// #     .publish_subscribe::<u64>()
    /// #     .history_size(1)
    /// #     .open_or_create()?;
    /// #
    /// # let publisher = service.publisher_builder().create()?;
    ///
    /// publisher.send_copy(1234)?;
    ///
    /// let subscriber = service.subscriber_builder().create()?;
    ///
    /// // updates all connections and delivers history to new participants
    /// publisher.update_connections();
    ///
    /// println!("history received {:?}", subscriber.receive()?.unwrap());
    /// # Ok(())
    /// # }
    /// ```
    fn update_connections(&self) -> Result<(), ConnectionFailure>;
}