settings/
agent.rs

1// Copyright 2019 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 crate::base::SettingType;
6use crate::message::base::MessengerType;
7use crate::service::message::Receptor;
8use crate::service_context::ServiceContext;
9use crate::{event, payload_convert, service};
10
11use futures::future::LocalBoxFuture;
12use std::collections::HashSet;
13use std::fmt::Debug;
14use std::rc::Rc;
15use thiserror::Error;
16
17/// Agent for watching the camera3 status.
18pub(crate) mod camera_watcher;
19
20/// Agent for handling media button input.
21pub(crate) mod media_buttons;
22
23/// This mod provides a concrete implementation of the agent authority.
24pub(crate) mod authority;
25
26/// Agent for rehydrating actions for restore.
27pub(crate) mod restore_agent;
28
29/// Agent for managing access to storage.
30pub(crate) mod storage_agent;
31
32/// Earcons.
33pub(crate) mod earcons;
34
35/// Inspect agents.
36pub(crate) mod inspect;
37
38#[derive(Error, Debug, Clone, Copy, PartialEq)]
39pub enum AgentError {
40    #[error("Unhandled Lifespan")]
41    UnhandledLifespan,
42    #[error("Unexpected Error")]
43    UnexpectedError,
44}
45
46pub(crate) type InvocationResult = Result<(), AgentError>;
47
48/// The scope of an agent's life. Initialization components should
49/// only run at the beginning of the service. Service components follow
50/// initialization and run for the duration of the service.
51#[derive(Clone, Copy, Debug, PartialEq)]
52pub(crate) enum Lifespan {
53    Initialization,
54    Service,
55}
56
57/// Struct of information passed to the agent during each invocation.
58#[derive(Clone)]
59pub struct Invocation {
60    pub(crate) lifespan: Lifespan,
61    pub(crate) service_context: Rc<ServiceContext>,
62}
63
64impl Debug for Invocation {
65    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
66        f.debug_struct("Invocation").field("lifespan", &self.lifespan).finish_non_exhaustive()
67    }
68}
69
70impl PartialEq for Invocation {
71    fn eq(&self, other: &Self) -> bool {
72        self.lifespan == other.lifespan
73    }
74}
75
76pub type AgentFuture = LocalBoxFuture<'static, ()>;
77
78/// Supported types of [Agent] creation functions.
79pub enum CreationFunc {
80    /// A simple wrapper around a static creation function.
81    ///
82    /// Example usage:
83    /// ```no_run
84    /// async fn create(c: Context) { }
85    /// let f = CreationFunc::Static(|c| Box::Pin(example::create(c));
86    /// ```
87    Static(fn(Context) -> AgentFuture),
88    /// Used for more complicate creation functions that need to capture state.
89    ///
90    /// Example usage:
91    /// ```no_run
92    /// let shared = Rc::new(Mutex::new(0u));
93    /// let f = CreationFunc::Dynamic(Rc::new(move |c| -> AgentFuture {
94    ///     let shared = Rc::clone(&shared);
95    ///     Box::pin(async move {
96    ///         *shared.lock().await = 42;
97    ///     })
98    /// }));
99    /// ```
100    Dynamic(Rc<dyn Fn(Context) -> AgentFuture>),
101}
102
103/// AgentCreator provides a simple wrapper for an async Agent creation function.
104pub struct AgentCreator {
105    pub debug_id: &'static str,
106    pub create: CreationFunc,
107}
108
109impl AgentCreator {
110    pub(crate) fn create(&self, context: Context) -> AgentFuture {
111        match &self.create {
112            CreationFunc::Static(f) => (f)(context),
113            CreationFunc::Dynamic(f) => (f)(context),
114        }
115    }
116}
117
118/// Agent Context contains necessary parts to create an agent.
119pub struct Context {
120    /// The receivor end to receive messages.
121    pub receptor: Receptor,
122
123    /// Publishers are used to publish events.
124    publisher: event::Publisher,
125
126    /// Delegates are used to create new messengers.
127    pub delegate: service::message::Delegate,
128
129    /// Indicates available Settings interfaces.
130    pub(crate) available_components: HashSet<SettingType>,
131}
132
133impl Context {
134    pub(crate) async fn new(
135        receptor: Receptor,
136        delegate: service::message::Delegate,
137        available_components: HashSet<SettingType>,
138    ) -> Self {
139        let publisher = event::Publisher::create(&delegate, MessengerType::Unbound).await;
140        Self { receptor, publisher, delegate, available_components }
141    }
142
143    /// Generates a new `Messenger` on the service `MessageHub`. Only
144    /// top-level messages can be sent, not received, as the associated
145    /// `Receptor` is discarded.
146    async fn create_messenger(
147        &self,
148    ) -> Result<service::message::Messenger, service::message::MessageError> {
149        Ok(self.delegate.create(MessengerType::Unbound).await?.0)
150    }
151
152    pub(crate) fn get_publisher(&self) -> event::Publisher {
153        self.publisher.clone()
154    }
155}
156
157#[derive(Clone, Debug, PartialEq)]
158pub enum Payload {
159    Invocation(Invocation),
160    Complete(InvocationResult),
161}
162
163payload_convert!(Agent, Payload);
settings/agent.rs

settings/
agent.rs
