The Context

Overview

The core MuPDF library is designed for simplicity, portability, and ease of integration. For all these reasons, it has no global variables, has no thread library dependencies, and has a well defined exception system to handle runtime errors. Nonetheless, in order to be as useful as possible, clearly the library must have some state and needs to be able to take advantage of multi-threaded environments.

The solution to these seeming conflicts is the Context (fz_context).

Every caller to MuPDF should create a Context at the start of it's use of the library, and destroy it at the end. This Context (or one 'cloned' from it) will then be passed in to every MuPDF API call.

Global State

At it's simplest, the Context contains global settings for the library. For instance, the level of Antialiasing used by the rendering routines is set in the Context, as is the default style sheet for Epub/FB2 files, and the tuning functions. In addition, the library stores some private information there too.

Error handling

All error handling within MuPDF is done using the fz_try/fz_catch constructs. See [[DocsErrorHandling][the docs on error handling] for more details.

These constructs can be nested, and rely on an exception stack maintained within the context. As such it is vitally important that no 2 threads use same context at the same time. See the [[#AnchorMT][Multi-threading] section for more information.

Allocation

When embedding MuPDF into a system, it is often desirable to ensure

The Store

Multi-threading

-- Robin Watts - 2016-04-24

Comments