From b0d36194e7947ef05c4942a4ce234fc6eee20fcd Mon Sep 17 00:00:00 2001 From: Hendrik Sollich Date: Fri, 8 Oct 2021 18:13:23 +0200 Subject: [PATCH 1/2] docs: fix some documentation links --- src/addr.rs | 8 ++++---- src/caller.rs | 6 ++++-- src/context.rs | 1 - 3 files changed, 8 insertions(+), 7 deletions(-) diff --git a/src/addr.rs b/src/addr.rs index a81c249..ab8a6f2 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>>, @@ -104,7 +104,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, @@ -137,7 +137,7 @@ 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, diff --git a/src/caller.rs b/src/caller.rs index b70a03a..e81fb96 100644 --- a/src/caller.rs +++ b/src/caller.rs @@ -13,7 +13,8 @@ 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 { pub actor_id: ActorId, @@ -40,7 +41,8 @@ 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. +/// 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 `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) pub struct Sender { 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, From 0d0dda34d52bae7f38a7395c6d578f3656917aeb Mon Sep 17 00:00:00 2001 From: Hendrik Sollich Date: Fri, 8 Oct 2021 18:14:58 +0200 Subject: [PATCH 2/2] chore: satisfy clippy --- src/actor.rs | 10 +++++----- src/addr.rs | 25 +++++++++++++++---------- src/caller.rs | 4 +++- src/lib.rs | 17 +++++++++++------ 4 files changed, 34 insertions(+), 22 deletions(-) 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 ab8a6f2..8088d23 100644 --- a/src/addr.rs +++ b/src/addr.rs @@ -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, @@ -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 { @@ -144,7 +145,7 @@ impl Addr { { 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 e81fb96..98b65c5 100644 --- a/src/caller.rs +++ b/src/caller.rs @@ -17,6 +17,7 @@ pub(crate) type SenderFn = Box Result<()> + 'static + Send>; /// 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>, } @@ -43,9 +44,10 @@ impl> Hash for Caller { /// /// 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 `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) +/// 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/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;