diff --git a/src/actor.rs b/src/actor.rs index 1e7b46c..0d84d93 100644 --- a/src/actor.rs +++ b/src/actor.rs @@ -15,7 +15,7 @@ pub trait Message: 'static + Send { /// Describes how to handle messages of a specific type. /// Implementing Handler is a general way to handle incoming messages. -/// The type T is a message which can be handled by the actor. +/// The type `T` is a message which can be handled by the actor. #[async_trait::async_trait] pub trait Handler: Actor where @@ -28,7 +28,7 @@ where /// Describes how to handle messages of a specific type. /// Implementing Handler is a general way to handle incoming streams. /// The type T is a stream message which can be handled by the actor. -/// Stream messages do not need to implement the `Message` trait. +/// Stream messages do not need to implement the [`Message`] trait. #[async_trait::async_trait] #[allow(unused_variables)] pub trait StreamHandler: Actor { @@ -47,13 +47,13 @@ pub trait StreamHandler: Actor { } /// Actors are objects which encapsulate state and behavior. -/// Actors run within a specific execution context `Context`. +/// Actors run within a specific execution context [`Context`]. /// The context object is available only during execution. /// Each actor has a separate execution context. /// /// Roles communicate by exchanging messages. /// The requester can wait for a response. -/// By `Addr` referring to the actors, the actors must provide an `Handle` implementation for this message. +/// By [`Addr`] referring to the actors, the actors must provide an [`Handler`] implementation for this message. /// All messages are statically typed. #[async_trait::async_trait] #[allow(unused_variables)] @@ -68,7 +68,7 @@ pub trait Actor: Sized + Send + 'static { /// Construct and start a new actor, returning its address. /// - /// This is constructs a new actor using the `Default` trait, and invokes its `start` method. + /// This is constructs a new actor using the [`Default`] trait, and invokes its [`start`](`Actor::start`) method. async fn start_default() -> Result> where Self: Default, diff --git a/src/addr.rs b/src/addr.rs index a81c249..8088d23 100644 --- a/src/addr.rs +++ b/src/addr.rs @@ -19,8 +19,8 @@ pub(crate) enum ActorEvent { /// The address of an actor. /// -/// When all references to `Addr` are dropped, the actor ends. -/// You can use `Clone` trait to create multiple copies of `Addr`. +/// When all references to [`Addr`] are dropped, the actor ends. +/// You can use the [`Clone`] trait to create multiple copies of [`Addr`]. pub struct Addr { pub(crate) actor_id: ActorId, pub(crate) tx: Arc>>, @@ -38,6 +38,7 @@ impl Clone for Addr { } impl Addr { + /// Turns an [`Addr`] into a [`WeakAddr`] pub fn downgrade(&self) -> WeakAddr { WeakAddr { actor_id: self.actor_id, @@ -104,7 +105,7 @@ impl Addr { Ok(()) } - /// Create a `Caller` for a specific message type + /// Create a [`Caller`] for a specific message type pub fn caller(&self) -> Caller where A: Handler, @@ -112,7 +113,7 @@ impl Addr { let weak_tx = Arc::downgrade(&self.tx); Caller { - actor_id: self.actor_id.clone(), + actor_id: self.actor_id, caller_fn: Mutex::new(Box::new(move |msg| { let weak_tx_option = weak_tx.upgrade(); Box::pin(async move { @@ -137,14 +138,14 @@ impl Addr { } } - /// Create a `Sender` for a specific message type + /// Create a [`Sender`] for a specific message type pub fn sender>(&self) -> Sender where A: Handler, { let weak_tx = Arc::downgrade(&self.tx); Sender { - actor_id: self.actor_id.clone(), + actor_id: self.actor_id, sender_fn: Box::new(move |msg| match weak_tx.upgrade() { Some(tx) => { mpsc::UnboundedSender::clone(&tx).start_send(ActorEvent::Exec(Box::new( @@ -171,6 +172,10 @@ impl Addr { } } +/// Weak version of [`Addr`]. +/// +/// This address will not prolong the lifetime of the actor. +/// In order to use a [`WeakAddr`] you need to "upgrade" it to a proper [`Addr`]. pub struct WeakAddr { pub(crate) actor_id: ActorId, pub(crate) tx: Weak>>, @@ -190,15 +195,15 @@ impl Hash for WeakAddr { } impl WeakAddr { + /// Attempts to turn a [`WeakAddr`] into an [`Addr`]. + /// + /// If the original [`Addr`] has already been dropped this method will return [`None`] pub fn upgrade(&self) -> Option> { - match self.tx.upgrade() { - Some(tx) => Some(Addr { - actor_id: self.actor_id, - tx, - rx_exit: self.rx_exit.clone(), - }), - None => None, - } + self.tx.upgrade().map(|tx| Addr { + actor_id: self.actor_id, + tx, + rx_exit: self.rx_exit.clone(), + }) } } diff --git a/src/caller.rs b/src/caller.rs index b70a03a..98b65c5 100644 --- a/src/caller.rs +++ b/src/caller.rs @@ -13,9 +13,11 @@ pub(crate) type SenderFn = Box Result<()> + 'static + Send>; /// Caller of a specific message type /// -/// Like `Sender, Caller has a weak reference to the recipient of the message type, and so will not prevent an actor from stopping if all Addr's have been dropped elsewhere. +/// Like [`Sender`], `Caller` has a weak reference to the recipient of the message type, +/// and so will not prevent an actor from stopping if all [`Addr`](`crate::Addr`)'s have been dropped elsewhere. pub struct Caller { + /// Id of the corresponding [`Actor`](crate::Actor) pub actor_id: ActorId, pub(crate) caller_fn: Mutex>, } @@ -40,10 +42,12 @@ impl> Hash for Caller { /// Sender of a specific message type /// -/// Like `Caller, Sender has a weak reference to the recipient of the message type, and so will not prevent an actor from stopping if all Addr's have been dropped elsewhere. -/// This allows it to be used in `send_later` `send_interval` actor functions, and not keep the actor alive indefinitely even after all references to it have been dropped (unless `ctx.stop()` is called from within) +/// Like [`Caller`], Sender has a weak reference to the recipient of the message type, +/// and so will not prevent an actor from stopping if all [`Addr`](`crate::Addr`)'s have been dropped elsewhere. +/// This allows it to be used in the `send_later` and`send_interval` actor functions, /// and not keep the actor alive indefinitely even after all references to it have been dropped (unless `ctx.stop()` is called from within) pub struct Sender { + /// Id of the corresponding [`Actor`](crate::actor::Actor) pub actor_id: ActorId, pub(crate) sender_fn: SenderFn, } diff --git a/src/context.rs b/src/context.rs index fa30be5..3b49df0 100644 --- a/src/context.rs +++ b/src/context.rs @@ -141,7 +141,6 @@ impl Context { /// Ok(()) /// } /// ``` - /// ``` pub fn add_stream(&mut self, mut stream: S) where S: Stream + Unpin + Send + 'static, diff --git a/src/lib.rs b/src/lib.rs index 26343e7..7fe8fa4 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -61,6 +61,7 @@ //! * [Async-std](https://github.com/async-rs/async-std) #![allow(clippy::type_complexity)] +#![warn(clippy::doc_markdown)] mod actor; mod addr; @@ -72,21 +73,25 @@ mod service; mod supervisor; #[cfg(all(feature = "anyhow", feature = "eyre"))] -compile_error!(r#" +compile_error!( + r#" features `xactor/anyhow` and `xactor/eyre` are mutually exclusive. If you are trying to disable anyhow set `default-features = false`. -"#); +"# +); -#[cfg(feature="anyhow")] +#[cfg(feature = "anyhow")] pub use anyhow as error; -#[cfg(feature="eyre")] +#[cfg(feature = "eyre")] pub use eyre as error; -/// Alias of error::Result +#[cfg_attr(feature = "eyre", doc = "Alias of [`eyre::Result`]")] +#[cfg_attr(not(feature = "eyre"), doc = "Alias of [`anyhow::Result`]")] pub type Result = error::Result; -/// Alias of error::Error +#[cfg_attr(feature = "eyre", doc = "Alias of [`eyre::Error`]")] +#[cfg_attr(not(feature = "eyre"), doc = "Alias of [`anyhow::Error`]")] pub type Error = error::Error; pub type ActorId = u64;