Documentation
¶
Overview ¶
Package poppler runs the implementation that judges ours, under a bound.
It exists because of one document. pdfimages hangs for ever on pdfforms/gh-qpdf/qpdf_qtest_qpdf_shared-unnamed-field.pdf — 2496 bytes — and so do pdfimages -list and pdfinfo; two sweeps of this repository stalled on it and had to be killed by hand (conformance#21). That is a property of the judge rather than a defect of ours, and the consequence is what matters: a hang and a slow job are indistinguishable from outside, so a sweep that stops dead at document 900 of 2268 is waited on rather than investigated, and the wait has no end.
So every invocation of a poppler tool in this repository goes through Run, and a document that exceeds the bound is recorded BY NAME with the tool that hung, never dropped and never retried. A named timeout is data about the corpus; a silent one is a gap a reader cannot tell from a bad score.
The bound lives here rather than in each caller so that there is one setting and one reason for it, and so that a new caller cannot be written without one.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Timeout = 2 * time.Minute
Timeout is how long a poppler tool may take on one document before it is called a hang.
It is NOT calibrated from timings, and that is deliberate twice over. The machine these runs are made on is shared, so a duration measured on it measures the other job as much as this one; and a bound read off a loaded machine would fire on documents that are merely large. So it is set far above any plausible handling of a single page, which makes a firing mean a hang rather than a slow document — and every firing is named with the tool, so a reader can judge that rather than take the bound on trust.
It is a variable because a corpus of larger pages may want a larger one: both commands take a -timeout flag, and a baseline record carries the value its run used, beside the gate, because it is part of the instrument.
Functions ¶
func Combined ¶
Combined is Run with the tool's error output folded into its answer.
It exists because "pdfimages -v" prints its version on STDERR, so the one invocation whose whole purpose is to record WHICH poppler judged a run comes back empty from Run. That is not a small loss: the judge is half the measurement, and a filter whose agreement falls because poppler changed has not regressed — telling those apart afterwards is impossible if nobody wrote down which poppler it was.
It is separate from Run rather than replacing it because the callers that parse output must not have the tool's warnings folded into it: pdfimages -list is read column by column, and a line of complaint in the middle of the table is a row.
func DidNotFinish ¶
DidNotFinish is what a hang is reported as, in the words the bound is set in.
func Document ¶
Document makes a path safe to hand a poppler tool as a POSITIONAL argument.
Every one of these tools parses its arguments with getopt, so a path that begins with "-" is read as a flag and not as a file. None of them is given a "--" terminator here because the flags and the file are interleaved differently by each one, and a terminator in the wrong place is worse than none.
It is reachable, which is why it exists. harvest names a local file after an identifier a REMOTE SERVER chose -- strings.ReplaceAll(id, "/", "_") + ".pdf" -- so an identifier beginning with a dash becomes a corpus file beginning with a dash, and every later invocation hands poppler a flag. "-v.pdf" would make pdfimages print its version and take no picture; the harness would then record the page as one the judge drew nothing for.
"./" is the fix getopt itself prescribes and it changes nothing else: the path still names the same file, and a path that is already absolute or already relative-explicit is left alone so that an error message says what a reader typed.
func Run ¶
Run runs one poppler tool and says whether it was the bound that stopped it.
CommandContext kills the process when the deadline passes, and the deadline having passed is read off the CONTEXT rather than off the error, because a killed process reports a signal and a tool that merely failed reports a status — and telling a hang from a refusal is the whole point.
The output is returned for the callers that want it; the ones that only want to know whether it worked discard it.
Types ¶
This section is empty.
Source Files