Debian Codegraph @

upstream/mageia-cauldron/man3pm/TAP::Parser::Scheduler.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "TAP::Parser::Scheduler 3pm"
61 .TH TAP::Parser::Scheduler 3pm 2025-06-24 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 TAP::Parser::Scheduler \- Schedule tests during parallel testing
68 .SH VERSION
69 .IX Header "VERSION"
70 Version 3.50
71 .SH SYNOPSIS
72 .IX Header "SYNOPSIS"
73 .Vb 1
74 \& use TAP::Parser::Scheduler;
75 .Ve
76 .SH DESCRIPTION
77 .IX Header "DESCRIPTION"
78 .SH METHODS
79 .IX Header "METHODS"
80 .SS "Class Methods"
81 .IX Subsection "Class Methods"
82 \fR\f(CI\*(C`new\*(C'\fR\fI\fR
83 .IX Subsection "new"
84 .PP
85 .Vb 5
86 \& my $sched = TAP::Parser::Scheduler\->new(tests => \e@tests);
87 \& my $sched = TAP::Parser::Scheduler\->new(
88 \& tests => [ [\*(Aqt/test_name.t\*(Aq,\*(AqTest Description\*(Aq], ... ],
89 \& rules => \e%rules,
90 \& );
91 .Ve
92 .PP
93 Given \*(Aqtests\*(Aq and optional \*(Aqrules\*(Aq as input, returns a new
94 \&\f(CW\*(C`TAP::Parser::Scheduler\*(C'\fR object. Each member of \f(CW@tests\fR should be either a
95 a test file name, or a two element arrayref, where the first element is a test
96 file name, and the second element is a test description. By default, we\*(Aqll use
97 the test name as the description.
98 .PP
99 The optional \f(CW\*(C`rules\*(C'\fR attribute provides direction on which tests should be run
100 in parallel and which should be run sequentially. If no rule data structure is
101 provided, a default data structure is used which makes every test eligible to
102 be run in parallel:
103 .PP
104 .Vb 1
105 \& { par => \*(Aq**\*(Aq },
106 .Ve
107 .PP
108 The rules data structure is documented more in the next section.
109 .SS "Rules data structure"
110 .IX Subsection "Rules data structure"
111 The "\f(CW\*(C`rules\*(C'\fR" data structure is the the heart of the scheduler. It allows you
112 to express simple rules like "run all tests in sequence" or "run all tests in
113 parallel except these five tests.". However, the rules structure also supports
114 glob\-style pattern matching and recursive definitions, so you can also express
115 arbitarily complicated patterns.
116 .PP
117 The rule must only have one top level key: either \*(Aqpar\*(Aq for "parallel" or \*(Aqseq\*(Aq
118 for "sequence".
119 .PP
120 Values must be either strings with possible glob\-style matching, or arrayrefs
121 of strings or hashrefs which follow this pattern recursively.
122 .PP
123 Every element in an arrayref directly below a \*(Aqpar\*(Aq key is eligible to be run
124 in parallel, while vavalues directly below a \*(Aqseq\*(Aq key must be run in sequence.
125 .PP
126 \fIRules examples\fR
127 .IX Subsection "Rules examples"
128 .PP
129 Here are some examples:
130 .PP
131 .Vb 2
132 \& # All tests be run in parallel (the default rule)
133 \& { par => \*(Aq**\*(Aq },
134 \&
135 \& # Run all tests in sequence, except those starting with "p"
136 \& { par => \*(Aqt/p*.t\*(Aq },
137 \&
138 \& # Run all tests in parallel, except those starting with "p"
139 \& {
140 \& seq => [
141 \& { seq => \*(Aqt/p*.t\*(Aq },
142 \& { par => \*(Aq**\*(Aq },
143 \& ],
144 \& }
145 \&
146 \& # Run some startup tests in sequence, then some parallel tests then some
147 \& # teardown tests in sequence.
148 \& {
149 \& seq => [
150 \& { seq => \*(Aqt/startup/*.t\*(Aq },
151 \& { par => [\*(Aqt/a/*.t\*(Aq,\*(Aqt/b/*.t\*(Aq,\*(Aqt/c/*.t\*(Aq], }
152 \& { seq => \*(Aqt/shutdown/*.t\*(Aq },
153 \& ],
154 \& },
155 .Ve
156 .PP
157 \fIRules resolution\fR
158 .IX Subsection "Rules resolution"
159 .IP \(bu 4
160 By default, all tests are eligible to be run in parallel. Specifying any of your own rules removes this one.
161 .IP \(bu 4
162 "First match wins". The first rule that matches a test will be the one that applies.
163 .IP \(bu 4
164 Any test which does not match a rule will be run in sequence at the end of the run.
165 .IP \(bu 4
166 The existence of a rule does not imply selecting a test. You must still specify the tests to run.
167 .IP \(bu 4
168 Specifying a rule to allow tests to run in parallel does not make the run in parallel. You still need specify the number of parallel \f(CW\*(C`jobs\*(C'\fR in your Harness object.
169 .PP
170 \fIGlob\-style pattern matching for rules\fR
171 .IX Subsection "Glob-style pattern matching for rules"
172 .PP
173 We implement our own glob\-style pattern matching. Here are the patterns it supports:
174 .PP
175 .Vb 5
176 \& ** is any number of characters, including /, within a pathname
177 \& * is zero or more characters within a filename/directory name
178 \& ? is exactly one character within a filename/directory name
179 \& {foo,bar,baz} is any of foo, bar or baz.
180 \& \e is an escape character
181 .Ve
182 .SS "Instance Methods"
183 .IX Subsection "Instance Methods"
184 \fR\f(CI\*(C`get_all\*(C'\fR\fI\fR
185 .IX Subsection "get_all"
186 .PP
187 Get a list of all remaining tests.
188 .PP
189 \fR\f(CI\*(C`get_job\*(C'\fR\fI\fR
190 .IX Subsection "get_job"
191 .PP
192 Return the next available job as TAP::Parser::Scheduler::Job object or
193 \&\f(CW\*(C`undef\*(C'\fR if none are available. Returns a TAP::Parser::Scheduler::Spinner if
194 the scheduler still has pending jobs but none are available to run right now.
195 .PP
196 \fR\f(CI\*(C`as_string\*(C'\fR\fI\fR
197 .IX Subsection "as_string"
198 .PP
199 Return a human readable representation of the scheduling tree.
200 For example:
201 .PP
202 .Vb 3
203 \& my @tests = (qw{
204 \& t/startup/foo.t
205 \& t/shutdown/foo.t
206 \&
207 \& t/a/foo.t t/b/foo.t t/c/foo.t t/d/foo.t
208 \& });
209 \& my $sched = TAP::Parser::Scheduler\->new(
210 \& tests => \e@tests,
211 \& rules => {
212 \& seq => [
213 \& { seq => \*(Aqt/startup/*.t\*(Aq },
214 \& { par => [\*(Aqt/a/*.t\*(Aq,\*(Aqt/b/*.t\*(Aq,\*(Aqt/c/*.t\*(Aq] },
215 \& { seq => \*(Aqt/shutdown/*.t\*(Aq },
216 \& ],
217 \& },
218 \& );
219 .Ve
220 .PP
221 Produces:
222 .PP
223 .Vb 10
224 \& par:
225 \& seq:
226 \& par:
227 \& seq:
228 \& par:
229 \& seq:
230 \& \*(Aqt/startup/foo.t\*(Aq
231 \& par:
232 \& seq:
233 \& \*(Aqt/a/foo.t\*(Aq
234 \& seq:
235 \& \*(Aqt/b/foo.t\*(Aq
236 \& seq:
237 \& \*(Aqt/c/foo.t\*(Aq
238 \& par:
239 \& seq:
240 \& \*(Aqt/shutdown/foo.t\*(Aq
241 \& \*(Aqt/d/foo.t\*(Aq
242 .Ve