Next: Using the cookie to Up: Cookie Previous: Detecting errors Contents Index
Content interpretations can take a (relatively) long time. Once one has been started, it can be useful a) to know how far through processing we are, and b) to be able to abort processing should the results of a run no longer be required.
As a run progresses, 2 fields in the cookie are updated. Firstly, progress will be set to a number that increases as progress is made. Think of this informally as being the number of objects that have been processed so far. In some cases (notably when processing a display list) we can know an upper bound for this value, and this value will be given as progress_max. In cases where no upper bound is known, progress_max will be set to -1. It is possible that the upper bound may start as -1, and then change to a known value later.
These values are intended to enable user feedback to be given, and should not be taken as guarantees of performance.
While running content, the interpreter periodically checks the abort field of the cookie. If it is discovered to be non zero, the rest of the content is ignored.
If the caller decides that it does not need the results of a run once it has been started (perhaps the user changes the page, or closes the file), then it should therefore set the abort field of the cookie to 1.
No guarantees are made about how often the cookie is checked, nor about how fast an interpreter will respond to the abort field once it is set. Setting the abort flag will never hurt, and will frequently help, however. Once the flag has been set to 1, it should never be reset to 0, as the results will be unpredictable.
Resources used by a run cannot be released until the end of a run, regardless of the setting of abort. Callers still need to wait for the fz_run_page (or other) call to complete before the page etc can be safely dropped.