arbiter 0.5.0

A framework for building distributed systems with actors.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

//! Core components and abstractions for the Arbiter actor framework.
//!
//! This crate provides the foundational types and traits for building
//! actor-based systems with pluggable networking and lifecycle management.

#![allow(refining_impl_trait)]

pub mod actor;
pub mod error;
pub mod handler;
pub mod network;
pub mod processor;
pub mod runtime;

/// A convenient prelude for bringing the most common Arbiter traits and types into scope.
pub mod prelude {
  pub use crate::{
    actor::LifeCycle,
    handler::{Handler, Message},
    network::{Network, Socket},
  };
}

/// Common test fixtures and mock actors used for testing.
#[cfg(any(test, feature = "fixtures"))]
pub mod fixtures {
  use crate::prelude::*;

  /// A simple ping message.
  #[derive(Debug, Clone)]
  pub struct Ping;

  /// A simple pong message.
  #[derive(Debug, Clone)]
  pub struct Pong;

  /// A simple actor that counts every message it receives.
  /// Handles both [`Ping`] and [`Pong`], incrementing `count` for each.
  /// Snapshot is the current count.
  #[derive(Debug, Clone)]
  pub struct Counter {
    pub count: usize,
  }

  impl LifeCycle for Counter {
    type Snapshot = usize;
    type StartMessage = ();
    type StopMessage = ();

    fn on_start(&mut self) -> Self::StartMessage {}

    fn on_stop(&mut self) -> Self::StopMessage {}

    fn snapshot(&self) -> Self::Snapshot { self.count }
  }

  impl Handler<Ping> for Counter {
    type Reply = ();

    fn handle(&mut self, _message: &Ping) -> Option<Self::Reply> {
      self.count += 1;
      tracing::debug!(count = self.count, "Counter received Ping");
      None
    }
  }

  impl Handler<Pong> for Counter {
    type Reply = ();

    fn handle(&mut self, _message: &Pong) -> Option<Self::Reply> {
      self.count += 1;
      tracing::debug!(count = self.count, "Counter received Pong");
      None
    }
  }

  /// Initiates a ping-pong exchange. Sends a [`Ping`] on start, then for
  /// each [`Pong`] received, increments count and replies with [`Ping`].
  /// Stops itself when count reaches `max_count`.
  ///
  /// Snapshot is the current count — ideal for stream-based testing.
  #[derive(Debug, Clone)]
  pub struct PingPlayer {
    pub count:     usize,
    pub max_count: usize,
  }

  impl LifeCycle for PingPlayer {
    type Snapshot = usize;
    type StartMessage = Ping;
    type StopMessage = ();

    fn on_start(&mut self) -> Self::StartMessage { Ping }

    fn on_stop(&mut self) -> Self::StopMessage {}

    fn snapshot(&self) -> Self::Snapshot { self.count }

    fn should_stop(&self) -> bool { self.count >= self.max_count }
  }

  impl Handler<Pong> for PingPlayer {
    type Reply = Ping;

    fn handle(&mut self, _message: &Pong) -> Option<Self::Reply> {
      self.count += 1;
      Some(Ping)
    }
  }

  /// Simple responder: replies [`Pong`] to every [`Ping`].
  /// No meaningful state — just an echo partner.
  #[derive(Debug, Clone)]
  pub struct PongPlayer;

  impl LifeCycle for PongPlayer {
    type Snapshot = ();
    type StartMessage = ();
    type StopMessage = ();

    fn on_start(&mut self) -> Self::StartMessage {}

    fn on_stop(&mut self) -> Self::StopMessage {}

    fn snapshot(&self) -> Self::Snapshot {}
  }

  impl Handler<Ping> for PongPlayer {
    type Reply = Pong;

    fn handle(&mut self, _message: &Ping) -> Option<Self::Reply> { Some(Pong) }
  }
}