[][src]Trait spirit::SpiritBuilder

pub trait SpiritBuilder: ConfigBuilder + Extensible {
    fn build(
        self,
        background_thread: bool
    ) -> Result<App<Self::Opts, Self::Config>, AnyError>;
fn run<B>(self, body: B)
    where
        B: FnOnce(&Arc<Spirit<Self::Opts, Self::Config>>) -> Result<(), AnyError> + Send + 'static
; }

An interface to turn the spirit Builder into a Spirit and possibly run it.

It is a trait to support a little trick. The run method has the ability to handle errors by logging them and then terminating the application with a non-zero exit code. It is convenient to include even the setup errors in this logging.

Therefore, the trait is implemented both on Builder and Result<Builder, AnyError> (and the other traits on Builder also support this trick). That way all the errors can be just transparently gathered and handled uniformly, without any error handling on the user side.

Examples

use spirit::{Empty, Spirit};
use spirit::prelude::*;

// This returns Builder
Spirit::<Empty, Empty>::new()
    // This method returns Result<Builder, AnyError>, but we don't handle the possible error with
    // ?.
    .run_before(|_| Ok(()))
    // The run lives both on Builder and Result<Builder, AnyError>. Here we call the latter.
    // If we get an error from above, the body here isn't run at all, but the error is handled
    // similarly as any errors from within the body.
    .run(|_| Ok(()))

Required methods

fn build(
    self,
    background_thread: bool
) -> Result<App<Self::Opts, Self::Config>, AnyError>

Finish building the Spirit.

This transitions from the configuration phase of Spirit to actually creating it. This loads the configuration and executes it for the first time. It launches the background thread for listening to signals and reloading configuration if the background_thread parameter is set to true.

This starts listening for signals, loads the configuration for the first time and starts the background thread.

This version returns the App (or error) and error handling is up to the caller. If you want spirit to take care of nice error logging (even for your application's top level errors), use run instead.

Warning

If asked to go to background (when you're using the spirit-daemonize crate, this uses fork. Therefore, start any threads after you call build (or from within run), or you'll lose them ‒ only the thread doing fork is preserved across it.

Panics

This will panic if background_thread is set to false and there are registered signals.

fn run<B>(self, body: B) where
    B: FnOnce(&Arc<Spirit<Self::Opts, Self::Config>>) -> Result<(), AnyError> + Send + 'static, 

Build the spirit and run the application, handling all relevant errors.

In case an error happens (either when creating the Spirit, or returned by the callback), the errors are logged (either to the place where logs are sent to in configuration, or to stderr if the error happens before logging is initialized ‒ for example if configuration can't be read). The application then terminates with failure exit code.

This mostly just wraps whatever the App::run_term does, but also handles the errors that already happened on the Builder.

use std::thread;
use std::time::Duration;

use spirit::{Empty, Spirit};
use spirit::prelude::*;

Spirit::<Empty, Empty>::new()
    .run(|spirit| {
        while !spirit.is_terminated() {
            // Some reasonable work here
            thread::sleep(Duration::from_millis(100));
        }

        Ok(())
    });
Loading content...

Implementations on Foreign Types

impl<O, C> SpiritBuilder for Result<Builder<O, C>, AnyError> where
    Self::Config: DeserializeOwned + Send + Sync + 'static,
    Self::Opts: StructOpt + Sync + Send + 'static, 
[src]

Loading content...

Implementors

impl<O, C> SpiritBuilder for Builder<O, C> where
    Self::Config: DeserializeOwned + Send + Sync + 'static,
    Self::Opts: StructOpt + Sync + Send + 'static, 
[src]

Loading content...