diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3pm/TAP::Parser::Scheduler.3pm')
| -rw-r--r-- | upstream/mageia-cauldron/man3pm/TAP::Parser::Scheduler.3pm | 239 |
1 files changed, 239 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/TAP::Parser::Scheduler.3pm b/upstream/mageia-cauldron/man3pm/TAP::Parser::Scheduler.3pm new file mode 100644 index 00000000..02bf19fe --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/TAP::Parser::Scheduler.3pm @@ -0,0 +1,239 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "TAP::Parser::Scheduler 3pm" +.TH TAP::Parser::Scheduler 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +TAP::Parser::Scheduler \- Schedule tests during parallel testing +.SH VERSION +.IX Header "VERSION" +Version 3.44 +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& use TAP::Parser::Scheduler; +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +.SH METHODS +.IX Header "METHODS" +.SS "Class Methods" +.IX Subsection "Class Methods" +\fR\f(CI\*(C`new\*(C'\fR\fI\fR +.IX Subsection "new" +.PP +.Vb 5 +\& my $sched = TAP::Parser::Scheduler\->new(tests => \e@tests); +\& my $sched = TAP::Parser::Scheduler\->new( +\& tests => [ [\*(Aqt/test_name.t\*(Aq,\*(AqTest Description\*(Aq], ... ], +\& rules => \e%rules, +\& ); +.Ve +.PP +Given 'tests' and optional 'rules' as input, returns a new +\&\f(CW\*(C`TAP::Parser::Scheduler\*(C'\fR object. Each member of \f(CW@tests\fR should be either a +a test file name, or a two element arrayref, where the first element is a test +file name, and the second element is a test description. By default, we'll use +the test name as the description. +.PP +The optional \f(CW\*(C`rules\*(C'\fR attribute provides direction on which tests should be run +in parallel and which should be run sequentially. If no rule data structure is +provided, a default data structure is used which makes every test eligible to +be run in parallel: +.PP +.Vb 1 +\& { par => \*(Aq**\*(Aq }, +.Ve +.PP +The rules data structure is documented more in the next section. +.SS "Rules data structure" +.IX Subsection "Rules data structure" +The "\f(CW\*(C`rules\*(C'\fR" data structure is the the heart of the scheduler. It allows you +to express simple rules like "run all tests in sequence" or "run all tests in +parallel except these five tests.". However, the rules structure also supports +glob-style pattern matching and recursive definitions, so you can also express +arbitarily complicated patterns. +.PP +The rule must only have one top level key: either 'par' for "parallel" or 'seq' +for "sequence". +.PP +Values must be either strings with possible glob-style matching, or arrayrefs +of strings or hashrefs which follow this pattern recursively. +.PP +Every element in an arrayref directly below a 'par' key is eligible to be run +in parallel, while vavalues directly below a 'seq' key must be run in sequence. +.PP +\fIRules examples\fR +.IX Subsection "Rules examples" +.PP +Here are some examples: +.PP +.Vb 2 +\& # All tests be run in parallel (the default rule) +\& { par => \*(Aq**\*(Aq }, +\& +\& # Run all tests in sequence, except those starting with "p" +\& { par => \*(Aqt/p*.t\*(Aq }, +\& +\& # Run all tests in parallel, except those starting with "p" +\& { +\& seq => [ +\& { seq => \*(Aqt/p*.t\*(Aq }, +\& { par => \*(Aq**\*(Aq }, +\& ], +\& } +\& +\& # Run some startup tests in sequence, then some parallel tests then some +\& # teardown tests in sequence. +\& { +\& seq => [ +\& { seq => \*(Aqt/startup/*.t\*(Aq }, +\& { par => [\*(Aqt/a/*.t\*(Aq,\*(Aqt/b/*.t\*(Aq,\*(Aqt/c/*.t\*(Aq], } +\& { seq => \*(Aqt/shutdown/*.t\*(Aq }, +\& ], +\& }, +.Ve +.PP +\fIRules resolution\fR +.IX Subsection "Rules resolution" +.IP \(bu 4 +By default, all tests are eligible to be run in parallel. Specifying any of your own rules removes this one. +.IP \(bu 4 +"First match wins". The first rule that matches a test will be the one that applies. +.IP \(bu 4 +Any test which does not match a rule will be run in sequence at the end of the run. +.IP \(bu 4 +The existence of a rule does not imply selecting a test. You must still specify the tests to run. +.IP \(bu 4 +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. +.PP +\fIGlob-style pattern matching for rules\fR +.IX Subsection "Glob-style pattern matching for rules" +.PP +We implement our own glob-style pattern matching. Here are the patterns it supports: +.PP +.Vb 5 +\& ** is any number of characters, including /, within a pathname +\& * is zero or more characters within a filename/directory name +\& ? is exactly one character within a filename/directory name +\& {foo,bar,baz} is any of foo, bar or baz. +\& \e is an escape character +.Ve +.SS "Instance Methods" +.IX Subsection "Instance Methods" +\fR\f(CI\*(C`get_all\*(C'\fR\fI\fR +.IX Subsection "get_all" +.PP +Get a list of all remaining tests. +.PP +\fR\f(CI\*(C`get_job\*(C'\fR\fI\fR +.IX Subsection "get_job" +.PP +Return the next available job as TAP::Parser::Scheduler::Job object or +\&\f(CW\*(C`undef\*(C'\fR if none are available. Returns a TAP::Parser::Scheduler::Spinner if +the scheduler still has pending jobs but none are available to run right now. +.PP +\fR\f(CI\*(C`as_string\*(C'\fR\fI\fR +.IX Subsection "as_string" +.PP +Return a human readable representation of the scheduling tree. +For example: +.PP +.Vb 3 +\& my @tests = (qw{ +\& t/startup/foo.t +\& t/shutdown/foo.t +\& +\& t/a/foo.t t/b/foo.t t/c/foo.t t/d/foo.t +\& }); +\& my $sched = TAP::Parser::Scheduler\->new( +\& tests => \e@tests, +\& rules => { +\& seq => [ +\& { seq => \*(Aqt/startup/*.t\*(Aq }, +\& { par => [\*(Aqt/a/*.t\*(Aq,\*(Aqt/b/*.t\*(Aq,\*(Aqt/c/*.t\*(Aq] }, +\& { seq => \*(Aqt/shutdown/*.t\*(Aq }, +\& ], +\& }, +\& ); +.Ve +.PP +Produces: +.PP +.Vb 10 +\& par: +\& seq: +\& par: +\& seq: +\& par: +\& seq: +\& \*(Aqt/startup/foo.t\*(Aq +\& par: +\& seq: +\& \*(Aqt/a/foo.t\*(Aq +\& seq: +\& \*(Aqt/b/foo.t\*(Aq +\& seq: +\& \*(Aqt/c/foo.t\*(Aq +\& par: +\& seq: +\& \*(Aqt/shutdown/foo.t\*(Aq +\& \*(Aqt/d/foo.t\*(Aq +.Ve |