heph 0.4.0

Heph is an actor framework based on asynchronous functions.
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
134
135
136
137
138
139
140
141
142
143
144
145
146
147

//! Standardised messages.
//!
//! To use these message the receiving actor should implement [`From`]`<Message>`,
//! this way the sending actor can simply send the message, without having to
//! wrap it in a message type first. See the examples below.
//!
//! Most message types have an optional id, defaulting to `()`. This allows a
//! single actor to receive messages from multiple sources with the ability to
//! differentiate the source of the message.
//!
//! Three more default messages should be considered, the two variants from
//! [`Result`]: [`Ok`] and [`Err`]. Lastly there is the `Signal` type from the
//! `heph-rt` crate to handle process signals.
//!
//! # Examples
//!
//! Implementing `From<Message>` to allow for easy sending of messages.
//!
//! ```
//! use heph::messages::Ack;
//!
//! #[derive(Debug, Eq, PartialEq)]
//! struct OK;
//!
//! #[derive(Debug, Eq, PartialEq)]
//! struct Error;
//!
//! /// The message type for the coordinating actor.
//! #[derive(Debug, Eq, PartialEq)]
//! enum Message {
//!     /// Acknowledgement of receiving an message.
//!     Ack(usize),
//!     /// An ok result.
//!     Ok(OK),
//!     /// An erroneous result.
//!     Error(Error),
//! }
//!
//! // This allows us to receive an `Ack` message.
//! impl From<Ack<usize>> for Message {
//!     fn from(ack: Ack<usize>) -> Message {
//!         Message::Ack(ack.0)
//!     }
//! }
//!
//! // Abilities to receive an result from a working actor.
//! impl From<Result<OK, Error>> for Message {
//!     fn from(res: Result<OK, Error>) -> Message {
//!         match res {
//!             Ok(ok) => Message::Ok(ok),
//!             Err(err) => Message::Error(err),
//!         }
//!     }
//! }
//! #
//! # drop(Message::Ack(0));
//! ```

/// A start signal
///
/// Useful for example when you want to delay the start of an actor. This
/// message has an optional id.
#[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd)]
#[repr(transparent)]
pub struct Start<Id = ()>(pub Id);

/// An acknowledgement.
///
/// Useful for example when you want to know if a message was received. This
/// message has an optional id.
#[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd)]
#[repr(transparent)]
pub struct Ack<Id = ()>(pub Id);

/// Signal to an actor that we're done.
///
/// This message has an optional id.
#[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd)]
#[repr(transparent)]
pub struct Done<Id = ()>(pub Id);

/// Signal to an actor to cancel an operation.
///
/// This message has an optional id.
#[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd)]
#[repr(transparent)]
pub struct Cancel<Id = ()>(pub Id);

/// Ask an actor to terminate.
///
/// # Notes
///
/// This message is not special in anyway, this means the receiving actor can
/// simply ignore this message and continue running.
#[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd)]
pub struct Terminate;

/// Macro to implement [`From`] for an enum message type.
///
/// # Examples
///
/// ```
/// # #[allow(dead_code)]
/// use heph::actor_ref::RpcMessage;
/// use heph::from_message;
///
/// #[derive(Debug)]
/// enum Message {
///     Msg(String),
///     Rpc(RpcMessage<String, usize>),
///     Rpc2(RpcMessage<(String, usize), (usize, usize)>),
/// }
///
/// // This implements `From<String>` for `Message`.
/// from_message!(Message::Msg(String));
///
/// // RPC is also supported:
/// from_message!(Message::Rpc(String) -> usize);
/// from_message!(Message::Rpc2(String, usize) -> (usize, usize));
/// ```
#[macro_export]
macro_rules! from_message {
    // Single field message.
    ($name: ident :: $variant: ident ( $ty: ty )) => {
        impl From<$ty> for $name {
            fn from(msg: $ty) -> $name {
                $name::$variant(msg)
            }
        }
    };
    // Single field RPC.
    ($name: ident :: $variant: ident ( $ty: ty ) -> $return_ty: ty) => {
        impl From<$crate::actor_ref::rpc::RpcMessage<$ty, $return_ty>> for $name {
            fn from(msg: $crate::actor_ref::rpc::RpcMessage<$ty, $return_ty>) -> $name {
                $name::$variant(msg)
            }
        }
    };
    // Multiple values RPC, for which we use the tuple format.
    ($name: ident :: $variant: ident ( $( $ty: ty ),+ ) -> $return_ty: ty) => {
        impl From<$crate::actor_ref::rpc::RpcMessage<( $( $ty ),+ ), $return_ty>> for $name {
            fn from(msg: $crate::actor_ref::rpc::RpcMessage<( $( $ty ),+ ), $return_ty>) -> $name {
                $name::$variant(msg)
            }
        }
    };
}