[package]
name = "qsu"
version = "0.3.0"
version = "0.4.0"
edition = "2021"
license = "0BSD"
# https://crates.io/category_slugs
categories = [ "asynchronous" ]
keywords = [ "service", "systemd", "winsvc" ]
repository = "https://repos.qrnch.tech/pub/qsu"
description = "Service subsystem wrapper."
rust-version = "1.56"
exclude = [
  ".fossil-settings",
  ".efiles",
  ".fslckout",
  "www",
  "build_docs.sh",
  "Rocket.toml",
  "rustfmt.toml"
]

# https://doc.rust-lang.org/cargo/reference/manifest.html#the-badges-section
[badges]
maintenance = { status = "experimental" }

[features]
default = ["rt"]
clap = ["dep:clap", "dep:itertools"]
full = ["clap", "installer", "rocket", "rt", "systemd", "tokio"]
installer = ["dep:sidoc"]
systemd = ["dep:sd-notify"]
rocket = ["rt", "dep:rocket", "tokio"]
rt = []
tokio = ["rt", "tokio/macros", "tokio/rt-multi-thread", "tokio/signal"]
wait-for-debugger = ["dep:dbgtools-win"]

[dependencies]
apperr = { version = "0.2.0" }
async-trait = { version = "0.1.77" }
chrono = { version = "0.4.33" }
clap = { version = "4.4.18", optional = true, features = [
chrono = { version = "0.4.35" }
clap = { version = "4.5.2", optional = true, features = [
  "derive", "env", "string", "wrap_help"
] }
env_logger = { version = "0.11.1" }
env_logger = { version = "0.11.3" }
futures = { version = "0.3.30" }
itertools = { version = "0.12.1", optional = true }
killswitch = { version = "0.4.2" }
log = { version = "0.4.20" }
parking_lot = { version = "0.12.1" }
rocket = { version = "0.5.0", optional = true }
sidoc = { version = "0.1.0", optional = true }
tokio = { version = "1.35.1", features = ["sync"] }
time = { version = "0.3.31", features = ["macros"] }
tokio = { version = "1.36.0", features = ["sync"] }
time = { version = "0.3.34", features = ["macros"] }
tracing = { version = "0.1.40" }

[dependencies.tracing-subscriber]
version = "0.3.18"
default-features = false
features = ["env-filter", "time", "fmt", "ansi"]

[target.'cfg(target_os = "linux")'.dependencies]
sd-notify = { version = "0.4.1", optional = true }

[target.'cfg(unix)'.dependencies]
libc = { version = "0.2.152" }
nix = { version = "0.27.1", features = ["pthread", "signal"] }
libc = { version = "0.2.153" }
nix = { version = "0.28.0", features = ["pthread", "signal"] }

[target.'cfg(windows)'.dependencies]
dbgtools-win = { version = "0.2.1", optional = true }
eventlog = { version = "0.2.2" }
registry = { version = "1.2.3" }
scopeguard = { version = "1.2.0" }
windows-service = { version = "0.6.0" }
windows-sys = { version = "0.52.0", features = [
  "Win32_Foundation", "Win32_System_Console"
] }
winreg = { version = "0.52.0" }

[dev-dependencies]
clap = { version = "4.4.14", features = ["derive", "env", "wrap_help"] }
tokio = { version = "1.35.1", features = ["time"] }
clap = { version = "4.5.2", features = ["derive", "env", "wrap_help"] }
tokio = { version = "1.36.0", features = ["time"] }

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs", "--generate-link-to-definition"]

[[example]]
name = "hellosvc"

#[macro_use]
extern crate rocket;

mod argp;
mod err;
mod procres;

use qsu::{
  argp::ArgParser,
  rt::{
    RocketServiceHandler, SrvAppRt, StartState, StopState, SvcEvt,
    SvcEvtReader
    InitCtx, RocketServiceHandler, RunEnv, SrvAppRt, SvcEvt, SvcEvtReader,
    TermCtx
  }
};

use rocket::{Build, Ignite, Rocket};

use err::Error;
use procres::ProcRes;


struct MyService {}

#[qsu::async_trait]
impl RocketServiceHandler for MyService {
  async fn init(
    &mut self,
    ss: StartState
    ictx: InitCtx
  ) -> Result<Vec<Rocket<Build>>, qsu::AppErr> {
    tracing::trace!("Running init()");

    let mut rockets = vec![];

    ss.report(Some("Building a rocket!".into()));
    ictx.report(Some("Building a rocket!".into()));
    let rocket = rocket::build().mount("/", routes![index]);

    ss.report(Some("Pushing a rocket".into()));
    ictx.report(Some("Pushing a rocket".into()));
    rockets.push(rocket);

    Ok(rockets)
  }

  async fn run(
    &mut self,
    rockets: Vec<Rocket<Ignite>>,
    _re: &RunEnv,
    mut set: SvcEvtReader
  ) -> Result<(), qsu::AppErr> {
    for rocket in rockets {
      tokio::task::spawn(async {
        rocket.launch().await.unwrap();
      });
    }

        }
      }
    }

    Ok(())
  }

  async fn shutdown(&mut self, ss: StopState) -> Result<(), qsu::AppErr> {
    ss.report(Some(format!("Entered {}", "shutdown").into()));
  async fn shutdown(&mut self, tctx: TermCtx) -> Result<(), qsu::AppErr> {
    tctx.report(Some(format!("Entered {}", "shutdown").into()));
    tracing::trace!("Running shutdown()");
    Ok(())
  }
}


fn main() -> ProcRes {

//! Simple service that does nothing other than log/trace every N seconds.

mod argp;
mod err;
mod procres;

use std::time::{Duration, Instant};

use qsu::{
  argp::ArgParser,
  rt::{
    InitCtx, RunEnv, SrvAppRt, SvcEvt, SvcEvtReader, TermCtx,
    SrvAppRt, StartState, StopState, SvcEvt, SvcEvtReader, TokioServiceHandler
    TokioServiceHandler
  }
};

use err::Error;
use procres::ProcRes;


struct MyService {}

#[qsu::async_trait]
impl TokioServiceHandler for MyService {
  async fn init(&mut self, ss: StartState) -> Result<(), qsu::AppErr> {
    ss.report(Some("Entered init".into()));
  async fn init(&mut self, ictx: InitCtx) -> Result<(), qsu::AppErr> {
    ictx.report(Some("Entered init".into()));
    tracing::trace!("Running init()");
    Ok(())
  }

  async fn run(
    &mut self,
    _re: &RunEnv,
    mut set: SvcEvtReader
  async fn run(&mut self, mut set: SvcEvtReader) -> Result<(), qsu::AppErr> {
  ) -> Result<(), qsu::AppErr> {
    const SECS: u64 = 30;
    let mut last_dump = Instant::now() - Duration::from_secs(SECS);
    loop {
      if Instant::now() - last_dump > Duration::from_secs(SECS) {
        log::error!("error");
        log::warn!("warn");
        log::info!("info");

        }
      }
    }

    Ok(())
  }

  async fn shutdown(&mut self, ss: StopState) -> Result<(), qsu::AppErr> {
    ss.report(Some(("Entered shutdown".to_string()).into()));
  async fn shutdown(&mut self, tctx: TermCtx) -> Result<(), qsu::AppErr> {
    tctx.report(Some(("Entered shutdown".to_string()).into()));
    tracing::trace!("Running shutdown()");
    Ok(())
  }
}


fn main() -> ProcRes {

  thread,
  time::{Duration, Instant}
};

use qsu::{
  argp::ArgParser,
  rt::{
    ServiceHandler, SrvAppRt, StartState, StopState, SvcEvt, SvcEvtReader
    InitCtx, RunEnv, ServiceHandler, SrvAppRt, SvcEvt, SvcEvtReader, TermCtx
  }
};

use err::Error;
use procres::ProcRes;


struct MyService {}

impl ServiceHandler for MyService {
  fn init(&mut self, ss: StartState) -> Result<(), qsu::AppErr> {
    ss.report(Some("Entered init".into()));
  fn init(&mut self, ictx: InitCtx) -> Result<(), qsu::AppErr> {
    ictx.report(Some("Entered init".into()));
    tracing::trace!("Running init()");
    Ok(())
  }

  fn run(
    &mut self,
    _re: &RunEnv,
    mut set: SvcEvtReader
  fn run(&mut self, mut set: SvcEvtReader) -> Result<(), qsu::AppErr> {
  ) -> Result<(), qsu::AppErr> {
    const SECS: u64 = 30;
    let mut last_dump = Instant::now() - Duration::from_secs(SECS);
    loop {
      if Instant::now() - last_dump > Duration::from_secs(SECS) {
        log::error!("error");
        log::warn!("warn");
        log::info!("info");

      thread::sleep(std::time::Duration::from_secs(1));
    }

    Ok(())
  }

  fn shutdown(&mut self, ss: StopState) -> Result<(), qsu::AppErr> {
    ss.report(Some(("Entered shutdown".to_string()).into()));
  fn shutdown(&mut self, tctx: TermCtx) -> Result<(), qsu::AppErr> {
    tctx.report(Some(("Entered shutdown".to_string()).into()));
    tracing::trace!("Running shutdown()");
    Ok(())
  }
}


fn main() -> ProcRes {

use tokio::runtime;

use tokio::sync::broadcast;


use crate::{err::Error, lumberjack::LumberJack, AppErr};

/// The run time environment.
///
/// Can be used by the application callbacks to determine whether it is running
/// as a service.
#[derive(Debug, Clone)]
pub enum RunEnv {
  /// Running as a foreground process.
  Foreground,

  /// Running as a service.
  ///
  /// If the service subsystem has named services, this will contain the
  /// service name.
  Service(Option<String>)
}

/// Used to pass an optional message to the service subsystem whenever a
/// startup or shutdown checkpoint as been reached.
pub enum StateMsg {
  Ref(&'static str),
  Owned(String)
}

  fn stopping(&self, checkpoint: u32, msg: Option<StateMsg>);

  fn stopped(&self);
}


/// Report startup checkpoints to the service subsystem.
///
/// An instance of this is handed to the server application through the service
/// handler's `init()` trait method.
pub struct StartState {
/// Context passed to `init()` service application callback.
pub struct InitCtx {
  re: RunEnv,
  sr: Arc<dyn StateReporter + Send + Sync>,
  cnt: Arc<AtomicU32>
}
impl StartState {

impl InitCtx {
  /// Return context used to identify whether service application is running as
  /// a foreground process or a system service.
  pub fn runenv(&self) -> RunEnv {
    self.re.clone()
  }

  /// Report startup state to the system service manager.
  ///
  /// For foreground processes and services that do not support startup state
  /// notifications this method has no effect.
  pub fn report(&self, status: Option<StateMsg>) {
    let checkpoint = self.cnt.fetch_add(1, Ordering::SeqCst);
    self.sr.starting(checkpoint, status);
  }
}

/// Report shutdown checkpoints to the service subsystem.

///
/// An instance of this is handed to the server application through the service
/// Context passed to `term()` service application callback.
/// handler's `shutdown()` trait method.
pub struct StopState {
pub struct TermCtx {
  re: RunEnv,
  sr: Arc<dyn StateReporter + Send + Sync>,
  cnt: Arc<AtomicU32>
}
impl StopState {

impl TermCtx {
  /// Return context used to identify whether service application is running as
  /// a foreground process or a system service.
  pub fn runenv(&self) -> RunEnv {
    self.re.clone()
  }

  /// Report shutdown state to the system service manager.
  ///
  /// For foreground processes and services that do not support shutdown state
  /// notifications this method has no effect.
  pub fn report(&self, status: Option<StateMsg>) {
    let checkpoint = self.cnt.fetch_add(1, Ordering::SeqCst);
    self.sr.stopping(checkpoint, status);
  }
}


/// "Synchronous" (non-`async`) server application.
///
/// Implement this for an object that wraps a server application that does not
/// use an async runtime.
pub trait ServiceHandler {
  fn init(&mut self, ss: StartState) -> Result<(), AppErr>;
  fn init(&mut self, ictx: InitCtx) -> Result<(), AppErr>;

  fn run(&mut self, ser: SvcEvtReader) -> Result<(), AppErr>;
  fn run(&mut self, re: &RunEnv, ser: SvcEvtReader) -> Result<(), AppErr>;

  fn shutdown(&mut self, ss: StopState) -> Result<(), AppErr>;
  fn shutdown(&mut self, tctx: TermCtx) -> Result<(), AppErr>;
}


/// `async` server application built on the tokio runtime.
///
/// Implement this for an object that wraps a server application that uses
/// tokio as an async runtime.
#[cfg(feature = "tokio")]
#[cfg_attr(docsrs, doc(cfg(feature = "tokio")))]
#[async_trait]
pub trait TokioServiceHandler {
  async fn init(&mut self, ss: StartState) -> Result<(), AppErr>;
  async fn init(&mut self, ictx: InitCtx) -> Result<(), AppErr>;

  async fn run(
    &mut self,
    re: &RunEnv,
    ser: SvcEvtReader
  async fn run(&mut self, ser: SvcEvtReader) -> Result<(), AppErr>;
  ) -> Result<(), AppErr>;

  async fn shutdown(&mut self, ss: StopState) -> Result<(), AppErr>;
  async fn shutdown(&mut self, tctx: TermCtx) -> Result<(), AppErr>;
}


/// Rocket server application handler.
///
/// While Rocket is built on top of tokio, it \[Rocket\] wants to initialize
/// tokio itself.

pub trait RocketServiceHandler {
  /// Rocket service initialization.
  ///
  /// The returned `Rocket`s will be ignited and their shutdown handlers will
  /// be triggered on shutdown.
  async fn init(
    &mut self,
    ss: StartState
    ictx: InitCtx
  ) -> Result<Vec<rocket::Rocket<rocket::Build>>, AppErr>;

  /// Server application main entry point.
  ///
  /// If the `init()` trait method returned `Rocket<Build>` instances to the
  /// qsu runtime it will ignote these and pass them to `run()`.  It is the
  /// responsibility of this method to launch the rockets and await them.
  async fn run(
    &mut self,
    rockets: Vec<rocket::Rocket<rocket::Ignite>>,
    re: &RunEnv,
    ser: SvcEvtReader
  ) -> Result<(), AppErr>;

  async fn shutdown(&mut self, ss: StopState) -> Result<(), AppErr>;
  async fn shutdown(&mut self, tctx: TermCtx) -> Result<(), AppErr>;
}


/// Event notifications that originate from the service subsystem that is
/// controlling the server application.
#[derive(Clone, Debug)]
pub enum SvcEvt {

  fn systemd(self, st: SrvAppRt) -> Result<(), Error> {
    LumberJack::default().set_init(self.log_init).init()?;

    tracing::debug!("Running service '{}'", self.svcname);

    let reporter = Arc::new(systemd::ServiceReporter {});

    let re = RunEnv::Service(Some(self.svcname.clone()));

    let res = match st {
      SrvAppRt::Sync(handler) => {
        rttype::sync_main(handler, reporter, None, self.test_mode)
        rttype::sync_main(re, handler, reporter, None, self.test_mode)
      }
      SrvAppRt::Tokio(rtbldr, handler) => {
        rttype::tokio_main(rtbldr, handler, reporter, None)
        rttype::tokio_main(rtbldr, re, handler, reporter, None)
      }
      #[cfg(feature = "rocket")]
      SrvAppRt::Rocket(handler) => rttype::rocket_main(handler, reporter, None)
      SrvAppRt::Rocket(handler) => {
        rttype::rocket_main(re, handler, reporter, None)
      }
    };

    res
  }

  /// Run as a Windows service.
  #[cfg(windows)]

  fn foreground(self, st: SrvAppRt) -> Result<(), Error> {
    LumberJack::default().set_init(self.log_init).init()?;

    tracing::debug!("Running service '{}'", self.svcname);

    let reporter = Arc::new(nosvc::ServiceReporter {});

    let re = RunEnv::Foreground;

    match st {
      SrvAppRt::Sync(handler) => {
        rttype::sync_main(handler, reporter, None, self.test_mode)
        rttype::sync_main(re, handler, reporter, None, self.test_mode)
      }

      #[cfg(feature = "tokio")]
      SrvAppRt::Tokio(rtbldr, handler) => {
        rttype::tokio_main(rtbldr, handler, reporter, None)
        rttype::tokio_main(rtbldr, re, handler, reporter, None)
      }

      #[cfg(feature = "rocket")]
      SrvAppRt::Rocket(handler) => rttype::rocket_main(handler, reporter, None)
      SrvAppRt::Rocket(handler) => {
        rttype::rocket_main(re, handler, reporter, None)
      }
    }
  }
}

impl RunCtx {
  /// Create a new service running context.
  pub fn new(name: &str) -> Self {

use tokio::{sync::broadcast, task};

use killswitch::KillSwitch;

use crate::{
  err::{AppErrors, Error},
  rt::{
    signals, RocketServiceHandler, StartState, StateReporter, StopState,
    SvcEvt, SvcEvtReader
    signals, InitCtx, RocketServiceHandler, RunEnv, StateReporter, SvcEvt,
    SvcEvtReader, TermCtx
  }
};


/// Internal "main()" routine for server applications that run one or more
/// Rockets as their main application.
pub(crate) fn rocket_main(
  re: RunEnv,
  handler: Box<dyn RocketServiceHandler + Send>,
  sr: Arc<dyn StateReporter + Send + Sync>,
  rx_svcevt: Option<broadcast::Receiver<SvcEvt>>
) -> Result<(), Error> {
  rocket::execute(rocket_async_main(handler, sr, rx_svcevt))?;
  rocket::execute(rocket_async_main(re, handler, sr, rx_svcevt))?;

  Ok(())
}

async fn rocket_async_main(
  re: RunEnv,
  mut handler: Box<dyn RocketServiceHandler + Send>,
  sr: Arc<dyn StateReporter + Send + Sync>,
  rx_svcevt: Option<broadcast::Receiver<SvcEvt>>
) -> Result<(), Error> {
  let ks = KillSwitch::new();

  // If a SvcEvt receiver end-point was handed to us, then use it.  Otherwise

  };

  let mut rx_svcevt2 = rx_svcevt.resubscribe();

  let set = Box::new(SvcEvtReader { rx: rx_svcevt });

  // Call application's init() method.
  let ss = StartState {
  let ictx = InitCtx {
    re: re.clone(),
    sr: Arc::clone(&sr),
    cnt: Arc::new(AtomicU32::new(2)) // 1 is used by the runtime, so start at 2
  };
  let (rockets, init_apperr) = match handler.init(ss).await {
  let (rockets, init_apperr) = match handler.init(ictx).await {
    Ok(rockets) => (rockets, None),
    Err(e) => (Vec::new(), Some(e))
  };

  // Ignite rockets so we can get Shutdown contexts for each of the instances.
  let mut ignited = vec![];
  let mut rocket_shutdowns = vec![];

        }
      }
    }
  });

  let run_apperr = if init_apperr.is_none() {
    sr.started();
    handler.run(ignited, *set).await.err()
    handler.run(ignited, &re, *set).await.err()
  } else {
    None
  };


  // Always send the first shutdown checkpoint here.  Either init() failed or
  // run retuned.  Either way, we're shutting down.

  }

  if (ks.finalize().await).is_err() {
    log::warn!("Attempted to finalize KillSwitch that wasn't triggered yet");
  }

  // Call the application's shutdown() function.
  let ss = StopState {
  let tctx = TermCtx {
    re,
    sr: Arc::clone(&sr),
    cnt: Arc::new(AtomicU32::new(2)) // 1 is used by the runtime, so start at 2
  };
  let term_apperr = handler.shutdown(ss).await.err();
  let term_apperr = handler.shutdown(tctx).await.err();

  // Inform the service subsystem that the the shutdown is complete
  sr.stopped();

  // There can be multiple failures, and we don't want to lose information
  // about what went wrong, so return an error context that can contain all
  // callback errors.

use std::sync::{atomic::AtomicU32, Arc};

use tokio::sync::broadcast;

use crate::{
  err::{AppErrors, Error},
  rt::{
    signals, ServiceHandler, StartState, StateReporter, StopState, SvcEvt,
    SvcEvtReader
    signals, InitCtx, RunEnv, ServiceHandler, StateReporter, SvcEvt,
    SvcEvtReader, TermCtx
  }
};

#[cfg(unix)]
use crate::rt::signals::SigType;

/// Internal "main()" routine for server applications that run plain old
/// non-`async` code.
pub(crate) fn sync_main(
  re: RunEnv,
  mut handler: Box<dyn ServiceHandler>,
  sr: Arc<dyn StateReporter + Send + Sync>,
  rx_svcevt: Option<broadcast::Receiver<SvcEvt>>,
  test_mode: bool
) -> Result<(), Error> {
  // Get rid of unused variable warning
  #[cfg(unix)]

    rx
  };

  let set = Box::new(SvcEvtReader { rx: rx_svcevt });

  // Call server application's init() method, passing along a startup state
  // reporter object.
  let ss = StartState {
  let ictx = InitCtx {
    re: re.clone(),
    sr: Arc::clone(&sr),
    cnt: Arc::new(AtomicU32::new(2)) // 1 is used by the runtime, so start at 2
  };
  let init_apperr = handler.init(ss).err();
  let init_apperr = handler.init(ictx).err();

  // If init() was successful, set the service's state to "started" and then
  // call the server application's run() method.
  let run_apperr = if init_apperr.is_none() {
    sr.started();
    handler.run(*set).err()
    handler.run(&re, *set).err()
  } else {
    None
  };

  // Always send the first shutdown checkpoint here.  Either init() failed or
  // run retuned.  Either way, we're shutting down.
  sr.stopping(1, None);

  // Call the application's shutdown() function, passing along a shutdown state
  // reporter object.
  let ss = StopState {
  let tctx = TermCtx {
    re,
    sr: Arc::clone(&sr),
    cnt: Arc::new(AtomicU32::new(2)) // 1 is used by the runtime, so start at 2
  };
  let term_apperr = handler.shutdown(ss).err();
  let term_apperr = handler.shutdown(tctx).err();

  // Inform the service subsystem that the the shutdown is complete
  sr.stopped();

  // There can be multiple failures, and we don't want to lose information
  // about what went wrong, so return an error context that can contain all
  // callback errors.

use std::sync::{atomic::AtomicU32, Arc};

use tokio::{runtime, sync::broadcast, task};

use crate::{
  err::{AppErrors, Error},
  rt::{
    signals, StartState, StateReporter, StopState, SvcEvt, SvcEvtReader,
    signals, InitCtx, RunEnv, StateReporter, SvcEvt, SvcEvtReader, TermCtx,
    TokioServiceHandler
  }
};

use killswitch::KillSwitch;


/// Internal "main()" routine for server applications that run the tokio
/// runtime for `async` code.
pub(crate) fn tokio_main(
  rtbldr: Option<runtime::Builder>,
  re: RunEnv,
  handler: Box<dyn TokioServiceHandler>,
  sr: Arc<dyn StateReporter + Send + Sync>,
  rx_svcevt: Option<broadcast::Receiver<SvcEvt>>
) -> Result<(), Error> {
  let rt = if let Some(mut bldr) = rtbldr {
    bldr.build()?
  } else {
    tokio::runtime::Runtime::new()?
  };
  rt.block_on(tokio_async_main(handler, sr, rx_svcevt))?;
  rt.block_on(tokio_async_main(re, handler, sr, rx_svcevt))?;

  Ok(())
}

/// The `async` main function for tokio servers.
///
/// If `rx_svcevt` is `Some(_)` it means the channel was created elsewhere
/// (implied: The transmitting endpoint lives somewhere else).  If it is `None`
/// the channel needs to be created.
async fn tokio_async_main(
  re: RunEnv,
  mut handler: Box<dyn TokioServiceHandler>,
  sr: Arc<dyn StateReporter + Send + Sync>,
  rx_svcevt: Option<broadcast::Receiver<SvcEvt>>
) -> Result<(), Error> {
  let ks = KillSwitch::new();

  // If a SvcEvt receiver end-point was handed to us, then use it.  Otherwise

    rx
  };

  let set = Box::new(SvcEvtReader { rx: rx_svcevt });

  // Call application's init() method.
  let ss = StartState {
  let ictx = InitCtx {
    re: re.clone(),
    sr: Arc::clone(&sr),
    cnt: Arc::new(AtomicU32::new(2)) // 1 is used by the runtime, so start at 2
  };
  let init_apperr = handler.init(ss).await.err();
  let init_apperr = handler.init(ictx).await.err();

  let run_apperr = if init_apperr.is_none() {
    sr.started();
    handler.run(*set).await.err()
    handler.run(&re, *set).await.err()
  } else {
    None
  };

  // Always send the first shutdown checkpoint here.  Either init() failed or
  // run retuned.  Either way, we're shutting down.
  sr.stopping(1, None);


  // Now that the main application has terminated kill off any remaining
  // auxiliary tasks (read: signal waiters)
  ks.trigger();

  if (ks.finalize().await).is_err() {
    log::warn!("Attempted to finalize KillSwitch that wasn't triggered yet");
  }

  // Call the application's shutdown() function.
  let ss = StopState {
  let tctx = TermCtx {
    re,
    sr: Arc::clone(&sr),
    cnt: Arc::new(AtomicU32::new(2)) // 1 is used by the runtime, so start at 2
  };
  let term_apperr = handler.shutdown(ss).await.err();
  let term_apperr = handler.shutdown(tctx).await.err();

  // Inform the service subsystem that the the shutdown is complete
  sr.stopped();

  // There can be multiple failures, and we don't want to lose information
  // about what went wrong, so return an error context that can contain all
  // callback errors.

#[cfg(feature = "wait-for-debugger")]
use dbgtools_win::debugger;


use crate::{
  err::Error,
  lumberjack::LumberJack,
  rt::{SrvAppRt, SvcEvt}
  rt::{RunEnv, SrvAppRt, SvcEvt}
};

use super::StateMsg;


const SERVICE_TYPE: ServiceType = ServiceType::OWN_PROCESS;
//const SERVICE_STARTPENDING_TIME: Duration = Duration::from_secs(10);

  // This must be done _before_ launching the application runtime thread below.
  CELL.get_or_init(|| Mutex::new(Some(xfer)));

  // Launch main application thread.
  //
  // The server application must be run on its own thread because the service
  // dispatcher call below will block the thread.
  let svcnm = svcname.to_string();
  let jh = thread::Builder::new()
    .name("svcapp".into())
    .spawn(move || srvapp_thread(st, rx_fromsvc))?;
    .spawn(move || srvapp_thread(st, svcnm, rx_fromsvc))?;

  // Register generated `ffi_service_main` with the system and start the
  // service, blocking this thread until the service is stopped.
  service_dispatcher::start(svcname, ffi_service_main)?;

  match jh.join() {
    Ok(_) => Ok(()),
    Err(e) => *e
      .downcast::<Result<(), Error>>()
      .expect("Unable to downcast error from svcapp thread")
  }
}

fn srvapp_thread(
  st: SrvAppRt,
  svcname: String,
  rx_fromsvc: oneshot::Receiver<Result<HandshakeMsg, Error>>
) -> Result<(), Error> {
  // Wait for the service subsystem to report that it has initialized.
  // It passes along a channel end-point that can be used to send events to
  // the service manager.

  let Ok(res) = rx_fromsvc.blocking_recv() else {
    panic!("Unable to receive handshake");
  };

  let Ok(HandshakeMsg { tx, rx }) = res else {
    panic!("Unable to receive handshake");
  };

  let reporter = Arc::new(ServiceReporter { tx: tx.clone() });

  let re = RunEnv::Service(Some(svcname));

  match st {
    SrvAppRt::Sync(handler) => {
      // Don't support test mode when running as a windows service
      crate::rt::rttype::sync_main(handler, reporter, Some(rx), false)
      crate::rt::rttype::sync_main(re, handler, reporter, Some(rx), false)
    }
    #[cfg(feature = "tokio")]
    SrvAppRt::Tokio(rtbldr, handler) => {
      crate::rt::rttype::tokio_main(rtbldr, handler, reporter, Some(rx))
      crate::rt::rttype::tokio_main(rtbldr, re, handler, reporter, Some(rx))
    }
    #[cfg(feature = "rocket")]
    SrvAppRt::Rocket(handler) => {
      crate::rt::rttype::rocket_main(handler, reporter, Some(rx))
      crate::rt::rttype::rocket_main(re, handler, reporter, Some(rx))
    }
  }
}


// Generate the windows service boilerplate.  The boilerplate contains the
// low-level service entry function (ffi_service_main) that parses incoming

use std::sync::Arc;

use parking_lot::Mutex;

use qsu::rt::{ServiceHandler, StartState, StopState, SvcEvtReader};
use qsu::rt::{InitCtx, RunEnv, ServiceHandler, SvcEvtReader, TermCtx};

#[cfg(feature = "tokio")]
use qsu::rt::TokioServiceHandler;


#[cfg(feature = "rocket")]
use qsu::{

    self.fail.shutdown();
    self
  }
}


impl ServiceHandler for MySyncService {
  fn init(&mut self, _ss: StartState) -> Result<(), qsu::AppErr> {
  fn init(&mut self, _ictx: InitCtx) -> Result<(), qsu::AppErr> {
    self.visited.lock().init = true;
    if self.fail.init {
      Err(Error::hello("From Sync::init()"))?;
    }
    Ok(())
  }

  fn run(
    &mut self,
    _re: &RunEnv,
    _set: SvcEvtReader
  fn run(&mut self, _set: SvcEvtReader) -> Result<(), qsu::AppErr> {
  ) -> Result<(), qsu::AppErr> {
    self.visited.lock().run = true;
    if self.fail.run {
      Err(Error::hello("From Sync::run()"))?;
    }
    Ok(())
  }

  fn shutdown(&mut self, _ss: StopState) -> Result<(), qsu::AppErr> {
  fn shutdown(&mut self, _tctx: TermCtx) -> Result<(), qsu::AppErr> {
    self.visited.lock().shutdown = true;
    if self.fail.shutdown {
      Err(Error::hello("From Sync::shutdown()"))?;
    }
    Ok(())
  }
}

    self
  }
}

#[cfg(feature = "tokio")]
#[qsu::async_trait]
impl TokioServiceHandler for MyTokioService {
  async fn init(&mut self, _ss: StartState) -> Result<(), qsu::AppErr> {
  async fn init(&mut self, _ictx: InitCtx) -> Result<(), qsu::AppErr> {
    self.visited.lock().init = true;
    if self.fail.init {
      Err(Error::hello("From Tokio::init()"))?;
    }
    Ok(())
  }

  async fn run(
    &mut self,
    _re: &RunEnv,
    _set: SvcEvtReader
  async fn run(&mut self, _set: SvcEvtReader) -> Result<(), qsu::AppErr> {
  ) -> Result<(), qsu::AppErr> {
    self.visited.lock().run = true;
    if self.fail.run {
      Err(Error::hello("From Tokio::run()"))?;
    }
    Ok(())
  }

  async fn shutdown(&mut self, _ss: StopState) -> Result<(), qsu::AppErr> {
  async fn shutdown(&mut self, _tctx: TermCtx) -> Result<(), qsu::AppErr> {
    self.visited.lock().shutdown = true;
    if self.fail.shutdown {
      Err(Error::hello("From Tokio::shutdown()"))?;
    }
    Ok(())
  }
}

}

#[cfg(feature = "rocket")]
#[qsu::async_trait]
impl RocketServiceHandler for MyRocketService {
  async fn init(
    &mut self,
    _ss: StartState
    _ictx: InitCtx
  ) -> Result<Vec<Rocket<Build>>, qsu::AppErr> {
    self.visited.lock().init = true;
    if self.fail.init {
      Err(Error::hello("From Rocket::init()"))?;
    }
    Ok(Vec::new())
  }

  async fn run(
    &mut self,
    _rockets: Vec<Rocket<Ignite>>,
    _re: &RunEnv,
    _set: SvcEvtReader
  ) -> Result<(), qsu::AppErr> {
    self.visited.lock().run = true;
    if self.fail.run {
      Err(Error::hello("From Rocket::run()"))?;
    }
    Ok(())
  }

  async fn shutdown(&mut self, _ss: StopState) -> Result<(), qsu::AppErr> {
  async fn shutdown(&mut self, _tctx: TermCtx) -> Result<(), qsu::AppErr> {
    self.visited.lock().shutdown = true;
    if self.fail.shutdown {
      Err(Error::hello("From Rocket::shutdown()"))?;
    }
    Ok(())
  }
}

// vim: set ft=rust et sw=2 ts=2 sts=2 cinoptions=2 tw=79 :

# Change log

## [Unreleased]

[Details](/vdiff?from=qsu-0.3.0&to=trunk)
[Details](/vdiff?from=qsu-0.4.0&to=trunk)

### Added

### Changed

### Removed

---

## [0.4.0] - 2024-03-22

[Details](/vdiff?from=qsu-0.3.0&to=qsu-0.4.0)

### Added

- Add a `rt::RunEnv` type that is passed to application handler callbacks,
  allowing the application to be information about whether they are being run
  as foreground processes or as services.

### Changed

- Replace `StartState` and `StopState` with `InitCtx` and `TermCtx`, each of
  which also contain a `RunEnv`.

---

## [0.3.0] - 2024-01-30

[Details](/vdiff?from=qsu-0.2.1&to=qsu-0.3.0)

### Changed