NAME

       Test2::Harness::Runner::Resource::SharedJobSlots - limit the job count (-j) per machine

SYNOPSIS

       This synopsis is not about using this in code, but rather how to use it on the command
       line.

       In order to use SharedJobSlots you must ether create the ".sharedjobslots.yml" file, or
       provide the "--shared-jobs-config PATH" argument on the command line.  The "PATH" must be
       a path to a yaml file with configuration specifications for job sharing.

CONFIG FILE

       Config files for shared slots must be yaml file, they must also be parsable by YAML::Tiny,
       which implements a subset of yaml.

       Here is an example config file:

           ---
           DEFAULT:
             state_file: /tmp/yath-slot-state
             max_slots:  8
             max_slots_per_job: 2
             max_slots_per_run: 6

           myhostname:
             state_file: /tmp/myhostname-slot-state
             max_slots:  16
             max_slots_per_job: 4
             max_slots_per_run: 12

   TOP LEVEL KEYS (HOSTNAMES)
       All top level keys are hostnames. When the config is read the settings for the current
       hostname will be used. If the hostname is not defined then the "DEFAULT" host will be
       read. If there is no "DEFAULT" host defined an exception will be thrown.

   CONFIG OPTIONS
       Each option must be specified under a hostname, none of these are valid on their own.

       state_file: /path/to/shared/state/file
           REQUIRED

           This specifies the path to the shared state file. All yath processes by all users who
           are sharing slots need read+write access to this file.

       state_umask: 0007
           Defaults to 0007. Used to set the umask of the state file as well as the lock file.

       max_slots: 8
           Max slots system-wide for all users to share.

       max_slots_per_run: 4
           Max slots a specific test run can use.

       min_slots_per_run: 0
           Minimum slots per run.

           Set this if you want to make sure that all runs get at least N slots, EVEN IF IT MEANS
           GOING OVER THE SYSTEM-WIDE MAXIMUM!.

           This defaults to 0.

       max_slots_per_job: 2
           Max slots a specific test job (test file) can use.

       default_slots_per_run: 4
           If the user does not specify a number of slots, use this as the default.

       default_slots_per_job: 2
           If the user does not specify a number of job slots, use this as the default.

       algorithm: fair
       algorithm: first
       algorithm: Fully::Qualified::Module::function_name
           Algorithm to use when assigning slots. 'fair' is the default.

       ALGORITHMS

       These are algorithms that are used to decide which test runs get which slots.

       fair
           DEFAULT

           This algorithm tries to balance slots so that all runs share an equal fraction of
           available slots. If there are not enough slots to go around then priority goes to
           oldest runs, followed by oldest requests.

       first
           Priority goes to the oldest run, followed by the next oldest, etc. If the run age is
           not sufficient to sort requests this will fall back to 'fair'.

           This is mainly useful for CI systems or batched test boxes. This will give priority to
           the first test run started, so additional test runs will not consume slots the first
           run wants to use, but if the first run is winding down and does not need all the
           slots, the second test run can start using only the spare slots.

           Use this with ordered test runs where you do not want a purely serial run order.

       Fully::Qualified::Module::function_name
           You can specify custom algorithms by giving fully qualified subroutine names.

       Example custom algorithm:

           sub custom_sort {
               my ($state_object, $state_data, $a, $b) = @_;

               return 1 if a_should_come_first($a, $b);
               return -1 if b_should_come_first($a, $b);
               return 0 if both_have_same_priority($a, $b);

               # *shrug*
               return 0;
           }

       Ultimately this is used in a "sort()" call, usual rules apply, return should be 1, 0, or
       -1. $a and $b are the 2 items being compared. $state_object is an instance of
       "Test2::Harness::Runner::Resource::SharedJobSlots::State".  $state_data is a hashref like
       you get from "$state_object->state()" which is useful if you want to know how many slots
       each runner is using for a 'fair' style algorth.

       Take a look at the "request_sort_XXX" methods on
       "Test2::Harness::Runner::Resource::SharedJobSlots::State" which implement the 3 original
       sorting methods.

SOURCE

       The source code repository for Test2-Harness can be found at
       http://github.com/Test-More/Test2-Harness/.

MAINTAINERS

       Chad Granum <exodist@cpan.org>

AUTHORS

       Chad Granum <exodist@cpan.org>

COPYRIGHT

       Copyright 2022 Chad Granum <exodist7@gmail.com>.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

       See http://dev.perl.org/licenses/

perl v5.36.0                                Test2::Harness::Runner::Resource::SharedJobSlots(3pm)