mechutil 0.8.0

Utility structures and functions for mechatronics applications.
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
85
86

//
// Copyright (C) 2025 Automated Design Corp.. All Rights Reserved.
// Created Date: 2025-02-18 13:59:17
// -----
// Last Modified: 2025-02-25 06:56:26
// -----
//
//

use async_trait::async_trait;
use tokio::sync::{mpsc, oneshot};

use super::filter::SubscriptionFilter;

/// A struct representing a subscription broadcast, containing the topic, message,
/// and subscription information.
#[derive(Clone, Debug)]
pub struct SubscriptionBroadcast<R> {
    pub id: usize,
    pub topic: String,
    pub message: R,
}

#[derive(Clone, Debug)]
pub struct SubscriptionResponse {
    pub id: usize,
}

/// A type alias for the subscription broadcast sender.
pub type SubscriptionBroadcastTx<R> = mpsc::Sender<SubscriptionBroadcast<R>>;
/// A type alias for the subscription broadcast receiver.
pub type SubscriptionBroadcastRx<R> = mpsc::Receiver<SubscriptionBroadcast<R>>;

/// A type alias for the subscription response receiver.
pub type SubscriptionResponseTx = oneshot::Sender<SubscriptionResponse>;

/// A trait that defines the behavior for handling subscriptions. The intended use
/// is for async nodes to register and manage subscriptions in a generic way.
#[async_trait]
pub trait SubscriptionHandler<R>
where
    R: Clone + Send + 'static,
{
    /// Subscribe to a topic or event. Any message broadcast to the topic will be sent to the subscriber.
    ///
    /// # Parameters
    /// - `topic`: The topic or event to subscribe to.
    /// - `subscription_information`: Information related to the subscription.
    /// - `broadcast_tx`: The broadcast channel to send messages to the subscriber.
    /// - `respond_to`: The channel to send a response to acknowledge the subscription.
    async fn subscribe(&mut self, topic: String, respond_to: SubscriptionResponseTx);

    /// Subscribe to a topic or event with a filter. The filter will be used to determine if a message
    /// should be sent to the subscriber when an event on the topic occurs.
    ///
    /// # Parameters
    /// - `topic`: The topic or event to subscribe to.
    /// - `subscription_information`: Information related to the subscription.
    /// - `filter`: The filter to apply to the subscription.
    /// - `broadcast_tx`: The broadcast channel to send messages to the subscriber.
    /// - `respond_to`: The channel to send a response to acknowledge the subscription.
    async fn subscribe_with_filter(
        &mut self,
        topic: String,
        filter: Box<dyn SubscriptionFilter<R> + Send + Sync>,
        respond_to: SubscriptionResponseTx,
    );

    /// Unsubscribe from a topic or event.
    ///
    /// # Parameters
    /// - `topic`: The topic or event to unsubscribe from.
    /// - `subscription_information`: Information related to the subscription.
    /// - `respond_to`: The channel to send a response to acknowledge the unsubscription.
    async fn unsubscribe(&mut self, id: usize, respond_to: SubscriptionResponseTx);

    /// Broadcast a message to all subscribers of a topic.
    ///
    /// # Parameters
    /// - `topic`: The topic to broadcast the message to.
    /// - `message`: The message to broadcast.
    ///
    /// # Returns
    /// - `Result<(), anyhow::Error>`: Returns an error if the broadcast fails.
    async fn broadcast(&self, topic: String, message: R) -> Result<(), anyhow::Error>;
}