PDF-Context.h

#ifndef MUPDF_FITZ_CONTEXT_H
#define MUPDF_FITZ_CONTEXT_H

#include “mupdf/fitz/version.h”
#include “mupdf/fitz/system.h”
#include “mupdf/fitz/geometry.h”

typedef struct fz_font_context fz_font_context;
typedef struct fz_colorspace_context fz_colorspace_context;
typedef struct fz_style_context fz_style_context;
typedef struct fz_tuning_context fz_tuning_context;
typedef struct fz_store fz_store;
typedef struct fz_glyph_cache fz_glyph_cache;
typedef struct fz_document_handler_context fz_document_handler_context;
typedef struct fz_output fz_output;
typedef struct fz_context fz_context;

/**
Allocator structure; holds callbacks and private data pointer.
分配器结构； 持有回调和私有数据指针。
*/
typedef struct
{
void *user;
void *(*malloc)(void *, size_t);
void *(*realloc)(void *, void *, size_t);
void (*free)(void *, void *);
} fz_alloc_context;

/**
Exception macro definitions. Just treat these as a black box -
pay no attention to the man behind the curtain.
异常宏定义。
把这些当成一个黑匣子——不要理会窗帘后面的男人。
*/

#define fz_var(var) fz_var_imp((void *)&(var))
#define fz_try(ctx) if (!fz_setjmp(*fz_push_try(ctx))) if (fz_do_try(ctx)) do
#define fz_always(ctx) while (0); if (fz_do_always(ctx)) do
#define fz_catch(ctx) while (0); if (fz_do_catch(ctx))

FZ_NORETURN void fz_vthrow(fz_context *ctx, int errcode, const char *, va_list ap);
FZ_NORETURN void fz_throw(fz_context *ctx, int errcode, const char *, …) FZ_PRINTFLIKE(3,4);
FZ_NORETURN void fz_rethrow(fz_context *ctx);
void fz_vwarn(fz_context *ctx, const char *fmt, va_list ap);
void fz_warn(fz_context *ctx, const char *fmt, …) FZ_PRINTFLIKE(2,3);
const char *fz_caught_message(fz_context *ctx);
int fz_caught(fz_context *ctx);
void fz_rethrow_if(fz_context *ctx, int errcode);

enum
{
FZ_ERROR_NONE = 0,
FZ_ERROR_MEMORY = 1,
FZ_ERROR_GENERIC = 2,
FZ_ERROR_SYNTAX = 3,
FZ_ERROR_MINOR = 4,
FZ_ERROR_TRYLATER = 5,
FZ_ERROR_ABORT = 6,
FZ_ERROR_COUNT
};

/**
Flush any repeated warnings.

Repeated warnings are buffered, counted and eventually printed
along with the number of repetitions. Call fz_flush_warnings
to force printing of the latest buffered warning and the
number of repetitions, for example to make sure that all
warnings are printed before exiting an application.

刷新所有重复警告。

重复警告被缓冲、计数并最终打印
以及重复次数。 调用
fz_flush_warnings
强制打印最新的缓冲警告和
重复次数，例如确保所有
在退出应用程序之前打印警告。
*/
void fz_flush_warnings(fz_context *ctx);

/**
Locking functions

MuPDF is kept deliberately free of any knowledge of particular
threading systems. As such, in order for safe multi-threaded
operation, we rely on callbacks to client provided functions.

A client is expected to provide FZ_LOCK_MAX number of mutexes,
and a function to lock/unlock each of them. These may be
recursive mutexes, but do not have to be.

If a client does not intend to use multiple threads, then it
may pass NULL instead of a lock structure.

In order to avoid deadlocks, we have one simple rule
internally as to how we use locks: We can never take lock n
when we already hold any lock i, where 0 <= i <= n. In order
to verify this, we have some debugging code, that can be
enabled by defining FITZ_DEBUG_LOCKING.
锁定功能

MuPDF
故意不了解任何特定的知识
线程系统。
因此，为了安全的多线程
操作，我们依赖于对客户端提供的函数的回调。

客户端应提供
FZ_LOCK_MAX 个互斥锁，
以及锁定/解锁它们中的每一个的功能。
这些可能是
递归互斥锁，但不是必须的。

如果客户端不打算使用多线程，那么它
可以传递
NULL
而不是锁结构。

为了避免死锁，我们有一个简单的规则
关于我们如何使用锁的内部：我们永远不能获取锁
n
当我们已经持有任何锁 i 时，其中 0 <= i <= n。
为了
为了验证这一点，我们有一些调试代码，可以
通过定义 FITZ_DEBUG_LOCKING 启用。

*/

typedef struct
{
void *user;
void (*lock)(void *user, int lock);
void (*unlock)(void *user, int lock);
} fz_locks_context;

enum {
FZ_LOCK_ALLOC = 0,
FZ_LOCK_FREETYPE,
FZ_LOCK_GLYPHCACHE,
FZ_LOCK_MAX
};

#if defined(MEMENTO) || !defined(NDEBUG)
#define FITZ_DEBUG_LOCKING
#endif

#ifdef FITZ_DEBUG_LOCKING

void fz_assert_lock_held(fz_context *ctx, int lock);
void fz_assert_lock_not_held(fz_context *ctx, int lock);
void fz_lock_debug_lock(fz_context *ctx, int lock);
void fz_lock_debug_unlock(fz_context *ctx, int lock);

#else

#define fz_assert_lock_held(A,B) do { } while (0)
#define fz_assert_lock_not_held(A,B) do { } while (0)
#define fz_lock_debug_lock(A,B) do { } while (0)
#define fz_lock_debug_unlock(A,B) do { } while (0)

#endif /* !FITZ_DEBUG_LOCKING */

/**
Specifies the maximum size in bytes of the resource store in
fz_context. Given as argument to fz_new_context.

FZ_STORE_UNLIMITED: Let resource store grow unbounded.

FZ_STORE_DEFAULT: A reasonable upper bound on the size, for
devices that are n