acton_core/common/
agent_reply.rs

1/*
2 * Copyright (c) 2024. Govcraft
3 *
4 * Licensed under either of
5 *   * Apache License, Version 2.0 (the "License");
6 *     you may not use this file except in compliance with the License.
7 *     You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
8 *   * MIT license: http://opensource.org/licenses/MIT
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the applicable License for the specific language governing permissions and
14 * limitations under that License.
15 */
16
17//! Convenient boxed future replies for agents using old or new style handlers
18
19use std::future::Future;
20use std::pin::Pin;
21
22/// A utility namespace for creating standard return types for `act_on` message handlers.
23///
24/// Message handlers registered with [`ManagedAgent::act_on`](crate::actor::ManagedAgent::act_on)
25/// typically need to return a future that is boxed and pinned, specifically [`FutureBox`].
26/// This struct provides helpers to create common future types that might be needed
27/// as part of that process.
28///
29/// It acts purely as a namespace and is not intended to be instantiated.
30pub struct AgentReply;
31
32impl AgentReply {
33    /// Creates an immediately resolving, no-operation future, boxed and pinned.
34    ///
35    /// This is useful for message handlers that perform synchronous work or do not need
36    /// to perform any asynchronous operations after processing the message.
37    ///
38    /// # Returns
39    ///
40    /// A `Pin<Box<impl Future<Output=()>>>` that completes immediately. This can often
41    /// be coerced or converted into the required [`FutureBox`].
42    #[inline]
43    pub fn immediate() -> Pin<Box<impl Future<Output = ()> + Sized>> {
44        // Original return type
45        Box::pin(async move {})
46    }
47
48    /// Wraps an existing future into a `Pin<Box<F>>`.
49    ///
50    /// This method takes any future `F` with `Output=()` and boxes and pins it.
51    /// This is often a necessary step before potentially casting or using it where
52    /// a [`FutureBox`] is expected, provided `F` meets the `Send + Sync + 'static` bounds.
53    ///
54    /// # Type Parameters
55    ///
56    /// * `F`: The type of the input future. Must have `Output=()`.
57    ///
58    /// # Arguments
59    ///
60    /// * `future`: The future to be wrapped.
61    ///
62    /// # Returns
63    ///
64    /// A `Pin<Box<F>>` containing the provided future.
65    #[inline]
66    pub fn from_async<F>(future: F) -> Pin<Box<F>>
67    // Original return type
68    where
69        F: Future<Output = ()> + Sized, // Original bounds
70    {
71        Box::pin(future)
72    }
73}
acton_core/common/agent_reply.rs

acton_core/common/
agent_reply.rs
