From 44e43818798d7ad6fde718ac3ead3a48ae9211b3 Mon Sep 17 00:00:00 2001 From: Rob Ede Date: Sun, 28 Nov 2021 00:35:34 +0000 Subject: [PATCH] add some internal server documentation --- actix-server/src/server.rs | 20 +++++++++++++------- actix-server/src/signals.rs | 23 +++++++++++------------ actix-server/src/socket.rs | 22 +++++++++++----------- 3 files changed, 35 insertions(+), 30 deletions(-) diff --git a/actix-server/src/server.rs b/actix-server/src/server.rs index 6f75316c..e79c0aef 100644 --- a/actix-server/src/server.rs +++ b/actix-server/src/server.rs @@ -19,7 +19,7 @@ use crate::{ builder::ServerBuilder, join_all::join_all, service::InternalServiceFactory, - signals::{Signal, Signals}, + signals::{SignalKind, Signals}, waker_queue::{WakerInterest, WakerQueue}, worker::{ServerWorker, ServerWorkerConfig, WorkerHandleServer}, ServerHandle, @@ -27,16 +27,22 @@ use crate::{ #[derive(Debug)] pub(crate) enum ServerCommand { - /// TODO + /// Worker failed to accept connection, indicating a probable panic. + /// + /// Contains index of faulted worker. WorkerFaulted(usize), + /// Pause accepting connections. + /// /// Contains return channel to notify caller of successful state change. Pause(oneshot::Sender<()>), + /// Resume accepting connections. + /// /// Contains return channel to notify caller of successful state change. Resume(oneshot::Sender<()>), - /// TODO + /// Stop accepting connections and begin shutdown procedure. Stop { /// True if shut down should be graceful. graceful: bool, @@ -324,9 +330,9 @@ impl ServerInner { } } - fn handle_signal(&mut self, signal: Signal) -> Option> { + fn handle_signal(&mut self, signal: SignalKind) -> Option> { match signal { - Signal::Int => { + SignalKind::Int => { info!("SIGINT received; starting forced shutdown"); self.exit = true; self.handle_cmd(ServerCommand::Stop { @@ -335,7 +341,7 @@ impl ServerInner { }) } - Signal::Term => { + SignalKind::Term => { info!("SIGTERM received; starting graceful shutdown"); self.exit = true; self.handle_cmd(ServerCommand::Stop { @@ -344,7 +350,7 @@ impl ServerInner { }) } - Signal::Quit => { + SignalKind::Quit => { info!("SIGQUIT received; starting forced shutdown"); self.exit = true; self.handle_cmd(ServerCommand::Stop { diff --git a/actix-server/src/signals.rs b/actix-server/src/signals.rs index 0822a433..d8cb84e3 100644 --- a/actix-server/src/signals.rs +++ b/actix-server/src/signals.rs @@ -11,7 +11,7 @@ use log::trace; // #[allow(dead_code)] #[derive(Debug, Clone, Copy, PartialEq)] #[allow(dead_code)] // variants are never constructed on non-unix -pub(crate) enum Signal { +pub(crate) enum SignalKind { /// `SIGINT` Int, @@ -22,12 +22,12 @@ pub(crate) enum Signal { Quit, } -impl fmt::Display for Signal { +impl fmt::Display for SignalKind { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.write_str(match self { - Signal::Int => "SIGINT", - Signal::Term => "SIGTERM", - Signal::Quit => "SIGQUIT", + SignalKind::Int => "SIGINT", + SignalKind::Term => "SIGTERM", + SignalKind::Quit => "SIGQUIT", }) } } @@ -38,7 +38,7 @@ pub(crate) struct Signals { signals: futures_core::future::BoxFuture<'static, std::io::Result<()>>, #[cfg(unix)] - signals: Vec<(Signal, actix_rt::signal::unix::Signal)>, + signals: Vec<(SignalKind, actix_rt::signal::unix::Signal)>, } impl Signals { @@ -58,9 +58,9 @@ impl Signals { use actix_rt::signal::unix; let sig_map = [ - (unix::SignalKind::interrupt(), Signal::Int), - (unix::SignalKind::terminate(), Signal::Term), - (unix::SignalKind::quit(), Signal::Quit), + (unix::SignalKind::interrupt(), SignalKind::Int), + (unix::SignalKind::terminate(), SignalKind::Term), + (unix::SignalKind::quit(), SignalKind::Quit), ]; let signals = sig_map @@ -85,18 +85,17 @@ impl Signals { } impl Future for Signals { - type Output = Signal; + type Output = SignalKind; fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll { #[cfg(not(unix))] { - self.signals.as_mut().poll(cx).map(|_| Signal::Int) + self.signals.as_mut().poll(cx).map(|_| SignalKind::Int) } #[cfg(unix)] { for (sig, fut) in self.signals.iter_mut() { - // TODO: match on if let Some ? if Pin::new(fut).poll_recv(cx).is_ready() { trace!("{} received", sig); return Poll::Ready(*sig); diff --git a/actix-server/src/socket.rs b/actix-server/src/socket.rs index 6f641d73..7f281701 100644 --- a/actix-server/src/socket.rs +++ b/actix-server/src/socket.rs @@ -159,24 +159,24 @@ pub enum MioStream { Uds(mio::net::UnixStream), } -/// helper trait for converting mio stream to tokio stream. +/// Helper trait for converting a Mio stream into a Tokio stream. pub trait FromStream: Sized { fn from_mio(sock: MioStream) -> io::Result; } #[cfg(windows)] mod win_impl { - use super::*; - use std::os::windows::io::{FromRawSocket, IntoRawSocket}; - // FIXME: This is a workaround and we need an efficient way to convert between mio and tokio stream + use super::*; + + // TODO: This is a workaround and we need an efficient way to convert between Mio and Tokio stream impl FromStream for TcpStream { fn from_mio(sock: MioStream) -> io::Result { match sock { MioStream::Tcp(mio) => { let raw = IntoRawSocket::into_raw_socket(mio); - // SAFETY: This is a in place conversion from mio stream to tokio stream. + // SAFETY: This is an in-place conversion from Mio stream to Tokio stream. TcpStream::from_std(unsafe { FromRawSocket::from_raw_socket(raw) }) } } @@ -186,19 +186,19 @@ mod win_impl { #[cfg(unix)] mod unix_impl { - use super::*; - use std::os::unix::io::{FromRawFd, IntoRawFd}; use actix_rt::net::UnixStream; - // FIXME: This is a workaround and we need an efficient way to convert between mio and tokio stream + use super::*; + + // HACK: This is a workaround and we need an efficient way to convert between Mio and Tokio stream impl FromStream for TcpStream { fn from_mio(sock: MioStream) -> io::Result { match sock { MioStream::Tcp(mio) => { let raw = IntoRawFd::into_raw_fd(mio); - // SAFETY: This is a in place conversion from mio stream to tokio stream. + // SAFETY: This is an in-place conversion from Mio stream to Tokio stream. TcpStream::from_std(unsafe { FromRawFd::from_raw_fd(raw) }) } MioStream::Uds(_) => { @@ -208,14 +208,14 @@ mod unix_impl { } } - // FIXME: This is a workaround and we need an efficient way to convert between mio and tokio stream + // HACK: This is a workaround and we need an efficient way to convert between Mio and Tokio stream impl FromStream for UnixStream { fn from_mio(sock: MioStream) -> io::Result { match sock { MioStream::Tcp(_) => panic!("Should not happen, bug in server impl"), MioStream::Uds(mio) => { let raw = IntoRawFd::into_raw_fd(mio); - // SAFETY: This is a in place conversion from mio stream to tokio stream. + // SAFETY: This is an in-place conversion from Mio stream to Tokio stream. UnixStream::from_std(unsafe { FromRawFd::from_raw_fd(raw) }) } }