Cloning

The context contains the exception stack for the fz_tryfz_catch constructs. As such trying to use the same context from multiple threads at the same time will lead to crashes.

The solution to this is to `clone' the context. Each clone will share the same underlying store (and will inherit the same settings, such as allocators, locks etc), but will have its own exception stack. Other settings, such as anti-alias levels, will be inherited from the original at the time of cloning, but can be changed to be different if required.

For example, in a viewer application, we might want to have a background process that runs through the file generating page thumbnails. In order for this not to interfere with the foreground process, we would clone the context, and use the cloned context in the thumbnailing thread. We might choose to disable anti-aliasing for the thumbnailing thread to trade quality for speed.

Any images decoded for the thumbnailing thread would live on in the store though, and would hence be available should the viewers normal render operations need them.

To clone a context, use fz_clone_context:

$\begin{lstlisting} /* fz_clone_context: Make a clone of an existing context. \p... ... return NULL. */ fz_context *fz_clone_context(fz_context *ctx); \end{lstlisting}$

For example:

$\begin{lstlisting} fz_context *worker_ctx = fz_clone_context(ctx); \end{lstlisting}$

In order for cloned contexts to work safely, they rely on being able to take locks around certain operations to make them atomic. Accordingly, fz_clone_context will return NULL (to indicate failure) if the base context did not have locking functions defined.