documenting comments on main process upgrade, remove useless comments

bin/src/command/mod.rs

@@ -164,7 +164,6 @@ impl std::fmt::Display for Success {
                 write!(f, "Successfully set the metrics to {:?}", metrics_cfg)
             }
             Self::MasterStop => write!(f, "stopping main process"),
-            // Self::Metrics => write!(f, "Successfully fetched the metrics"),
             Self::NotifiedClient(id) => {
                 write!(f, "Successfully notified client {} of the advancement", id)
             }
@@ -245,6 +244,7 @@ pub struct CommandServer {
     config: Config,
     /// id of the next worker to be spawned
     next_worker_id: u32,
+    /// the path to the sozu executable, used to spawn workers
     executable_path: String,
     /// caching the number of backends instead of going through the whole state.backends hashmap
     backends_count: usize,

bin/src/main.rs

@@ -29,7 +29,7 @@ mod cli;
 mod command;
 /// The command line logic
 mod ctl;
-/// Forking & restarting the main process
+/// Forking & restarting the main process using a more recent executable of Sōzu
 mod upgrade;
 /// Some unix helper functions
 mod util;

bin/src/upgrade.rs

@@ -41,7 +41,6 @@ impl SerializedWorker {
             pid: worker.pid,
             id: worker.id,
             run_state: worker.run_state,
-            //token:      worker.token.clone().map(|Token(t)| t),
             queue: worker.queue.clone().into(),
             scm: worker.scm_socket.raw_fd(),
         }
@@ -53,15 +52,19 @@ impl SerializedWorker {
 pub struct UpgradeData {
     /// file descriptor of the unix command socket
     pub command_socket_fd: i32,
-    //clients: ????
     pub config: Config,
     /// JSON serialized workers
     pub workers: Vec<SerializedWorker>,
     pub state: ConfigState,
     pub next_id: u32,
-    //pub token_count: usize,
 }
 
+/// unix-forks the main process
+///
+/// - Parent: meant to disappear after the child confirms it's alive
+/// - Child: calls Sōzu's executable path with `sozu main [...]`
+///
+/// returns the pid of the new main, and a channel to get confirmation from the new main
 pub fn fork_main_into_new_main(
     executable_path: String,
     upgrade_data: UpgradeData,
@@ -130,7 +133,8 @@ pub fn fork_main_into_new_main(
     }
 }
 
-/// starts new main process with upgrade data, notifies the old main process
+/// Called by the child of a main process fork. 
+/// Starts new main process with upgrade data, notifies the old main process
 pub fn begin_new_main_process(
     new_to_old_channel_fd: i32,
     upgrade_file_fd: i32,

bin/src/worker.rs

@@ -42,6 +42,7 @@ use sozu_command_lib::{
 
 use crate::{command::Worker, logging, util};
 
+/// Called once at the beginning of the main process, this forks main into as many workers
 pub fn start_workers(executable_path: String, config: &Config) -> anyhow::Result<Vec<Worker>> {
     let state = ConfigState::new();
     let mut workers = Vec::new();
@@ -195,6 +196,12 @@ pub fn begin_worker_process(
     Ok(())
 }
 
+/// unix-forks the main process
+/// 
+/// - Parent: sends config and listeners to the new worker
+/// - Child: calls the sozu executable path like so: `sozu worker --id <worker_id> [...]`
+/// 
+/// returns the child process pid, and channels to talk to it.
 pub fn fork_main_into_worker(
     worker_id: &str,
     config: &Config,
@@ -238,8 +245,8 @@ pub fn fork_main_into_worker(
     info!("{} launching worker", worker_id);
     debug!("executable path is {}", executable_path);
     match unsafe { fork() } {
-        Ok(ForkResult::Parent { child }) => {
-            info!("{} worker launched: {}", worker_id, child);
+        Ok(ForkResult::Parent { child: worker_pid }) => {
+            info!("{} worker launched: {}", worker_id, worker_pid);
             main_to_worker_channel
                 .write_message(config)
                 .with_context(|| "Could not send config to the new worker using the channel")?;
@@ -257,7 +264,7 @@ pub fn fork_main_into_worker(
             util::disable_close_on_exec(main_to_worker_scm.fd)?;
 
             Ok((
-                child.into(),
+                worker_pid.into(),
                 main_to_worker_channel.into(),
                 main_to_worker_scm,
             ))

command/src/logging.rs

@@ -25,7 +25,9 @@ pub struct Logger {
     pub directives: Vec<LogDirective>,
     pub backend: LoggerBackend,
     pub access_backend: Option<LoggerBackend>,
+    /// is displayed in each log, for instance "MAIN" or worker_id
     pub tag: String,
+    /// the pid of the current process (main or worker)
     pub pid: i32,
     pub initialized: bool,
 }