actix_signal/
lib.rs

1//! Manage the lifecycle of an actix actor with its address.
2//!
3//! If you want to stop/terminate an actor, you call [`ActorContext::stop`](actix::ActorContext::stop) or
4//! [`ActorContext::terminate`](actix::ActorContext::terminate) within its execution context.
5//!
6//! However, sometimes you have access to its address only. This crate adds a bunch of methods to the address so that
7//! you may [stop](AddrSignalExt::stop) or [terminate](AddrSignalExt::terminate) the actor outside its running context.
8//!
9//! *Minimum supported rust version: 1.50.0*
10//!
11//! # Example
12//!
13//! ```
14//! use actix::{Actor, Context};
15//! use actix_signal::{AddrSignalExt, SignalHandler};
16//! # use actix_signal_derive::SignalHandler;
17//!
18//! #[derive(SignalHandler)]
19//! struct MyActor;
20//!
21//! impl Actor for MyActor {
22//!     type Context = Context<Self>;
23//! }
24//!
25//! # #[actix_rt::test]
26//! # async fn test() {
27//! let actor = MyActor;
28//! let addr = actor.start();
29//!
30//! addr.stop();        // Stop the actor
31//! addr.terminate();   // Terminate the actor
32//! # }
33//! ```
34//!
35//! You may also implement handlers by hand if you don't want to use the proc macro or need custom behaviors.
36//!
37//! ```
38//! use actix::{Actor, Context, Handler, ActorContext};
39//! use actix_signal::{AddrSignalExt, StopSignal, TerminateSignal};
40//!
41//! struct MyActor;
42//!
43//! impl Actor for MyActor {
44//!     type Context = Context<Self>;
45//! }
46//!
47//! impl Handler<StopSignal> for MyActor {
48//!     type Result = ();
49//!
50//!     fn handle(&mut self, _msg: StopSignal, ctx: &mut Self::Context) -> Self::Result {
51//!         ctx.stop();
52//!     }
53//! }
54//!
55//! impl Handler<TerminateSignal> for MyActor {
56//!     type Result = ();
57//!
58//!     fn handle(&mut self, _msg: TerminateSignal, ctx: &mut Self::Context) -> Self::Result {
59//!         ctx.terminate();
60//!     }
61//! }
62//!
63//! # #[actix_rt::test]
64//! # async fn test() {
65//! let actor = MyActor;
66//! let addr = actor.start();
67//!
68//! addr.stop();        // Stop the actor
69//! addr.terminate();   // Terminate the actor
70//! # }
71//! ```
72//!
73//! # Feature flags
74//!
75//! `derive` - Provide `#[derive(SignalHandler)]` proc-macro.
76
77#[cfg(feature = "actix-signal-derive")]
78#[macro_use]
79extern crate actix_signal_derive;
80
81use actix::dev::ToEnvelope;
82use actix::{Actor, Handler};
83
84#[cfg(feature = "actix-signal-derive")]
85pub use actix_signal_derive::*;
86pub use addr::*;
87pub use signals::*;
88
89mod addr;
90mod private;
91pub mod signals;
92
93/// Actors that are able to handle signals.
94///
95/// This trait is sealed and automatically implemented for actors implementing `Handler`s for [`signals`](signals).
96/// See top-level document for instructions on implementing these traits.
97pub trait SignalHandler: Handler<StopSignal> + Handler<TerminateSignal> + private::Sealed {}
98
99impl<T> SignalHandler for T where T: Handler<StopSignal> + Handler<TerminateSignal> {}
100
101/// Execution contexts that are able to handle signals.
102///
103/// This trait is sealed and automatically implemented for contexts of which the associated actors implement `Handler`s
104/// for [`signals`](signals).
105/// See top-level document for instructions on implementing these traits.
106pub trait ToSignalEnvelope<A>:
107    ToEnvelope<A, StopSignal> + ToEnvelope<A, TerminateSignal> + private::Sealed
108where
109    A: Actor + SignalHandler,
110    <A as Actor>::Context: ToSignalEnvelope<A>,
111{
112}
113
114impl<A, T> ToSignalEnvelope<A> for T
115where
116    A: Actor<Context = T> + SignalHandler,
117    T: ToEnvelope<A, StopSignal> + ToEnvelope<A, TerminateSignal>,
118    <A as Actor>::Context: ToEnvelope<A, StopSignal> + ToEnvelope<A, TerminateSignal>,
119{
120}
actix_signal/lib.rs

actix_signal/
lib.rs
