NAME

    HealthCheck::Parallel - A HealthCheck that uses parallelization for
    running checks

VERSION

    version v0.1.0

SYNOPSIS

        use HealthCheck::Parallel;
    
        my $hc = HealthCheck::Parallel->new(
            max_procs  => 4,      # default
            timeout    => 120,    # default, global timeout in seconds
            tempdir    => '/tmp', # override Parallel::ForkManager default
            child_init => sub { warn "Will run at start of child process check" },
            checks     => [
                sub { sleep 5; return { id => 'slow1', status => 'OK' } },
                sub { sleep 5; return { id => 'slow2', status => 'OK' } },
            ],
        );
    
        # Takes 5 seconds to run both checks instead of 10.
        my $res = $hc->check;
    
        # These checks will not use parallelization.
        $res = $hc->check( max_procs => 0 );
    
        # Neither will these.
        $res = $hc->check( max_procs => 1 );
    
        # Override timeout for specific check.
        $res = $hc->check( timeout => 60 );

DESCRIPTION

    This library inherits HealthCheck so that the provided checks are run
    in parallel.

METHODS

 new

    Overrides the "new" in HealthCheck constructor to additionally allow
    "max_procs" and "timeout" arguments for controlling parallelization and
    global timeout behavior.

ATTRIBUTES

 max_procs

    A positive integer (or coderef returning one) specifying the maximum
    number of processes that should be run in parallel when executing the
    checks. No parallelization will be used unless given a value that is
    greater than 1. Defaults to 4.

    If provided as a coderef, it will be called at runtime to determine the
    value, allowing dynamic adjustment:

        my $hc = HealthCheck::Parallel->new(
            max_procs => sub { int(rand(10)) },
            checks    => [ ... ],
        );

 child_init

    An optional coderef which will be run when the child process of a check
    is created. A possible important use case is making sure child
    processes don't try to make use of STDOUT if these checks are running
    under FastCGI envrionment:

        my $hc = HealthCheck::Parallel->new(
            child_init => sub {
                untie *STDOUT;
                { no warnings; *FCGI::DESTROY = sub {}; }
            },
        );

 tempdir

    Sets the tempdir value to use in Parallel::ForkManager for IPC.

 timeout

    A positive integer (or coderef returning one) specifying the maximum
    number of seconds to wait for all parallelized checks to complete. If
    the timeout is exceeded, all running child processes will be terminated
    and CRITICAL results will be returned for affected checks. Defaults to
    120 seconds.

    If provided as a coderef, it will be called at runtime to determine the
    value, allowing dynamic adjustment:

        my $hc = HealthCheck::Parallel->new(
            timeout => sub { int(rand(10)) },
            checks  => [ ... ],
        );

    Note: The timeout only applies when parallelization is enabled
    (max_procs > 1). When max_procs is 0 or 1, checks run in the parent
    process and the timeout is not used.

    The timeout is implemented using a non-blocking polling loop instead of
    using any signal-based timeouts to potentially avoiding conflicting
    with others.

DEPENDENCIES

      * Perl 5.10 or higher.

      * HealthCheck

      * Parallel::ForkManager

SEE ALSO

      * HealthCheck::Diagnostic

      * The GSG Health Check Standard
      <https://grantstreetgroup.github.io/HealthCheck.html>.

AUTHOR

    Grant Street Group <developers@grantstreet.com>

COPYRIGHT AND LICENSE

    This software is Copyright (c) 2023 - 2025 by Grant Street Group.

    This is free software, licensed under:

      The Artistic License 2.0 (GPL Compatible)