Added documentation for aktoro-runtime.

Author: r3v2d0g

aktoro-raw/src/spawned.rs

@@ -22,6 +22,9 @@ type ControllerError<A> = <Controller<A> as RawController<A>>::Error;
 
 type Updated<A> = <<<A as Actor>::Context as Context<A>>::Updater as Updater<A>>::Updated;
 
+/// A wrapper around an actor's
+/// message, control and update
+/// channels.
 pub struct Spawned<A: Actor> {
     sender: Sender<A>,
     ctrler: Controller<A>,
@@ -31,11 +34,6 @@ pub struct Spawned<A: Actor> {
 impl<A: Actor> Spawned<A> {
     /// Creates a new `Spawned` struct from an actor's
     /// context.
-    ///
-    /// ## Note
-    ///
-    /// This should only be used by a runtime after
-    /// an actor has finished starting.
     pub fn new(ctx: &mut A::Context) -> Spawned<A> {
         Spawned {
             sender: ctx.sender().clone(),

aktoro-runtime/src/actor.rs

@@ -25,11 +25,35 @@ pub(crate) struct Actor<A: raw::Actor> {
 }
 
 #[derive(Eq, PartialEq, Debug, Clone)]
+/// A default implementation for the
+/// [`aktoro-raw::Status`] trait.
+///
+/// [`aktoro-raw::Status`]: https://docs.rs/aktoro-raw/struct.Status.html
 pub enum Status {
+    /// The status that an actor should have
+    /// before [`Actor::starting`] is called.
+    ///
+    /// [`Actor::starting`]: https://docs.rs/aktoro-raw/trait.Actor.html#method.starting
     Starting,
+    /// The status that an actor should have
+    /// before [`Actor::started`] is called.
+    ///
+    /// [`Actor::started`]: https://docs.rs/aktoro-raw/trait.Actor.html#method.started
     Started,
+    /// The status that an actor should have
+    /// before [`Actor::stopping`] is called.
+    ///
+    /// [`Actor::stopped`]: https://docs.rs/aktoro-raw/trait.Actor.html#method.stopping
     Stopping,
+    /// The status that an actor should have
+    /// before [`Actor::stopped`] is called.
+    ///
+    /// [`Actor::stopped`]: https://docs.rs/aktoro-raw/trait.Actor.html#method.stopped
     Stopped,
+    /// The status that an actor has after
+    /// [`Actor::stopped`] has been called.
+    ///
+    /// [`Actor::stopped`]: https://docs.rs/aktoro-raw/trait.Actor.html#method.stropped
     Dead,
 }
 
@@ -64,22 +88,35 @@ impl<A: raw::Actor> Actor<A> {
         killed: KilledSender,
         mut ctx: A::Context,
     ) -> Option<Self> {
+        // Sets the actor's status as starting
+        // and call the `starting` method on it.
         ctx.set_status(A::Status::starting());
         act.starting(&mut ctx);
 
+        // If the actor has decided to stop
+        // gracefully, we call its
+        // `stopping` method.
         if ctx.status().is_stopping() {
             act.stopping(&mut ctx);
 
-            if ctx.status().is_stopped() {
+            // If it has stopped, we set
+            // its status as stopped.
+            if ctx.status().is_stopping() {
                 ctx.set_status(A::Status::stopped());
             }
         }
 
+        // If the actor's status is marked
+        // as stopped, we call its `stopped`
+        // method and change its status
+        // as dead.
         if ctx.status().is_stopped() {
             act.stopped(&mut ctx);
             ctx.set_status(A::Status::dead());
         }
 
+        // If the actor is dead, we don't
+        // spawn it in the background.
         if ctx.status().is_dead() {
             return None;
         }
@@ -94,13 +131,21 @@ impl<A: raw::Actor> Actor<A> {
         })
     }
 
+    /// Marks the actor as dead.
     fn dead(&mut self) -> Result<(), Error> {
+        // We set the actor's status as
+        // dead.
         self.ctx.set_status(A::Status::dead());
 
+        // We try to push the actor's
+        // new status over its update
+        // channel.
         if let Err(err) = self.ctx.update() {
             return Err(Box::new(err).into());
         }
 
+        // We try to notify the actor's
+        // death over the killed channel.
         if let Err(err) = self.killed.killed(self.id) {
             return Err(Box::new(err).into());
         }
@@ -152,6 +197,8 @@ impl raw::Status for Status {
 }
 
 impl KillSender {
+    /// Kills the actor by sending a
+    /// message over its kill channel.
     pub(crate) fn kill(&mut self) {
         if let Some(notify) = self.0.take() {
             notify.done();
@@ -161,6 +208,7 @@ impl KillSender {
 }
 
 impl KilledSender {
+    /// Notifies that the actor died.
     fn killed(&mut self, id: u64) -> Result<(), TrySendError<u64>> {
         self.0.try_send(id)
     }
@@ -173,51 +221,79 @@ impl<A: raw::Actor> Future for Actor<A> {
         let actor = self.get_mut();
 
         loop {
+            // If the actor has been asked
+            // to die, we kill it.
             match Pin::new(&mut actor.kill).poll(ctx) {
                 Poll::Ready(()) => actor.act.stopped(&mut actor.ctx),
                 Poll::Pending => (),
             }
 
+            // If the actor's status is marked
+            // as stopping, we call `stopping`
+            // on it.
             if actor.ctx.status().is_stopping() {
                 actor.act.stopping(&mut actor.ctx);
 
+                // If the actor's status hasn't
+                // changed, we set it as stopped.
                 if actor.ctx.status().is_stopping() {
                     actor.ctx.set_status(A::Status::stopped());
                 }
             }
 
+            // If the actor's status is marked
+            // as stopped, we call `stopped`
+            // ont it and notify that the actor
+            // is dead over the killed channel.
             if actor.ctx.status().is_stopped() {
                 actor.act.stopped(&mut actor.ctx);
                 return Poll::Ready(actor.dead());
             }
 
+            // If the actor's status is marked
+            // as dead, we notify that the actor
+            // is dead over the killed channel.
             if actor.ctx.status().is_dead() {
                 return Poll::Ready(actor.dead());
             }
 
+            // If `started` hasn't been called
+            // on the actor, we call it.
             if !actor.started {
                 actor.ctx.set_status(A::Status::started());
                 actor.act.started(&mut actor.ctx);
+                // We save that the actor's
+                // `started` method has been
+                // called.
                 actor.started = true;
                 continue;
             }
 
             match Pin::new(&mut actor.ctx).poll_next(ctx) {
                 Poll::Ready(Some(work)) => match work {
+                    // If the context received an
+                    // action for the actor to handle,
+                    // we do so.
                     raw::Work::Action(mut action) => {
                         if let Err(err) = action.handle(&mut actor.act, &mut actor.ctx) {
                             return Poll::Ready(Err(Error::std(err).add_res(actor.dead())));
                         }
 
                         continue;
                     }
+                    // If the context has been asked
+                    // to get an event handled by the
+                    // actor, we do so.
                     raw::Work::Event(mut event) => {
                         if let Err(err) = event.handle(&mut actor.act, &mut actor.ctx) {
                             return Poll::Ready(Err(Error::std(err).add_res(actor.dead())));
                         }
 
                         continue;
                     }
+                    // If the context has received a
+                    // message for the actor to handle,
+                    // we do so.
                     raw::Work::Message(mut msg) => {
                         if let Err(err) = msg.handle(&mut actor.act, &mut actor.ctx) {
                             return Poll::Ready(Err(Error::std(err).add_res(actor.dead())));
@@ -227,6 +303,10 @@ impl<A: raw::Actor> Future for Actor<A> {
                     }
                     raw::Work::Update => continue,
                 },
+                // If the actor's context `Work`
+                // stream has been closed, we
+                // change the actor's status as
+                // being stopped.
                 Poll::Ready(None) => {
                     actor.ctx.set_status(A::Status::stopped());
                     continue;

aktoro-runtime/src/runtime.rs

@@ -18,21 +18,42 @@ use crate::actor::KilledRecver;
 use crate::actor::KilledSender;
 use crate::error::Error;
 
+/// An actor runtime using the [`runtime`]
+///
+/// [`runtime`]: https://docs.rs/crates/runtime
 pub struct Runtime {
+    /// A map matching an actor's ID with
+    /// a sender for its kill channel.
     actors: FnvHashMap<u64, Kill>,
+    /// A sender for the actors' killed
+    /// channel (it will be cloned and
+    /// passed to all new actors).
     sender: KilledSender,
+    /// A receiver the the actors' killed
+    /// channel, notified when an actor
+    /// has stopped/been killed.
     recver: KilledRecver,
+    /// A fast (non-cryptographic) random
+    /// number generator.
     rng: Xoshiro512StarStar,
 }
 
+/// A future that resolves when all the
+/// runtime's actors have been stopped.
 pub struct Stop(Wait);
 
+/// A future that resolves when all the
+/// runtime's actors have been stopped.
 pub struct Wait {
     rt: Runtime,
+    /// Contains a list of all the errors
+    /// that happened while waiting for
+    /// the actors to stop.
     errors: Vec<Error>,
 }
 
 impl Runtime {
+    /// Creates a new `Runtime`.
     pub fn new() -> Self {
         Runtime::default()
     }
@@ -45,24 +66,35 @@ impl raw::Runtime for Runtime {
     type Error = Error;
 
     fn spawn<A: raw::Actor>(&mut self, actor: A) -> Option<raw::Spawned<A>> {
+        // Create a new context for the actor.
         let mut ctx = A::Context::new();
 
+        // Create a new `Spawned` struct from
+        // the actor's context.
         let spawned = raw::Spawned::new(&mut ctx);
 
+        // Generate the actor's ID.
         let id = self.rng.next_u64();
 
+        // Create the actor's kill channel.
         let (sender, recver) = actor::new_kill();
 
+        // Try to create the actor (fails if
+        // it refused to start).
         let actor = Actor::new(id, actor, recver, self.sender.clone(), ctx)?;
 
+        // Save the actor's kill channel's
+        // sender.
         self.actors.insert(id, sender);
 
+        // Spawn the actor.
         runtime::spawn(actor);
 
         Some(spawned)
     }
 
     fn stop(mut self) -> Stop {
+        // Ask for each actor to stop.
         for (_, actor) in self.actors.iter_mut() {
             actor.kill();
         }
@@ -82,6 +114,11 @@ impl Future for Stop {
     type Output = Result<(), Error>;
 
     fn poll(self: Pin<&mut Self>, ctx: &mut FutContext) -> Poll<Result<(), Error>> {
+        // `Stop` is just a wrapper
+        // arround `Wait` (what differs
+        // is what happens before it
+        // is returned by the `stop`
+        // method).
         Pin::new(&mut self.get_mut().0).poll(ctx)
     }
 }
@@ -98,12 +135,16 @@ impl Future for Wait {
                 return Poll::Ready(Ok(()));
             }
 
+            // We try to poll from the actors'
+            // kill channel's receiver.
             match Pin::new(&mut rt.recver).poll_next(ctx) {
                 Poll::Ready(Some(actor)) => {
                     if rt.actors.remove(&actor).is_none() {
                         wait.errors.push(Error::already_removed(actor));
                     }
                 }
+                // If the channel has been closed,
+                // we stop the future.
                 Poll::Ready(None) => {
                     if wait.errors.len() > 1 {
                         return Poll::Ready(Err(Error::multiple(wait.errors.split_off(0))));