1Test2::Harness::Runner:U:sReersoCTuoernsctter2:i::b:SuHhtaaerrdneedPsJesor:bl:SRlDuoontcnsue(mr3e:)n:tRaetsioounrce::SharedJobSlots(3)
2
3
4

NAME

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

SYNOPSIS

10       This synopsis is not about using this in code, but rather how to use it
11       on the command line.
12
13       In order to use SharedJobSlots you must ether create the
14       ".sharedjobslots.yml" file, or provide the "--shared-jobs-config PATH"
15       argument on the command line.  The "PATH" must be a path to a yaml file
16       with configuration specifications for job sharing.
17

CONFIG FILE

19       Config files for shared slots must be yaml file, they must also be
20       parsable by YAML::Tiny, which implements a subset of yaml.
21
22       Here is an example config file:
23
24           ---
25           DEFAULT:
26             state_file: /tmp/yath-slot-state
27             max_slots:  8
28             max_slots_per_job: 2
29             max_slots_per_run: 6
30
31           myhostname:
32             state_file: /tmp/myhostname-slot-state
33             max_slots:  16
34             max_slots_per_job: 4
35             max_slots_per_run: 12
36
37   TOP LEVEL KEYS (HOSTNAMES)
38       All top level keys are hostnames. When the config is read the settings
39       for the current hostname will be used. If the hostname is not defined
40       then the "DEFAULT" host will be read. If there is no "DEFAULT" host
41       defined an exception will be thrown.
42
43   CONFIG OPTIONS
44       Each option must be specified under a hostname, none of these are valid
45       on their own.
46
47       state_file: /path/to/shared/state/file
48           REQUIRED
49
50           This specifies the path to the shared state file. All yath
51           processes by all users who are sharing slots need read+write access
52           to this file.
53
54       state_umask: 0007
55           Defaults to 0007. Used to set the umask of the state file as well
56           as the lock file.
57
58       max_slots: 8
59           Max slots system-wide for all users to share.
60
61       max_slots_per_run: 4
62           Max slots a specific test run can use.
63
64       min_slots_per_run: 0
65           Minimum slots per run.
66
67           Set this if you want to make sure that all runs get at least N
68           slots, EVEN IF IT MEANS GOING OVER THE SYSTEM-WIDE MAXIMUM!.
69
70           This defaults to 0.
71
72       max_slots_per_job: 2
73           Max slots a specific test job (test file) can use.
74
75       default_slots_per_run: 4
76           If the user does not specify a number of slots, use this as the
77           default.
78
79       default_slots_per_job: 2
80           If the user does not specify a number of job slots, use this as the
81           default.
82
83       algorithm: fair
84       algorithm: first
85       algorithm: Fully::Qualified::Module::function_name
86           Algorithm to use when assigning slots. 'fair' is the default.
87
88       ALGORITHMS
89
90       These are algorithms that are used to decide which test runs get which
91       slots.
92
93       fair
94           DEFAULT
95
96           This algorithm tries to balance slots so that all runs share an
97           equal fraction of available slots. If there are not enough slots to
98           go around then priority goes to oldest runs, followed by oldest
99           requests.
100
101       first
102           Priority goes to the oldest run, followed by the next oldest, etc.
103           If the run age is not sufficient to sort requests this will fall
104           back to 'fair'.
105
106           This is mainly useful for CI systems or batched test boxes. This
107           will give priority to the first test run started, so additional
108           test runs will not consume slots the first run wants to use, but if
109           the first run is winding down and does not need all the slots, the
110           second test run can start using only the spare slots.
111
112           Use this with ordered test runs where you do not want a purely
113           serial run order.
114
115       Fully::Qualified::Module::function_name
116           You can specify custom algorithms by giving fully qualified
117           subroutine names.
118
119       Example custom algorithm:
120
121           sub custom_sort {
122               my ($state_object, $state_data, $a, $b) = @_;
123
124               return 1 if a_should_come_first($a, $b);
125               return -1 if b_should_come_first($a, $b);
126               return 0 if both_have_same_priority($a, $b);
127
128               # *shrug*
129               return 0;
130           }
131
132       Ultimately this is used in a sort() call, usual rules apply, return
133       should be 1, 0, or -1. $a and $b are the 2 items being compared.
134       $state_object is an instance of
135       "Test2::Harness::Runner::Resource::SharedJobSlots::State".  $state_data
136       is a hashref like you get from "$state_object->state()" which is useful
137       if you want to know how many slots each runner is using for a 'fair'
138       style algorth.
139
140       Take a look at the "request_sort_XXX" methods on
141       "Test2::Harness::Runner::Resource::SharedJobSlots::State" which
142       implement the 3 original sorting methods.
143

SOURCE

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

MAINTAINERS

149       Chad Granum <exodist@cpan.org>
150

AUTHORS

152       Chad Granum <exodist@cpan.org>
153

155       Copyright 2022 Chad Granum <exodist7@gmail.com>.
156
157       This program is free software; you can redistribute it and/or modify it
158       under the same terms as Perl itself.
159
160       See http://dev.perl.org/licenses/
161
162
163
164perl v5.38.0               Test2::2H0a2r3n-e1s0s-:0:4Runner::Resource::SharedJobSlots(3)
Impressum