.\" -*- 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