thormotion 0.4.2

A cross-platform motion control library for Thorlabs systems, written in Rust.
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

/*
Project: thormotion
GitHub: https://github.com/MillieFD/thormotion

BSD 3-Clause License, Copyright (c) 2025, Amelia Fraser-Dale

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the conditions of the LICENSE are met.
*/

use std::sync::Arc;

use crate::devices::bug_abort;
use crate::messages::Receiver;

/// Indicates whether the wrapped [`Receiver`] is bound to a [`New`][1] or [`Existing`][2]
/// [`Sender`][3]
///
/// [1]: Provenance::New
/// [2]: Provenance::Existing
/// [3]: crate::messages::Sender
#[derive(Debug, Clone)]
pub(crate) enum Provenance {
    /// If a [`Sender`][1] does not exist for the given command ID, a new [`broadcast`][2] channel
    /// is created. The new [`Sender`][1] is inserted into the [`Dispatcher`][3] [`HashMap`][4]
    /// and the new [`Receiver`] is returned wrapped in [`Provenance::New`].
    ///
    /// [1]: crate::messages::Sender
    /// [2]: async_broadcast::broadcast
    /// [3]: crate::messages::Dispatcher
    /// [4]: ahash::HashMap
    New(Receiver),
    /// If the [`Dispatcher`][1] [`HashMap`][2] already contains a [`Sender`][3] for the given
    /// command ID, a [`new_receiver`][4] is subscribed to the existing channel and returned wrapped
    /// in [`Provenance::Existing`].
    ///
    /// [1]: crate::messages::Dispatcher
    /// [2]: ahash::HashMap
    /// [3]: crate::messages::Sender
    /// [4]: async_broadcast::Sender::new_receiver
    Existing(Receiver),
}

impl Provenance {
    /// Consumes the [`Provenance`], returning the wrapped [`Receiver`] regardless of whether it is
    /// [`New`][1] or [`Existing`][2].
    ///
    /// This function does not panic.
    ///
    /// [1]: Provenance::New
    /// [2]: Provenance::Existing
    pub(super) fn unpack(self) -> Receiver {
        match self {
            Provenance::New(rx) => rx,
            Provenance::Existing(rx) => rx,
        }
    }

    /// Returns `True` if the [`Provenance`] is [`New`][1].
    ///
    /// [1]: Provenance::New
    pub(crate) fn is_new(&self) -> bool {
        match self {
            Provenance::New(_) => true,
            Provenance::Existing(_) => false,
        }
    }

    /// Consumes the [`Provenance`], returning the message received by the wrapped [`Receiver`].
    pub(crate) async fn receive(self) -> Arc<[u8]> {
        self.unpack().recv_direct().await.unwrap_or_else(|e| {
            bug_abort(format!(
                "Failed to receive command from broadcast channel : {}",
                e
            ))
        })
    }
}