Macro heph::restart_supervisor

source · [−]

macro_rules! restart_supervisor {
    ($vis: vis $supervisor_name: ident, $actor_name: expr $(,)*) => { ... };
    ($vis: vis $supervisor_name: ident, $actor_name: expr, () $(,)*) => { ... };
    ($vis: vis $supervisor_name: ident, $actor_name: expr, ( $( $arg: ty),* ) $(,)*) => { ... };
    ($vis: vis $supervisor_name: ident, $actor_name: expr, $arg: ty $(,)*) => { ... };
    ($vis: vis $supervisor_name: ident, $actor_name: expr, (), $max_restarts: expr, $max_duration: expr $(,)*) => { ... };
    ($vis: vis $supervisor_name: ident, $actor_name: expr, ( $( $arg: ty ),* ), $max_restarts: expr, $max_duration: expr $(,)*) => { ... };
    ($vis: vis $supervisor_name: ident, $actor_name: expr, $arg: ty, $max_restarts: expr, $max_duration: expr $(,)*) => { ... };
    ($vis: vis $supervisor_name: ident, $actor_name: expr, (), $max_restarts: expr, $max_duration: expr, $log_extra: expr, $( args $(. $log_arg_field: tt )* ),* $(,)*) => { ... };
    ($vis: vis $supervisor_name: ident, $actor_name: expr, ( $( $arg: ty ),* ), $max_restarts: expr, $max_duration: expr, $log_extra: expr, $( args $(. $log_arg_field: tt )* ),* $(,)*) => { ... };
    ($vis: vis $supervisor_name: ident, $actor_name: expr, $arg: ty, $max_restarts: expr, $max_duration: expr, $log_extra: expr, $( args $(. $log_arg_field: tt )* ),* $(,)*) => { ... };
}

Expand description

Macro to create a supervisor that logs the error and restarts the actor.

This creates a new type that implements the Supervisor and SyncSupervisor traits. The macro accepts the following arguments:

Visibility indicator (optional), defaults to private (i.e. no indicator).
Name of the new supervisor type.
Log friendly name of the actor, used in logging.
Type of the argument(s) used to restart the actor. Multiple arguments must be in the tuple format (same as for the NewActor::Argument type).
Maximum number of restarts (optional), defaults to 5.
Maximum duration before the restart counter get reset (optional), defaults to 5 seconds.
Additional logging message, defaults to nothing extra. This uses normal rust formatting rules and is added at the end of the default message, after the error. The args keyword gives access to the arguments. See example 7 Restart Supervisor (in the example directory of the source code).

The new type can be created using the new function, e.g. MySupervisor::new(args), see the example below.

Logged messages

When the actor failed and is restarted:

$actor_name failed, restarting it ($left/$max restarts left): ${error}$log_extra
my_actor failed, restarting it (1/2 restarts left): some I/O error: actor arguments (true, 0): (true, 0)

If the actor failed too many times to quickly it will log the following.

$actor_name failed, stopping it (no restarts left): ${error}$log_extra
my_actor failed, stopping it (no restarts left): some I/O error: actor arguments (true, 0): (true, 0)

Similar messages will be logged if the actor fails to restart.

Examples

The example below shows the simplest usage of the restart_supervisor macro. Example 7 Restart Supervisor (in the example directory of the source code) has a more complete example.

use std::time::Duration;

use heph::restart_supervisor;

// Creates the `MySupervisor` type.
restart_supervisor!(
    pub                      // Visibility indicator.
    MySupervisor,            // Name of the supervisor type.
    "my actor",              // Name of the actor.
    (bool, u32),             // Type of the arguments for the actor.
    2,                       // Maximum number of restarts.
    Duration::from_secs(30), // Maximum duration before the restart counter
                             // get reset, defaults to 5 seconds (optional).
    // This string is added to the log message after the error. `args`
    // gives access to the arguments.
    ": actor arguments {:?} ({}, {})",
    args,
    args.0,
    args.1,
);

// Create a new supervisor.
let supervisor = MySupervisor::new(true, 23);