Skip to content

Commit

Permalink
Docs/main docs (#61)
Browse files Browse the repository at this point in the history 
* docs: example on main

* release: patch 0.5.2

* refactor: fmt
  • Loading branch information
@wenig
wenig authored Jul 4, 2022
1 parent dbe15bb commit a236ebe
Show file tree
Hide file tree
Showing 5 changed files with 190 additions and 6 deletions.
4 changes: 2 additions & 2 deletions CITATION.cff
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ authors:
given-names: Phillip
orcid: https://orcid.org/0000-0002-8942-4322
title: "Actix-Telepathy"
version: 0.5.1
version: 0.5.2
# doi: ...
date-released: 2022-06-17
date-released: 2022-07-04
url: "https://github.com/wenig/actix-telepathy"
2 changes: 1 addition & 1 deletion Cargo.toml
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[package]
name = "actix-telepathy"
version = "0.5.1"
version = "0.5.2"
authors = ["wenig <info@pwenig.de>"]
edition = "2018"
license = "Apache-2.0"
Expand Down
6 changes: 3 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[![crates.io](https://img.shields.io/crates/v/actix-telepathy?label=latest)](https://crates.io/crates/actix-telepathy)
![Tests on main](https://github.com/wenig/actix-telepathy/workflows/Rust/badge.svg)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Dependency Status](https://deps.rs/crate/actix-telepathy/0.5.0/status.svg)](https://deps.rs/crate/actix-telepathy/0.5.0)
[![Dependency Status](https://deps.rs/crate/actix-telepathy/0.5.2/status.svg)](https://deps.rs/crate/actix-telepathy/0.5.2)
![Downloads](https://img.shields.io/crates/d/actix-telepathy.svg)

# Actix Telepathy
Expand Down Expand Up @@ -29,7 +29,7 @@ So far, we only support single seed nodes. Connecting to different seed nodes ca
```toml
[dependencies]
actix = "0.13"
actix-telepathy = "0.5.0"
actix-telepathy = "0.5.2"
```

### main.rs
Expand Down Expand Up @@ -61,7 +61,7 @@ async fn main() {
month = {6},
title = {{Actix-Telepathy}},
url = {https://github.com/wenig/actix-telepathy},
version = {0.5.1},
version = {0.5.2},
year = {2022}
}
```
182 changes: 182 additions & 0 deletions src/lib.rs
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,185 @@
//! Actix-Telepathy is an extension to [Actix](https://docs.rs/actix) that enables remote messaging and clustering support.
//!
//! Telepathy does not change Actix' messaging system but _extends_ the
//!
//! - [actix::Actor](https://docs.rs/actix/latest/actix/trait.Actor.html) with the [RemoteActor](./trait.RemoteActor.html) trait and the
//! - [actix::Message](https://docs.rs/actix/latest/actix/trait.Message.html) with the [RemoteMessage](./trait.RemoteMessage.html) trait.
//!
//! Hence, an example actor receiving a remote message is defined as follows.
//! To connect multiple computers in a cluster, a [Cluster](./struct.Cluster.html) must be generated.
//!
//! ```rust
//! use actix::prelude::*;
//! use actix_broker::BrokerSubscribe;
//! use actix_telepathy::prelude::*; // <-- Telepathy extension
//! use serde::{Serialize, Deserialize};
//! use std::net::SocketAddr;
//!
//! #[derive(RemoteMessage, Serialize, Deserialize)] // <-- Telepathy extension
//! struct MyMessage {}
//!
//! #[derive(RemoteActor)] // <-- Telepathy extension
//! #[remote_messages(MyMessage)] // <-- Telepathy extension
//! struct MyActor {
//! state: usize
//! }
//!
//! impl Actor for MyActor {
//! type Context = Context<Self>;
//!
//! fn started(&mut self, ctx: &mut Self::Context) {
//! self.register(ctx.address().recipient()); // <-- Telepathy extension
//! }
//! }
//!
//! impl Handler<MyMessage> for MyActor {
//! type Result = ();
//!
//! fn handle(&mut self, msg: MyMessage, ctx: &mut Self::Context) -> Self::Result {
//! todo!()
//! }
//! }
//!
//! #[actix_rt::main]
//! pub async fn start_cluster(own_addr: SocketAddr, seed_nodes: Vec<SocketAddr>) {
//! let _addr = MyActor { state: 0 }.start();
//! let _cluster = Cluster::new(own_addr, seed_nodes);
//! tokio::time::sleep(std::time::Duration::from_secs(5)).await;
//! }
//!
//! ```
//!
//! The previous example will not do anything. However, the cluster will try to connect to the given addresses in `seed_nodes`.
//! To react to new joining members, a [ClusterListener](./trait.ClusterListener.html) actor should be used:
//!
//! ```rust
//! use actix::prelude::*;
//! use actix_broker::BrokerSubscribe;
//! use actix_telepathy::prelude::*; // <-- Telepathy extension
//! use serde::{Serialize, Deserialize};
//! use std::net::SocketAddr;
//!
//! #[derive(RemoteMessage, Serialize, Deserialize)] // <-- Telepathy extension
//! struct MyMessage {}
//!
//! #[derive(RemoteActor)] // <-- Telepathy extension
//! #[remote_messages(MyMessage)] // <-- Telepathy extension
//! struct MyActor {
//! state: usize
//! }
//!
//! impl Actor for MyActor {
//! type Context = Context<Self>;
//!
//! fn started(&mut self, ctx: &mut Self::Context) {
//! self.register(ctx.address().recipient()); // <-- Telepathy extension
//! self.subscribe_system_async::<ClusterLog>(ctx); // <-- Telepathy extension
//! }
//! }
//!
//! impl Handler<MyMessage> for MyActor {
//! type Result = ();
//!
//! fn handle(&mut self, msg: MyMessage, ctx: &mut Self::Context) -> Self::Result {
//! todo!()
//! }
//! }
//!
//! impl Handler<ClusterLog> for MyActor { // <-- Telepathy extension
//! type Result = ();
//!
//! fn handle(&mut self, msg: ClusterLog, ctx: &mut Self::Context) -> Self::Result {
//! match msg {
//! ClusterLog::NewMember(_ip_addr, _remote_addr) => {
//! println!("New member joined the cluster.")
//! },
//! ClusterLog::MemberLeft(_ip_addr) => {
//! println!("Member left the cluster.")
//! }
//! }
//! }
//! }
//! impl ClusterListener for MyActor {} // <-- Telepathy extension
//!
//! #[actix_rt::main]
//! pub async fn start_cluster(own_addr: SocketAddr, seed_nodes: Vec<SocketAddr>) {
//! let _addr = MyActor { state: 0 }.start();
//! let _cluster = Cluster::new(own_addr, seed_nodes); // <-- Telepathy extension
//! tokio::time::sleep(std::time::Duration::from_secs(5)).await;
//! }
//!
//! ```
//!
//! Now, we receive a printed message whenever a new member joins the cluster or when a member leaves.
//! To send messages between remote actors to other members in the cluster, we have to utilize the
//! [RemoteAddr](./struct.RemoteAddr.html) that the [ClusterListener](./trait.ClusterListener.html) receives.
//!
//! ```rust
//! use actix::prelude::*;
//! use actix_broker::BrokerSubscribe;
//! use actix_telepathy::prelude::*; // <-- Telepathy extension
//! use serde::{Serialize, Deserialize};
//! use std::net::SocketAddr;
//!
//! #[derive(RemoteMessage, Serialize, Deserialize)] // <-- Telepathy extension
//! struct MyMessage {}
//!
//! #[derive(RemoteActor)] // <-- Telepathy extension
//! #[remote_messages(MyMessage)] // <-- Telepathy extension
//! struct MyActor {
//! state: usize
//! }
//!
//! impl Actor for MyActor {
//! type Context = Context<Self>;
//!
//! fn started(&mut self, ctx: &mut Self::Context) {
//! self.register(ctx.address().recipient()); // <-- Telepathy extension
//! self.subscribe_system_async::<ClusterLog>(ctx); // <-- Telepathy extension
//! }
//! }
//!
//! impl Handler<MyMessage> for MyActor {
//! type Result = ();
//!
//! fn handle(&mut self, msg: MyMessage, ctx: &mut Self::Context) -> Self::Result {
//! println!("RemoteMessage received!")
//! }
//! }
//!
//! impl Handler<ClusterLog> for MyActor { // <-- Telepathy extension
//! type Result = ();
//!
//! fn handle(&mut self, msg: ClusterLog, ctx: &mut Self::Context) -> Self::Result {
//! match msg {
//! ClusterLog::NewMember(_ip_addr, mut remote_addr) => {
//! println!("New member joined the cluster.");
//! remote_addr.change_id(Self::ACTOR_ID.to_string());
//! remote_addr.do_send(MyMessage {})
//! },
//! ClusterLog::MemberLeft(_ip_addr) => {
//! println!("Member left the cluster.")
//! }
//! }
//! }
//! }
//! impl ClusterListener for MyActor {} // <-- Telepathy extension
//!
//! #[actix_rt::main]
//! pub async fn start_cluster(own_addr: SocketAddr, seed_nodes: Vec<SocketAddr>) {
//! let _addr = MyActor { state: 0 }.start();
//! let _cluster = Cluster::new(own_addr, seed_nodes); // <-- Telepathy extension
//! tokio::time::sleep(std::time::Duration::from_secs(5)).await;
//! }
//!
//! ```
//!
//! Now, every new member receives a `MyMessage` from every [ClusterListener](./trait.ClusterListener.html) in the cluster.
//!
//! Before we could use the [RemoteAddr](./struct.RemoteAddr.html), we had to make sure, that it is pointing to the correct [RemoteActor](./trait.RemoteActor.html), which is `MyActor` in that case.
//! Therefore, we had to call `change_id` on the [RemoteAddr](./struct.RemoteAddr.html). A [RemoteAddr](./struct.RemoteAddr.html) points to a specific actor on a remote machine.
//! Per default, this is the [NetworkInterface](./struct.NetworkInterface.html) actor.
#[cfg(feature = "derive")]
pub use actix_telepathy_derive::*;
#[cfg(feature = "protocols")]
Expand Down
2 changes: 2 additions & 0 deletions src/remote/addr/resolver.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,8 @@ impl Debug for NotAvailableError {
}
}

/// A system actor that can resolve `ACTOR_ID`s to [actix::Addr](https://docs.rs/actix/latest/actix/struct.Addr.html)s
/// by sending an [AddrRequest](./enum.AddrRequest.html).
impl AddrResolver {
pub fn new() -> Self {
AddrResolver::default()
Expand Down

0 comments on commit a236ebe

Please sign in to comment.