<<

# Bugzilla::DaemonControl

- NAME
- SYNOPSIS
- DESCRIPTION
- FUNCTIONS
  - run_httpd()
  - run_cereal()
  - run_cereal_and_httpd()
  - assert_database()
  - assert_seleniuim()
  - assert_httpd()
  - on_finish($f)
  - on_exception($f)

# NAME

Bugzilla::DaemonControl - Utility functions for controlling daemons

# SYNOPSIS

        my $httpd_exit_code_f = run_httpd(@httpd_args);
        my $signal_f = catch_signal("TERM");

# DESCRIPTION

This module exports functions that either start daemons (run_httpd(), run_cereal()), check for running services (assert_httpd(), assert_database(), assert_selenium()), or help build more functions like the above (on_exception(), on_finish()).

The `run_` and `assert_` functions return Futures, see Future for details on that. But if you've used Promises in the JavaScript, Futures are the same concept.

# FUNCTIONS

Nothing is exported by default, but you can request `:all` for that. You can also just get the run_* functions with `:run`.

## run_httpd()

This function starts an httpd and returns a future that is done when the httpd exits. The return value will be the exit code of the process.

Thus the following program would exit with whatever value httpd exits with:

        exit run_httpd()->get;

It may also fail in unlikely situations, such as a fork() failing, httpd not being found, etc.

Canceling the future will send `SIGTERM` to httpd.

## run_cereal()

This runs a builtin process that listens on `localhost:5880` for TCP connections. Each connection may send lines of text, and those lines of text will be written to STDOUT. Once you start this, you should limit or stop entirely printing to STDOUT to ensure that output is well-ordered.

If you need to listen on a different port, set the environmental variable `LOGGING_PORT`.

This returns a future similar to run_httpd(). Canceling the future will terminate the cereal daemon.

## run_cereal_and_httpd()

This will start up cereal and the httpd. It will return a future that is done when either httpd or cereal exits. The future will also be done if `SIGTERM` is sent to the process that calls this function.

Because of how futures work, when one of these processes is done (or when we get the signal) the other futures are canceled.

This means that if cereal exits, httpd will exit. And if httpd exits, cereal will exit.

## assert_database()

This provides a simple way to wait on the database being up. It will either be done with no usable return value, or fail with a timeout error.

        # wait until we have a database
        assert_database()->get;

## assert_seleniuim()

This returns a future that is complete when we can reach selenium, or it fails with a timeout.

## assert_httpd()

This returns a future that is complete when we can reach the __lbheartbeat__ endpoint, or it fails with a timeout.

## on_finish($f)

This returns a callback that will complete a future. It is to be used with IO::Async::Process.

## on_exception($f)

This returns a callback that will fail a future. It is to be used with IO::Async::Process.

<<