Debian Codegraph @

upstream/debian-unstable/man3/TAP::Parser::Scheduler.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (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 .\"
57 .IX Title "TAP::Parser::Scheduler 3perl"
58 .TH TAP::Parser::Scheduler 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 TAP::Parser::Scheduler \- Schedule tests during parallel testing
65 .SH VERSION
66 .IX Header "VERSION"
67 Version 3.48
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use TAP::Parser::Scheduler;
72 .Ve
73 .SH DESCRIPTION
74 .IX Header "DESCRIPTION"
75 .SH METHODS
76 .IX Header "METHODS"
77 .SS "Class Methods"
78 .IX Subsection "Class Methods"
79 \fR\f(CI\*(C`new\*(C'\fR\fI\fR
80 .IX Subsection "new"
81 .PP
82 .Vb 5
83 \& my $sched = TAP::Parser::Scheduler\->new(tests => \e@tests);
84 \& my $sched = TAP::Parser::Scheduler\->new(
85 \& tests => [ [\*(Aqt/test_name.t\*(Aq,\*(AqTest Description\*(Aq], ... ],
86 \& rules => \e%rules,
87 \& );
88 .Ve
89 .PP
90 Given 'tests' and optional 'rules' as input, returns a new
91 \&\f(CW\*(C`TAP::Parser::Scheduler\*(C'\fR object. Each member of \f(CW@tests\fR should be either a
92 a test file name, or a two element arrayref, where the first element is a test
93 file name, and the second element is a test description. By default, we'll use
94 the test name as the description.
95 .PP
96 The optional \f(CW\*(C`rules\*(C'\fR attribute provides direction on which tests should be run
97 in parallel and which should be run sequentially. If no rule data structure is
98 provided, a default data structure is used which makes every test eligible to
99 be run in parallel:
100 .PP
101 .Vb 1
102 \& { par => \*(Aq**\*(Aq },
103 .Ve
104 .PP
105 The rules data structure is documented more in the next section.
106 .SS "Rules data structure"
107 .IX Subsection "Rules data structure"
108 The "\f(CW\*(C`rules\*(C'\fR" data structure is the the heart of the scheduler. It allows you
109 to express simple rules like "run all tests in sequence" or "run all tests in
110 parallel except these five tests.". However, the rules structure also supports
111 glob-style pattern matching and recursive definitions, so you can also express
112 arbitarily complicated patterns.
113 .PP
114 The rule must only have one top level key: either 'par' for "parallel" or 'seq'
115 for "sequence".
116 .PP
117 Values must be either strings with possible glob-style matching, or arrayrefs
118 of strings or hashrefs which follow this pattern recursively.
119 .PP
120 Every element in an arrayref directly below a 'par' key is eligible to be run
121 in parallel, while vavalues directly below a 'seq' key must be run in sequence.
122 .PP
123 \fIRules examples\fR
124 .IX Subsection "Rules examples"
125 .PP
126 Here are some examples:
127 .PP
128 .Vb 2
129 \& # All tests be run in parallel (the default rule)
130 \& { par => \*(Aq**\*(Aq },
131 \&
132 \& # Run all tests in sequence, except those starting with "p"
133 \& { par => \*(Aqt/p*.t\*(Aq },
134 \&
135 \& # Run all tests in parallel, except those starting with "p"
136 \& {
137 \& seq => [
138 \& { seq => \*(Aqt/p*.t\*(Aq },
139 \& { par => \*(Aq**\*(Aq },
140 \& ],
141 \& }
142 \&
143 \& # Run some startup tests in sequence, then some parallel tests then some
144 \& # teardown tests in sequence.
145 \& {
146 \& seq => [
147 \& { seq => \*(Aqt/startup/*.t\*(Aq },
148 \& { par => [\*(Aqt/a/*.t\*(Aq,\*(Aqt/b/*.t\*(Aq,\*(Aqt/c/*.t\*(Aq], }
149 \& { seq => \*(Aqt/shutdown/*.t\*(Aq },
150 \& ],
151 \& },
152 .Ve
153 .PP
154 \fIRules resolution\fR
155 .IX Subsection "Rules resolution"
156 .IP \(bu 4
157 By default, all tests are eligible to be run in parallel. Specifying any of your own rules removes this one.
158 .IP \(bu 4
159 "First match wins". The first rule that matches a test will be the one that applies.
160 .IP \(bu 4
161 Any test which does not match a rule will be run in sequence at the end of the run.
162 .IP \(bu 4
163 The existence of a rule does not imply selecting a test. You must still specify the tests to run.
164 .IP \(bu 4
165 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.
166 .PP
167 \fIGlob-style pattern matching for rules\fR
168 .IX Subsection "Glob-style pattern matching for rules"
169 .PP
170 We implement our own glob-style pattern matching. Here are the patterns it supports:
171 .PP
172 .Vb 5
173 \& ** is any number of characters, including /, within a pathname
174 \& * is zero or more characters within a filename/directory name
175 \& ? is exactly one character within a filename/directory name
176 \& {foo,bar,baz} is any of foo, bar or baz.
177 \& \e is an escape character
178 .Ve
179 .SS "Instance Methods"
180 .IX Subsection "Instance Methods"
181 \fR\f(CI\*(C`get_all\*(C'\fR\fI\fR
182 .IX Subsection "get_all"
183 .PP
184 Get a list of all remaining tests.
185 .PP
186 \fR\f(CI\*(C`get_job\*(C'\fR\fI\fR
187 .IX Subsection "get_job"
188 .PP
189 Return the next available job as TAP::Parser::Scheduler::Job object or
190 \&\f(CW\*(C`undef\*(C'\fR if none are available. Returns a TAP::Parser::Scheduler::Spinner if
191 the scheduler still has pending jobs but none are available to run right now.
192 .PP
193 \fR\f(CI\*(C`as_string\*(C'\fR\fI\fR
194 .IX Subsection "as_string"
195 .PP
196 Return a human readable representation of the scheduling tree.
197 For example:
198 .PP
199 .Vb 3
200 \& my @tests = (qw{
201 \& t/startup/foo.t
202 \& t/shutdown/foo.t
203 \&
204 \& t/a/foo.t t/b/foo.t t/c/foo.t t/d/foo.t
205 \& });
206 \& my $sched = TAP::Parser::Scheduler\->new(
207 \& tests => \e@tests,
208 \& rules => {
209 \& seq => [
210 \& { seq => \*(Aqt/startup/*.t\*(Aq },
211 \& { par => [\*(Aqt/a/*.t\*(Aq,\*(Aqt/b/*.t\*(Aq,\*(Aqt/c/*.t\*(Aq] },
212 \& { seq => \*(Aqt/shutdown/*.t\*(Aq },
213 \& ],
214 \& },
215 \& );
216 .Ve
217 .PP
218 Produces:
219 .PP
220 .Vb 10
221 \& par:
222 \& seq:
223 \& par:
224 \& seq:
225 \& par:
226 \& seq:
227 \& \*(Aqt/startup/foo.t\*(Aq
228 \& par:
229 \& seq:
230 \& \*(Aqt/a/foo.t\*(Aq
231 \& seq:
232 \& \*(Aqt/b/foo.t\*(Aq
233 \& seq:
234 \& \*(Aqt/c/foo.t\*(Aq
235 \& par:
236 \& seq:
237 \& \*(Aqt/shutdown/foo.t\*(Aq
238 \& \*(Aqt/d/foo.t\*(Aq
239 .Ve