actix/
lib.rs

1//! Actix is an actor framework.
2//!
3//! [Actors](Actor) are objects which encapsulate state and behavior, they communicate exclusively
4//! by exchanging messages. Actix actors are implemented on top of [Tokio](https://tokio.rs).
5//!
6//! Multiple actors can run in same thread. Actors can run in multiple threads using the [`Arbiter`]
7//! API. Actors exchange typed messages.
8//!
9//! ## Features
10//!
11//! - Async or sync actors
12//! - Actor communication in a local/thread context
13//! - Using Futures for asynchronous message handling
14//! - Actor supervision
15//! - Typed messages (no [`Any`](std::any::Any) type) and generic messages are allowed
16//! - Runs on stable Rust 1.68+
17//!
18//! ## Other Documentation
19//!
20//! - [User Guide](https://actix.rs/docs/actix)
21//! - [Community Chat on Discord](https://discord.gg/NWpN5mmg3x)
22
23#![deny(rust_2018_idioms, nonstandard_style, future_incompatible)]
24#![doc(html_logo_url = "https://actix.rs/img/logo.png")]
25#![doc(html_favicon_url = "https://actix.rs/favicon.ico")]
26#![cfg_attr(docsrs, feature(doc_auto_cfg))]
27
28#[cfg(doctest)]
29doc_comment::doctest!("../README.md");
30
31mod actor;
32mod address;
33mod context;
34mod context_impl;
35mod context_items;
36mod handler;
37mod mailbox;
38mod stream;
39mod supervisor;
40
41pub mod actors;
42pub mod clock;
43pub mod fut;
44pub mod io;
45pub mod registry;
46pub mod sync;
47pub mod utils;
48
49#[cfg(feature = "macros")]
50pub use actix_derive::{main, test, Message, MessageResponse};
51pub use actix_rt::{spawn, Arbiter, ArbiterHandle, System, SystemRunner};
52
53#[doc(hidden)]
54pub mod __private {
55    #[cfg(feature = "macros")]
56    pub use actix_macros::{main, test};
57}
58
59#[doc(hidden)]
60pub use crate::context::ContextFutureSpawner;
61pub use crate::{
62    actor::{Actor, ActorContext, ActorState, AsyncContext, Running, SpawnHandle, Supervised},
63    address::{Addr, MailboxError, Recipient, WeakAddr, WeakRecipient},
64    context::Context,
65    fut::{
66        ActorFuture, ActorFutureExt, ActorStream, ActorStreamExt, ActorTryFuture,
67        ActorTryFutureExt, WrapFuture, WrapStream,
68    },
69    handler::{
70        ActorResponse, AtomicResponse, Handler, Message, MessageResult, Response,
71        ResponseActFuture, ResponseFuture,
72    },
73    registry::{ArbiterService, Registry, SystemRegistry, SystemService},
74    stream::StreamHandler,
75    supervisor::Supervisor,
76    sync::{SyncArbiter, SyncContext},
77};
78
79pub mod prelude {
80    //! The `actix` prelude.
81    //!
82    //! The purpose of this module is to alleviate imports of many common actix
83    //! traits by adding a glob import to the top of actix heavy modules:
84    //!
85    //! ```
86    //! # #![allow(unused_imports)]
87    //! use actix::prelude::*;
88    //! ```
89
90    #[doc(hidden)]
91    #[cfg(feature = "macros")]
92    pub use actix_derive::{Message, MessageResponse};
93    pub use actix_rt::{Arbiter, ArbiterHandle, System, SystemRunner};
94    pub use futures_core::stream::Stream;
95
96    #[allow(deprecated)]
97    pub use crate::utils::Condition;
98    pub use crate::{
99        actor::{Actor, ActorContext, ActorState, AsyncContext, Running, SpawnHandle, Supervised},
100        actors,
101        address::{Addr, MailboxError, Recipient, RecipientRequest, Request, SendError},
102        context::{Context, ContextFutureSpawner},
103        dev, fut,
104        fut::{
105            ActorFuture, ActorFutureExt, ActorStream, ActorStreamExt, ActorTryFuture,
106            ActorTryFutureExt, WrapFuture, WrapStream,
107        },
108        handler::{
109            ActorResponse, AtomicResponse, Handler, Message, MessageResult, Response,
110            ResponseActFuture, ResponseFuture,
111        },
112        io,
113        registry::{ArbiterService, SystemService},
114        stream::StreamHandler,
115        supervisor::Supervisor,
116        sync::{SyncArbiter, SyncContext},
117        utils::{IntervalFunc, TimerFunc},
118    };
119}
120
121pub mod dev {
122    //! The `actix` prelude for library developers.
123    //!
124    //! The purpose of this module is to alleviate imports of many common actix
125    //! traits by adding a glob import to the top of actix heavy modules:
126    //!
127    //! ```
128    //! # #![allow(unused_imports)]
129    //! use actix::dev::*;
130    //! ```
131
132    pub use crate::{
133        address::{Envelope, EnvelopeProxy, RecipientRequest, Request, ToEnvelope},
134        prelude::*,
135    };
136    pub mod channel {
137        pub use crate::address::channel::{channel, AddressReceiver, AddressSender};
138    }
139    pub use crate::{
140        context_impl::{AsyncContextParts, ContextFut, ContextParts},
141        handler::{MessageResponse, OneshotSender},
142        mailbox::Mailbox,
143        registry::{Registry, SystemRegistry},
144    };
145}
146
147/// Starts the system and executes the supplied future.
148///
149/// This function does the following:
150///
151/// * Creates and starts the actix system with default configuration.
152/// * Spawns the given future onto the current arbiter.
153/// * Blocks the current thread until the system shuts down.
154///
155/// The `run` function returns when the `System::current().stop()`
156/// method gets called.
157///
158/// # Examples
159///
160/// ```
161/// use std::time::{Duration, Instant};
162/// use actix_rt::time::sleep;
163///
164/// fn main() {
165///   actix::run(async move {
166///       sleep(Duration::from_millis(100)).await;
167///       actix::System::current().stop();
168///   });
169/// }
170/// ```
171///
172/// # Panics
173///
174/// This function panics if the actix system is already running.
175#[allow(clippy::unit_arg, clippy::needless_doctest_main)]
176pub fn run<R>(f: R) -> std::io::Result<()>
177where
178    R: std::future::Future<Output = ()> + 'static,
179{
180    Ok(actix_rt::System::new().block_on(f))
181}