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 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203
#![deny(warnings)] #![deny(missing_docs)] #![allow(clippy::needless_doctest_main)] #![cfg_attr(feature = "unstable", feature(fn_traits))] #![cfg_attr(feature = "unstable", feature(unboxed_closures))] //! A simple, ergonomic, idiomatic, macro for generating the boilerplate to use rust futures tasks in a concurrent actor style. //! //! # What is GhostActor? //! //! GhostActor boils down to a macro that helps you write all the boilerplate //! needed to treat a Future like an actor. When you "spawn" a GhostActor, //! you receive a handle called a "Sender", that allows you to make async //! requests and inline await async responses to/from you actor implementation's //! driver task. //! //! The senders are cheaply clone-able allowing you to easily execute any //! number of parallel workflows with your task. When all senders are dropped, //! or if you explicitly call `ghost_actor_shutdown()`, the driver task //! (a.k.a. your Actor) will end. //! //! # Example //! //! ``` //! use must_future::*; //! //! #[derive(Debug, thiserror::Error)] //! pub enum MyError { //! #[error(transparent)] //! GhostError(#[from] ghost_actor::GhostError), //! } //! //! ghost_actor::ghost_actor! { //! // Set the visibility of your actor. //! // Name your actor. //! // Specify the Error type for your actor. //! // The error type must implement `From<GhostError>`. //! //! /// Api Docs that should appear on the Sender type for your actor. //! pub actor MyActor<MyError> { //! // specify your actor api //! //! /// This string will be applied as docs to sender/handler. //! fn add_one( //! // any api params here //! input: u32, //! ) -> u32; // return type here //! } //! } //! //! /// An example implementation of the example MyActor GhostActor. //! struct MyActorImpl; //! //! // The generics for a handler are: //! // 1 - the "custom" type you'd like to allow users of your api to send in. //! // 2 - the "internal" type you'd like your handlers to send in. //! // It is highly recommended to use a `ghost_chan!` type for these. //! // However, if you have no use for these capabilities, use `()`. //! impl MyActorHandler<(), ()> for MyActorImpl { //! fn handle_add_one( //! &mut self, //! input: u32, //! ) -> MyActorHandlerResult<u32> { //! Ok(async move { //! Ok(input + 1) //! }.must_box()) //! } //! } //! //! impl MyActorImpl { //! /// Rather than using ghost_actor_spawn directly, use this simple spawn. //! pub async fn spawn() -> MyActorSender { //! use futures::future::FutureExt; //! //! let (sender, driver) = MyActorSender::ghost_actor_spawn(|_internal_sender| { //! async move { //! Ok(MyActorImpl) //! }.must_box() //! }).await.unwrap(); //! //! tokio::task::spawn(driver); //! //! sender //! } //! } //! //! #[tokio::main(threaded_scheduler)] //! async fn main() { //! let mut sender = MyActorImpl::spawn().await; //! //! assert_eq!(43, sender.add_one(42).await.unwrap()); //! //! sender.ghost_actor_shutdown().await.unwrap(); //! //! let res = format!("{:?}", sender.add_one(42).await); //! if &res != "Err(GhostError(SendError(SendError { kind: Disconnected })))" //! && &res != "Err(GhostError(ResponseError(Canceled)))" //! { //! panic!("expected send error"); //! } //! } //! ``` //! //! # Implementing a Handler //! //! The `ghost_actor!` macro is going to generate a "[Name]Handler" trait. //! To provide an implementation for your `ghost_actor!` type, you need an //! item that implements this trait (see example above). //! //! In addition to all the `handle_*` methods that are auto-generated per //! the `Api` section in the macro, there are also provided implementations //! for `handle_ghost_actor_custom` and `handle_ghost_actor_internal`. //! //! Please see any of the unit tests (or run `cargo doc` on a module containing //! your `ghost_actor!` macro invocation) for examples on how to implement //! a handler. //! //! # Implementing a Spawn function //! //! While you can absolutely require users of your api to call //! `YourTypeSender::ghost_actor_spawn(...)` and instantiate your handler type //! inside the callback, it might be polite to provide a function that requires //! a little less boilerplate. //! //! See the example above, however, there may be no need to expose the //! implemented item type at all, you could, for example: //! //! ``` //! # #[derive(Debug, thiserror::Error)] //! # pub enum MyError { //! # #[error(transparent)] //! # GhostError(#[from] ghost_actor::GhostError), //! # } //! # ghost_actor::ghost_actor! { //! # pub actor MyActor<MyError> { //! # fn add_one( //! # input: u32, //! # ) -> u32; //! # } //! # } //! use must_future::*; //! //! /// internal private type //! struct MyActorImpl; //! //! impl MyActorHandler<(), ()> for MyActorImpl { //! // ... //! # fn handle_add_one(&mut self, input: u32) -> MyActorHandlerResult<u32> { //! # unimplemented!(); //! # } //! } //! //! /// Rather than using ghost_actor_spawn directly, use this simple spawn. //! /// This spawn makes an assumption that we are in a tokio runtime, //! /// if we don't want to make that assumption, we can also return the //! /// driver future here. //! pub async fn spawn_my_actor() -> MyActorSender { //! use futures::future::FutureExt; //! //! let (sender, driver) = MyActorSender::ghost_actor_spawn(|_internal_sender| { //! async move { //! Ok(MyActorImpl) //! }.must_box() //! }).await.unwrap(); //! //! tokio::task::spawn(driver); //! //! sender //! } //! # #[tokio::main(threaded_scheduler)] //! # async fn main() { //! # } //! ``` //! //! # The `ghost_chan!` macro. //! //! The `ghost_chan!` macro has an identical API to the `ghost_actor!` macro. //! And, in fact, the `ghost_actor!` macro invokes `ghost_chan!` to produce //! an internal enum for sending messages from your `Sender` struct. //! //! When implementing a ghost actor Handler that will make use of Custom //! and/or Internal types, it is recommended to use a `ghost_chan!` enum as //! this type. //! //! See the unit/integration tests for examples on making use of these. /// Re-exported dependencies to help with macro references. pub mod dependencies { pub use futures; pub use must_future; pub use paste; pub use thiserror; pub use tracing; } mod types; pub use types::*; pub mod ghost_chan; mod r#macro; pub use r#macro::*; mod tests;