Skip to content

Commit

Permalink
chore: renaming Process to Actor
Browse files Browse the repository at this point in the history
  • Loading branch information
vmenge committed Dec 30, 2024
1 parent cf9bfc9 commit 075cc2c
Show file tree
Hide file tree
Showing 22 changed files with 194 additions and 196 deletions.
3 changes: 2 additions & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,2 +1,3 @@
[workspace]
members = ["core"]
members = ["speare"]
resolver = "2"
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
`speare` is a minimalistic actor framework. A thin abstraction over tokio tasks and flume channels with supervision inspired by Akka.NET. Read [The Speare Book](https://vmenge.github.io/speare/) for more details on how to use the library.

## Quick Look
Below is an example of a very minimal `Counter` `Process`.
Below is an example of a very minimal `Counter` `Actor`.

```rust
use speare::*;
Expand All @@ -25,7 +25,7 @@ enum CounterMsg {
}

#[async_trait]
impl Process for Counter {
impl Actor for Counter {
type Props = ();
type Msg = CounterMsg;
type Err = ();
Expand Down
6 changes: 3 additions & 3 deletions book/src/SUMMARY.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Summary

- [Introduction](intro.md)
- [What is a Process?](./what_is_a_process.md)
- [Working with Processes](./wroking_with_processes.md)
- [Process Lifecycle](./process_lifecycle.md)
- [What is an Actor?](./what_is_a_process.md)
- [Working with Actors](./wroking_with_processes.md)
- [Actor Lifecycle](./process_lifecycle.md)
- [Supervision](./supervision.md)
8 changes: 4 additions & 4 deletions book/src/intro.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# Introduction
This guide introduces `speare`, covering `Process` creation, message handling, and essential library features. The objective is to provide clear, concise instructions for effectively utilizing `speare` in your Rust projects.
This guide introduces `speare`, covering `Actor` creation, message handling, and essential library features. The objective is to provide clear, concise instructions for effectively utilizing `speare` in your Rust projects.

## What is `speare`?
`speare` is a Rust library designed to simplify the process of actor-based concurrency. It provides an abstraction over [tokio green threads](https://tokio.rs/tokio/tutorial/spawning#tasks) and [flume channels](https://github.com/zesterer/flume), allowing for easier management of tokio threads and efficient message passing between them. `speare` revolves around a main abstraction: `Process` -- which lives on its own green thread owning its data, reducing the risks of deadlocks and encouraging a modular design. No more `Arc<Mutex<T>>` everywhere :)
`speare` is a Rust library designed to simplify the process of actor-based concurrency. It provides an abstraction over [tokio green threads](https://tokio.rs/tokio/tutorial/spawning#tasks) and [flume channels](https://github.com/zesterer/flume), allowing for easier management of tokio threads and efficient message passing between them. `speare` revolves around a main abstraction: `Actor` -- which lives on its own green thread owning its data, reducing the risks of deadlocks and encouraging a modular design. No more `Arc<Mutex<T>>` everywhere :)

## Quick Look
Below is an example of a very minimal `Counter` `Process`.
Below is an example of a very minimal `Counter` `Actor`.

```rust
use speare::*;
Expand All @@ -23,7 +23,7 @@ enum CounterMsg {
}

#[async_trait]
impl Process for Counter {
impl Actor for Counter {
type Props = ();
type Msg = CounterMsg;
type Err = ();
Expand Down
10 changes: 5 additions & 5 deletions book/src/process_lifecycle.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@
TBD 🏗️

<p hidden>
process lifecycle
- process spawns and lives in memory forever until its stopped
actor lifecycle
- actor spawns and lives in memory forever until its stopped
- stopped by its parent being stopped, by being stopped manually or by its parent supervision strategy
- when a process is spawned, the init method is called to create the process instance
- when a process is stopped the exit method is called.
- when a process is restarted, the exit method is first called, and then the init to create a new instance of the process. the handle remains the same though.
- when a actor is spawned, the init method is called to create the actor instance
- when a actor is stopped the exit method is called.
- when a actor is restarted, the exit method is first called, and then the init to create a new instance of the actor. the handle remains the same though.
</p>
6 changes: 3 additions & 3 deletions book/src/supervision.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@ TBD 🏗️

<p hidden>
supervisoin
- top level processes created by a node are unsupervised
- every process created by another process is superivsed by its parent
- top level actors created by a node are unsupervised
- every actor created by another actor is superivsed by its parent
- supervision means that the parent decide can decide what to do with its children when one of them errors.
- two main strategies, one for one, one for all
- can restart, stop, resume or escalate
- a process will finish handling whatever message it is currently handling before stopping (or restarting) itself
- a actor will finish handling whatever message it is currently handling before stopping (or restarting) itself
</p>
26 changes: 13 additions & 13 deletions book/src/what_is_a_process.md
Original file line number Diff line number Diff line change
@@ -1,39 +1,39 @@
# What is a Process?
A Process is really just a loop that lives in a `tokio::task` together with some state, yielding to the tokio runtime while it waits for a message received via a flume channel which it then uses to modify its state. All `speare` does is provide mechanisms to manage lifecycle, communication and supervision of processes.
# What is a Actor?
A Actor is really just a loop that lives in a `tokio::task` together with some state, yielding to the tokio runtime while it waits for a message received via a flume channel which it then uses to modify its state. All `speare` does is provide mechanisms to manage lifecycle, communication and supervision of actors..

A `Process` is comprised of a few parts:
A `Actor` is comprised of a few parts:
### Trait Implementor
- **State**: the main struct which implements the `Process` trait. The state is mutable and can be modified every time a messaged is received by the `Process`.
- **State**: the main struct which implements the `Actor` trait. The state is mutable and can be modified every time a messaged is received by the `Actor`.

### Associated types
- **Props**: dependencies needed by the struct that implements `Process` for instantiation, configuration or anything in between.
- **Msg**: data received and processed by the `Process`.
- **Err**: the error that can be returned by the process when it fails.
- **Props**: dependencies needed by the struct that implements `Actor` for instantiation, configuration or anything in between.
- **Msg**: data received and processed by the `Actor`.
- **Err**: the error that can be returned by the `Actor` when it fails.

### Trait Functions
- **async fn init**: `(ctx: &mut Ctx<Self>) -> Result<Self, Self::Err>`

*Required*. Used by `speare` to create new instances of your `Process` whenever it is spawned or restarted.
*Required*. Used by `speare` to create new instances of your `Actor` whenever it is spawned or restarted.

- **async fn exit**: `(&mut self, reason: ExitReason<Self>, ctx: &mut Ctx<Self>)`

*Optional*. Called every time your `Process` is stopped, be it manually through its `Handle<_>` or
*Optional*. Called every time your `Actor` is stopped, be it manually through its `Handle<_>` or
by the parent through its [supervision strategy](./supervision.md).

- **handle**: `(&mut self, msg: Self::Msg, ctx: &mut Ctx<Self>) -> Result<(), Self::Err>`

*Optional*. Called when the `Process` receives a message through its channel.
*Optional*. Called when the `Actor` receives a message through its channel.
Messages are **always** processed sequentially.

- **supervision**: `(props: &Self::Props) -> Supervision`

*Optional*. Called before your `Process` is spawned. Used to customize the [supervision strategy](./supervision.md)
*Optional*. Called before your `Actor` is spawned. Used to customize the [supervision strategy](./supervision.md)
for its **children**. If not implemented, the default supervision strategy will
be used: one-for-one infinite restarts without backoff.


## Example
Below is an example of a process making use of all its associated types and trait functions.
Below is an example of a `Actor` making use of all its associated types and trait functions.

```rs
use speare::*;
Expand Down Expand Up @@ -61,7 +61,7 @@ enum CounterErr {
}

#[async_trait]
impl Process for Counter {
impl Actor for Counter {
type Props = CounterProps;
type Msg = CounterMsg;
type Err = CounterErr;
Expand Down
8 changes: 4 additions & 4 deletions book/src/wroking_with_processes.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
TBD 🏗️

<p hidden>
# Working with Processes
- a process can be communicated with through its Handle, which is received once it is spawned
- a process can be spawned from a node as an unsupervised top-level process (more on that later) or spawned from other processes which will be their parent and supervise them.
# Working with Actors
- an actor can be communicated with through its Handle, which is received once it is spawned
- an actor can be spawned from a node as an unsupervised top-level actor (more on that later) or spawned from other actors which will be their parent and supervise them.
- ctx what is it etc
communication between processes
communication between actors
- send and send_in to send messages
- req and req_timeout to send requests
</p>
File renamed without changes.
File renamed without changes.
File renamed without changes.
16 changes: 8 additions & 8 deletions core/src/exit.rs → speare/src/exit.rs
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
use std::{fmt, ops::Deref, sync::Arc};

use crate::Process;
use crate::Actor;

/// A thin wrapper around `Arc<E>` with custom `fmt::Debug` and `fmt::Display`
/// implementations for better error logging.
Expand Down Expand Up @@ -54,22 +54,22 @@ where
}
}

/// Enumerates the reasons why a `Process` might exit.
/// Enumerates the reasons why a [`Actor`] might exit.
pub enum ExitReason<P>
where
P: Process,
P: Actor,
{
/// Process exited due to manual request through a `Handle<P>`
/// [`Actor`] exited due to manual request through a `Handle<_>`
Handle,
/// Process exited due to a request from its Parent process as a part of its supervision strategy.
/// [`Actor`] exited due to a request from its Parent [`Actor`] as a part of its supervision strategy.
Parent,
/// Procss exited due to error.
/// [`Actor`] exited due to error.
Err(SharedErr<P::Err>),
}

impl<P> fmt::Debug for ExitReason<P>
where
P: Process,
P: Actor,
P::Err: fmt::Debug,
{
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
Expand All @@ -83,7 +83,7 @@ where

impl<P> fmt::Display for ExitReason<P>
where
P: Process,
P: Actor,
P::Err: fmt::Display,
{
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
Expand Down
Loading

0 comments on commit 075cc2c

Please sign in to comment.