openthread/ot/singleton/
backing.rs

1// Copyright 2022 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5use super::*;
6use std::cell::{Cell, RefCell};
7use std::task::Waker;
8
9/// Backing struct for OpenThread instances. This type contains information
10/// related to the rust API implementation.
11#[allow(clippy::type_complexity)]
12pub(crate) struct InstanceBacking {
13    pub waker: Cell<Waker>,
14    pub platform: RefCell<std::boxed::Box<dyn Platform>>,
15    pub state_change_fn: Cell<Option<std::boxed::Box<dyn FnMut(ot::ChangedFlags)>>>,
16    pub cli_output_fn: Cell<Option<std::boxed::Box<dyn FnMut(&CStr)>>>,
17    pub ip6_receive_fn: Cell<Option<std::boxed::Box<dyn FnMut(OtMessageBox<'_>)>>>,
18    pub ip6_address_fn: Cell<Option<std::boxed::Box<dyn FnMut(Ip6AddressInfo<'_>, bool)>>>,
19    pub multicast_listener_callback:
20        Cell<Option<std::boxed::Box<dyn FnMut(BackboneRouterMulticastListenerEvent, &Ip6Address)>>>,
21    pub active_scan_fn: Cell<Option<std::boxed::Box<dyn FnMut(Option<&ActiveScanResult>)>>>,
22    pub energy_scan_fn: Cell<Option<std::boxed::Box<dyn FnMut(Option<&EnergyScanResult>)>>>,
23    pub joiner_fn: Cell<Option<std::boxed::Box<dyn FnOnce(Result)>>>,
24    pub srp_server_service_update_fn: Cell<
25        Option<std::boxed::Box<dyn FnMut(ot::SrpServerServiceUpdateId, &ot::SrpServerHost, u32)>>,
26    >,
27    pub dnssd_query_sub_unsub_fn: Cell<Option<std::boxed::Box<dyn FnMut(bool, &CStr)>>>,
28    pub nat64_receive_fn: Cell<Option<std::boxed::Box<dyn FnMut(OtMessageBox<'_>)>>>,
29    pub dhcp6pd_state_change_callback_fn:
30        Cell<Option<std::boxed::Box<dyn FnMut(BorderRoutingDhcp6PdState)>>>,
31    pub ephemeral_key_callback: Cell<Option<std::boxed::Box<dyn FnMut()>>>,
32}
33
34impl InstanceBacking {
35    pub(crate) fn new<T: Platform + 'static>(platform: T) -> Self {
36        Self {
37            waker: Cell::new(futures::task::noop_waker()),
38            platform: RefCell::new(Box::new(platform) as std::boxed::Box<dyn Platform>),
39            cli_output_fn: Cell::new(None),
40            ip6_receive_fn: Cell::new(None),
41            ip6_address_fn: Cell::new(None),
42            state_change_fn: Cell::new(None),
43            active_scan_fn: Cell::new(None),
44            energy_scan_fn: Cell::new(None),
45            joiner_fn: Cell::new(None),
46            srp_server_service_update_fn: Cell::new(None),
47            dnssd_query_sub_unsub_fn: Cell::new(None),
48            multicast_listener_callback: Cell::new(None),
49            nat64_receive_fn: Cell::new(None),
50            dhcp6pd_state_change_callback_fn: Cell::new(None),
51            ephemeral_key_callback: Cell::new(None),
52        }
53    }
54}
55
56impl InstanceBacking {
57    unsafe fn glob() -> &'static mut Option<InstanceBacking> {
58        static mut SINGLETON_BACKING: Option<InstanceBacking> = None;
59        // TODO(b/319328255) -- Fix usage so lint no longer applies
60        #[allow(static_mut_refs)]
61        &mut SINGLETON_BACKING
62    }
63
64    /// Returns a reference to the global singleton `InstanceBacking`.
65    ///
66    /// If you are tempted to use this method, consider using `Instance::borrow_backing()`
67    /// instead.
68    ///
69    /// ## Safety ##
70    ///
71    /// The behavior of this method is undefined when called at the same
72    /// time that `InstanceBacking::set_singleton()`/`InstanceBacking::drop_singleton()`
73    /// is being called from a different thread.
74    ///
75    /// In order to keep things safe and straightforward, this method should
76    /// only be called by the implementation of `Instance::borrow_backing()`.
77    pub(crate) unsafe fn as_ref() -> &'static InstanceBacking {
78        Self::glob().as_ref().expect("otInstance is uninitialized")
79    }
80
81    /// Initializes the singleton instance backing with the given value.
82    /// Will panic if this is called twice without calling
83    /// `InstanceBacking::finalize` in between.
84    ///
85    /// ## Safety ##
86    ///
87    /// The behavior of this method is undefined when called at the same
88    /// time that `InstanceBacking::as_ref()`/`InstanceBacking::drop_singleton()`
89    /// is being called from a different thread.
90    ///
91    /// In order to keep things safe and straightforward, this method should
92    /// only be called by the implementation of `Instance::new()`.
93    pub(crate) unsafe fn set_singleton(backing: InstanceBacking) {
94        trace!("Setting Singleton InstanceBacking");
95        assert!(Self::glob().replace(backing).is_none(), "Tried to make two OpenThread instances");
96    }
97
98    /// Finalizes and drops the singleton instance backing. After this
99    /// method is called, [`InstacnceBacking::set`] may be called again.
100    ///
101    /// ## Safety ##
102    ///
103    /// The behavior of this method is undefined when called at the same
104    /// time that `InstanceBacking::set_singleton()`/`InstanceBacking::as_ref()`
105    /// is being called from a different thread.
106    ///
107    /// In order to keep things safe and straightforward, this method should
108    /// only be called by the implementation of `Instance::finalize()`.
109    pub(crate) unsafe fn drop_singleton() {
110        trace!("Dropping Singleton InstanceBacking");
111        assert!(Self::glob().take().is_some(), "Tried to drop singleton that was never allocated");
112    }
113}