store.h File Reference

#include "mupdf/fitz/system.h"
#include "mupdf/fitz/context.h"
#include "mupdf/fitz/output.h"
#include "mupdf/fitz/log.h"
#include "mupdf/fitz/types.h"

Include dependency graph for store.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	fz_storable
struct	fz_key_storable
struct	fz_store_hash
struct	fz_store_type

Macros
#define	FZ_INIT_STORABLE(S_, RC, DROP)
#define	FZ_INIT_AWKWARD_STORABLE(S_, RC, DROP, DROPPABLE)
#define	FZ_INIT_KEY_STORABLE(KS_, RC, DROP)
#define	FZ_LOG_STORE(...)
#define	FZ_LOG_DUMP_STORE(...)

Typedefs
typedef struct fz_storable	fz_storable
typedef void	fz_store_drop_fn(fz_context *, fz_storable *)
typedef int	fz_store_droppable_fn(fz_context *, fz_storable *)
typedef int	fz_store_filter_fn(fz_context *ctx, void *arg, void *key)

Functions
void *	fz_keep_storable (fz_context *, const fz_storable *)
void	fz_drop_storable (fz_context *, const fz_storable *)
void *	fz_keep_key_storable (fz_context *, const fz_key_storable *)
void	fz_drop_key_storable (fz_context *, const fz_key_storable *)
void *	fz_keep_key_storable_key (fz_context *, const fz_key_storable *)
void	fz_drop_key_storable_key (fz_context *, const fz_key_storable *)
void	fz_new_store_context (fz_context *ctx, size_t max)
fz_store *	fz_keep_store_context (fz_context *ctx)
void	fz_drop_store_context (fz_context *ctx)
void *	fz_store_item (fz_context *ctx, void *key, void *val, size_t itemsize, const fz_store_type *type)
void *	fz_find_item (fz_context *ctx, fz_store_drop_fn *drop, void *key, const fz_store_type *type)
void	fz_remove_item (fz_context *ctx, fz_store_drop_fn *drop, void *key, const fz_store_type *type)
void	fz_empty_store (fz_context *ctx)
int	fz_store_scavenge (fz_context *ctx, size_t size, int *phase)
int	fz_store_scavenge_external (fz_context *ctx, size_t size, int *phase)
int	fz_shrink_store (fz_context *ctx, unsigned int percent)
void	fz_filter_store (fz_context *ctx, fz_store_filter_fn *fn, void *arg, const fz_store_type *type)
void	fz_drop_drawn_tiles_for_document (fz_context *ctx, fz_document *doc)
void	fz_debug_store (fz_context *ctx, fz_output *out)
void	fz_defer_reap_start (fz_context *ctx)
void	fz_defer_reap_end (fz_context *ctx)

Macro Definition Documentation

FZ_INIT_AWKWARD_STORABLE

#define FZ_INIT_AWKWARD_STORABLE	(		S_,
			RC,
			DROP,
			DROPPABLE )

Value:

    do { fz_storable *S = &(S_)->storable; S->refs = (RC); \
    S->drop = (DROP); S->droppable = (DROPPABLE); \
    } while (0)

FZ_INIT_KEY_STORABLE

#define FZ_INIT_KEY_STORABLE	(		KS_,
			RC,
			DROP )

Value:

    do { fz_key_storable *KS = &(KS_)->key_storable; KS->store_key_refs = 0;\
    FZ_INIT_STORABLE(KS,RC,DROP); \
    } while (0)

Macro to initialise a key storable object.

FZ_INIT_STORABLE

#define FZ_INIT_STORABLE	(		S_,
			RC,
			DROP )

Value:

    do { fz_storable *S = &(S_)->storable; S->refs = (RC); \
    S->drop = (DROP); S->droppable = NULL; \
    } while (0)

Macros to initialise a storable object.

FZ_LOG_DUMP_STORE

#define FZ_LOG_DUMP_STORE

(

...

)

Value:

do {} while (0)

FZ_LOG_STORE

#define FZ_LOG_STORE

(

...

)

Value:

do {} while (0)

Typedef Documentation

fz_storable

typedef struct fz_storable fz_storable

Resource store

MuPDF stores decoded "objects" into a store for potential reuse. If the size of the store gets too big, objects stored within it can be evicted and freed to recover space. When MuPDF comes to decode such an object, it will check to see if a version of this object is already in the store - if it is, it will simply reuse it. If not, it will decode it and place it into the store.

All objects that can be placed into the store are derived from the fz_storable type (i.e. this should be the first component of the objects structure). This allows for consistent (thread safe) reference counting, and includes a function that will be called to free the object as soon as the reference count reaches zero.

Most objects offer fz_keep_XXXX/fz_drop_XXXX functions derived from fz_keep_storable/fz_drop_storable. Creation of such objects includes a call to FZ_INIT_STORABLE to set up the fz_storable header.

fz_store_drop_fn

typedef void fz_store_drop_fn(fz_context *, fz_storable *)

Function type for a function to drop a storable object.

Objects within the store are identified by type by comparing their drop_fn pointers.

fz_store_droppable_fn

typedef int fz_store_droppable_fn(fz_context *, fz_storable *)

Function type for a function to check whether a storable object can be dropped at the moment.

Return 0 for 'cannot be dropped', 1 otherwise.

fz_store_filter_fn

typedef int fz_store_filter_fn(fz_context *ctx, void *arg, void *key)

Callback function called by fz_filter_store on every item within the store.

Return 1 to drop the item from the store, 0 to retain.

Function Documentation

fz_debug_store()

void fz_debug_store	(	fz_context *	ctx,
		fz_output *	out )

Output debugging information for the current state of the store to the given output channel.

fz_defer_reap_end()

void fz_defer_reap_end

(

fz_context *

ctx

)

Decrement the defer reap count.

If the defer reap count returns to 0, and the store has reapable objects in, a reap pass will begin.

Call this at the end of a process during which you potentially might drop many reapable objects.

It is vital that every fz_defer_reap_start is matched by a fz_defer_reap_end call.

fz_defer_reap_start()

void fz_defer_reap_start

(

fz_context *

ctx

)

Increment the defer reap count.

No reap operations will take place (except for those triggered by an immediate failed malloc) until the defer reap count returns to 0.

Call this at the start of a process during which you potentially might drop many reapable objects.

It is vital that every fz_defer_reap_start is matched by a fz_defer_reap_end call.

fz_drop_drawn_tiles_for_document()

void fz_drop_drawn_tiles_for_document	(	fz_context *	ctx,
		fz_document *	doc )

Filter the store and throw away any stored tiles drawn for a given document.

fz_drop_key_storable()

void fz_drop_key_storable	(	fz_context *	,
		const fz_key_storable *	)

Decrement the (normal) reference count for a storable object. When the total reference count hits zero, the drop function for that object is called to free the object.

Never throws exceptions.

fz_drop_key_storable_key()

void fz_drop_key_storable_key	(	fz_context *	,
		const fz_key_storable *	)

Decrement the (key) reference count for a storable object. When the total reference count hits zero, the drop function for that object is called to free the object.

Never throws exceptions.

fz_drop_storable()

void fz_drop_storable	(	fz_context *	,
		const fz_storable *	)

Decrement the reference count for a storable object. When the reference count hits zero, the drop function for that object is called to free the object.

Never throws exceptions.

fz_drop_store_context()

void fz_drop_store_context

(

fz_context *

ctx

)

Decrement the reference count for the store context. When the reference count hits zero, the store context is freed.

Never throws exceptions.

fz_empty_store()

void fz_empty_store

(

fz_context *

ctx

)

Evict every item from the store.

fz_filter_store()

void fz_filter_store	(	fz_context *	ctx,
		fz_store_filter_fn *	fn,
		void *	arg,
		const fz_store_type *	type )

Filter every element in the store with a matching type with the given function.

If the function returns 1 for an element, drop the element.

fz_find_item()

void * fz_find_item	(	fz_context *	ctx,
		fz_store_drop_fn *	drop,
		void *	key,
		const fz_store_type *	type )

Find an item within the store.

drop: The function used to free the value (to ensure we get a value of the correct type).

key: The key used to index the item.

type: Functions used to manipulate the key.

Returns NULL for not found, otherwise returns a pointer to the value indexed by key to which a reference has been taken.

fz_keep_key_storable()

void * fz_keep_key_storable	(	fz_context *	,
		const fz_key_storable *	)

Increment the (normal) reference count for a key storable object. Returns the same pointer.

Never throws exceptions.

fz_keep_key_storable_key()

void * fz_keep_key_storable_key	(	fz_context *	,
		const fz_key_storable *	)

Increment the (key) reference count for a key storable object. Returns the same pointer.

Never throws exceptions.

fz_keep_storable()

void * fz_keep_storable	(	fz_context *	,
		const fz_storable *	)

Increment the reference count for a storable object. Returns the same pointer.

Never throws exceptions.

fz_keep_store_context()

fz_store * fz_keep_store_context

(

fz_context *

ctx

)

Increment the reference count for the store context. Returns the same pointer.

Never throws exceptions.

fz_new_store_context()

void fz_new_store_context	(	fz_context *	ctx,
		size_t	max )

Create a new store inside the context

max: The maximum size (in bytes) that the store is allowed to grow to. FZ_STORE_UNLIMITED means no limit.

fz_remove_item()

void fz_remove_item	(	fz_context *	ctx,
		fz_store_drop_fn *	drop,
		void *	key,
		const fz_store_type *	type )

Remove an item from the store.

If an item indexed by the given key exists in the store, remove it.

drop: The function used to free the value (to ensure we get a value of the correct type).

key: The key used to find the item to remove.

type: Functions used to manipulate the key.

fz_shrink_store()

int fz_shrink_store	(	fz_context *	ctx,
		unsigned int	percent )

Evict items from the store until the total size of the objects in the store is reduced to a given percentage of its current size.

percent: age of current size to reduce the store to.

Returns non zero if we managed to free enough memory, zero otherwise.

fz_store_item()

void * fz_store_item	(	fz_context *	ctx,
		void *	key,
		void *	val,
		size_t	itemsize,
		const fz_store_type *	type )

Add an item to the store.

Add an item into the store, returning NULL for success. If an item with the same key is found in the store, then our item will not be inserted, and the function will return a pointer to that value instead. This function takes its own reference to val, as required (i.e. the caller maintains ownership of its own reference).

key: The key used to index the item.

val: The value to store.

itemsize: The size in bytes of the value (as counted towards the store size).

type: Functions used to manipulate the key.

fz_store_scavenge()

int fz_store_scavenge	(	fz_context *	ctx,
		size_t	size,
		int *	phase )

Internal function used as part of the scavenging allocator; when we fail to allocate memory, before returning a failure to the caller, we try to scavenge space within the store by evicting at least 'size' bytes. The allocator then retries.

size: The number of bytes we are trying to have free.

phase: What phase of the scavenge we are in. Updated on exit.

Returns non zero if we managed to free any memory.

fz_store_scavenge_external()

int fz_store_scavenge_external	(	fz_context *	ctx,
		size_t	size,
		int *	phase )

External function for callers to use to scavenge while trying allocations.

size: The number of bytes we are trying to have free.

phase: What phase of the scavenge we are in. Updated on exit.

Returns non zero if we managed to free any memory.