.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Lintian::Unpacker 3"
.TH Lintian::Unpacker 3 "2019-11-07" "Lintian v2.33.0~bpo10+1" "Debian Package Checker"
.\" 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"
Lintian::Unpacker \-\- Job handler to unpack collections
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& use Lintian::DepMap::Properties;
\& use Lintian::Unpacker;
\&
\& my $done = 1;
\& my $joblimit = 4;
\& my $collmap = Lintian::DepMap::Properties\->new;
\& my %requested = ( \*(Aqdebfiles\*(Aq => 1 );
\& # Initialise $collmap with the collections and their relations
\& # \- Each node in $collmap should an instance of L::CollScript
\& #   as property.
\& my $unpacker = Lintian::Unpacker\->new ($collmap, \e%requested,
\&                                        $joblimit);
\&
\& while (1) {
\&     my $errhandler = sub {}; # Insert hook
\&     my @lpkgs; # List of Lintian::Lab::Entry instances
\&     $unpacker\->reset_worklist;
\&     next unless $unpacker\->prepare_tasks ($errhandler, @lpkgs);
\&
\&     my %hooks = (
\&         \*(Aqcoll\-hook\*(Aq => sub {}, # Insert hook
\&         \*(Aqfinish\-hook\*(Aq => sub {}, # Insert hook
\&     );
\&     $unpacker\->process_tasks ();
\&     last if $done;
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
An unpacker class to extract data from lab entries and make it
available via Lintian::Collect.
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.IP "init (\s-1COLLMAP,\s0 PROFILE[, \s-1OPTIONS\s0])" 4
.IX Item "init (COLLMAP, PROFILE[, OPTIONS])"
Creates a new unpacker.
.Sp
\&\s-1COLLMAP\s0 is a Lintian::DepMap::Properties describing the dependencies
between the collections.  Each node in \s-1COLLMAP\s0 must have a
Lintian::CollScript as property.
.Sp
\&\s-1OPTIONS\s0 is an optional hashref containing optional configurations.  If
a key is not present, its value is assumed to be \f(CW\*(C`undef\*(C'\fR unless
otherwise stated.  The following key/values are available:
.RS 4
.ie n .IP """profile""" 4
.el .IP "``profile''" 4
.IX Item "profile"
If this key is present and its value is defined, the value must be
Lintian::Profile.  The unpacker will use the enabled checks of the
Profile to determine what collections to use.
.Sp
If \*(L"profile\*(R" is not present or its value is undefined, then all
collections in \s-1COLLMAP\s0 will be unpacked.
.ie n .IP """extra-coll""" 4
.el .IP "``extra-coll''" 4
.IX Item "extra-coll"
If this key is present and its value is defined, it must be a
reference to a hash table.  The keys are considered names of \*(L"extra\*(R"
collections to unpack.  The values in this table is ignored.
.Sp
Extra collections will be unpacked on top of other collections.
.Sp
\&\s-1NB:\s0 This value is ignored if \*(L"profile\*(R" is not given.
.ie n .IP """jobs""" 4
.el .IP "``jobs''" 4
.IX Item "jobs"
This value is the max number of jobs to be run in parallel.  Can be
changed with the \*(L"jobs\*(R" method later.  If omitted, it defaults to
0.  Refer to \*(L"jobs\*(R" for more info.
.RE
.RS 4
.RE
.SH "INSTANCE METHODS"
.IX Header "INSTANCE METHODS"
.IP "prepare_tasks (\s-1ERRHANDLER,\s0 LAB-ENTRY...)" 4
.IX Item "prepare_tasks (ERRHANDLER, LAB-ENTRY...)"
Prepare a number of lab entries for unpacking.
.Sp
The \s-1ERRHANDLER\s0 should be a code ref, which will be invoked in case
that an entry is not in the laboratory and cannot be created (via
the create method).  It is invoked once per failed entry giving the
entry as first (and only) argument.
.Sp
If \s-1ERRHANDLER\s0 returns normally, the entry is skipped (and will not be
unpacked later).  If \s-1ERRHANDLER\s0 croaks/dies/etc., the method will
attempt to update the status file for any entry it created before
passing back the error to the caller (via die).
.Sp
LAB-ENTRY is an array of lab entries to be processed.  They must be
instances of Lintian::Lab::Entry, but do not have to exists.  They
will be created as needed.
.Sp
Returns a truth value if at least one entry needs to be processed
and it did not cause an error.  Otherwise, it returns \f(CW\*(C`undef\*(C'\fR.
.Sp
\&\s-1NB:\s0 The status file is not updated for created entries on successful
return.  It should either be done by running the process_tasks method
or manually.
.IP "process_tasks (\s-1HOOKS\s0)" 4
.IX Item "process_tasks (HOOKS)"
Process the current tasks.  This method blocks until all tasks and
jobs have terminated.
.Sp
The return value is unspecified.
.Sp
\&\s-1HOOKS\s0 (if given) is a hashref of hooks.  The following hooks are available:
.RS 4
.IP "coll-hook (\s-1LPKG, EVENT, COLL,\s0 TASK_ID[, \s-1STATUS_OR_ERROR_MSG\s0])" 4
.IX Item "coll-hook (LPKG, EVENT, COLL, TASK_ID[, STATUS_OR_ERROR_MSG])"
Called each time a new collection job is started or finished.
.Sp
\&\s-1LPKG\s0 is the entry it is applied to.  \s-1COLL\s0 is
the collection being applied.  \s-1EVENT\s0 is either
\&\*(L"start\*(R" for a new job, \*(L"start-failed\*(R" for a job that failed to
start (appears instead of a \*(L"start\*(R" event) or \*(L"finish\*(R" for a job
terminating.
.Sp
\&\s-1TASK_ID\s0 is the task id of the job (a string).
.Sp
If the event is \*(L"finish\*(R", then \s-1STATUS_OR_ERROR_MSG\s0 is the exit code of
the job (non-zero being an error).  If the event is \*(L"start-failed\*(R", it
is an error message explaining why the job failed to start.  It is not
defined for other events.
.RE
.RS 4
.RE
.IP "reset_worklist" 4
.IX Item "reset_worklist"
Wait for all running jobs (see \*(L"wait_for_jobs\*(R") and discard the
current worklist.
.IP "wait_for_jobs" 4
.IX Item "wait_for_jobs"
Block and wait for all running jobs to terminate.  Usually this is not
needed unless process_tasks was interrupted somehow.
.IP "kill_jobs" 4
.IX Item "kill_jobs"
Forcefully terminate all running jobs.  Usually this is not needed
unless process_tasks was interrupted somehow.
.IP "jobs" 4
.IX Item "jobs"
Returns or sets the max number of jobs to be processed in parallel.
.Sp
If the limit is 0, then there is no limit for the number of parallel
jobs.
.SH "AUTHOR"
.IX Header "AUTHOR"
Originally written by Niels Thykier <niels@thykier.net> for Lintian.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBlintian\fR\|(1), \fBLintian::CollScript\fR\|(3), \fBLintian::Lab::Entry\fR\|(3)