add some internal server documentation

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<BoxFuture<'static, ()>> {
+    fn handle_signal(&mut self, signal: SignalKind) -> Option<BoxFuture<'static, ()>> {
         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 {

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",
+            SignalKind::Int => "SIGINT",
-            Signal::Term => "SIGTERM",
+            SignalKind::Term => "SIGTERM",
-            Signal::Quit => "SIGQUIT",
+            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::interrupt(), SignalKind::Int),
-                (unix::SignalKind::terminate(), Signal::Term),
+                (unix::SignalKind::terminate(), SignalKind::Term),
-                (unix::SignalKind::quit(), Signal::Quit),
+                (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<Self::Output> {
         #[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);

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<Self>;
 }
 
 #[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<Self> {
             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<Self> {
             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<Self> {
             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) })
                 }
             }