1 #ifndef MUPDF_FITZ_STORE_H 2 #define MUPDF_FITZ_STORE_H 3 4 #include "mupdf/fitz/system.h" 5 #include "mupdf/fitz/context.h" 6 #include "mupdf/fitz/output.h" 7 #include "mupdf/fitz/log.h" 8 9 /** 10 Resource store 11 12 MuPDF stores decoded "objects" into a store for potential reuse. 13 If the size of the store gets too big, objects stored within it 14 can be evicted and freed to recover space. When MuPDF comes to 15 decode such an object, it will check to see if a version of this 16 object is already in the store - if it is, it will simply reuse 17 it. If not, it will decode it and place it into the store. 18 19 All objects that can be placed into the store are derived from 20 the fz_storable type (i.e. this should be the first component of 21 the objects structure). This allows for consistent (thread safe) 22 reference counting, and includes a function that will be called 23 to free the object as soon as the reference count reaches zero. 24 25 Most objects offer fz_keep_XXXX/fz_drop_XXXX functions derived 26 from fz_keep_storable/fz_drop_storable. Creation of such objects 27 includes a call to FZ_INIT_STORABLE to set up the fz_storable 28 header. 29 */ 30 typedef struct fz_storable fz_storable; 31 32 /** 33 Function type for a function to drop a storable object. 34 35 Objects within the store are identified by type by comparing 36 their drop_fn pointers. 37 */ 38 typedef void (fz_store_drop_fn)(fz_context *, fz_storable *); 39 40 /** 41 Any storable object should include an fz_storable structure 42 at the start (by convention at least) of their structure. 43 (Unless it starts with an fz_key_storable, see below). 44 */ 45 struct fz_storable { 46 int refs; 47 fz_store_drop_fn *drop; 48 }; 49 50 /** 51 Any storable object that can appear in the key of another 52 storable object should include an fz_key_storable structure 53 at the start (by convention at least) of their structure. 54 */ 55 typedef struct 56 { 57 fz_storable storable; 58 short store_key_refs; 59 } fz_key_storable; 60 61 /** 62 Macro to initialise a storable object. 63 */ 64 #define FZ_INIT_STORABLE(S_,RC,DROP) \ 65 do { fz_storable *S = &(S_)->storable; S->refs = (RC); \ 66 S->drop = (DROP); \ 67 } while (0) 68 69 /** 70 Macro to initialise a key storable object. 71 */ 72 #define FZ_INIT_KEY_STORABLE(KS_,RC,DROP) \ 73 do { fz_key_storable *KS = &(KS_)->key_storable; KS->store_key_refs = 0;\ 74 FZ_INIT_STORABLE(KS,RC,DROP); \ 75 } while (0) 76 77 /** 78 Increment the reference count for a storable object. 79 Returns the same pointer. 80 81 Never throws exceptions. 82 */ 83 void *fz_keep_storable(fz_context *, const fz_storable *); 84 85 /** 86 Decrement the reference count for a storable object. When the 87 reference count hits zero, the drop function for that object 88 is called to free the object. 89 90 Never throws exceptions. 91 */ 92 void fz_drop_storable(fz_context *, const fz_storable *); 93 94 /** 95 Increment the (normal) reference count for a key storable 96 object. Returns the same pointer. 97 98 Never throws exceptions. 99 */ 100 void *fz_keep_key_storable(fz_context *, const fz_key_storable *); 101 102 /** 103 Decrement the (normal) reference count for a storable object. 104 When the total reference count hits zero, the drop function for 105 that object is called to free the object. 106 107 Never throws exceptions. 108 */ 109 void fz_drop_key_storable(fz_context *, const fz_key_storable *); 110 111 /** 112 Increment the (key) reference count for a key storable 113 object. Returns the same pointer. 114 115 Never throws exceptions. 116 */ 117 void *fz_keep_key_storable_key(fz_context *, const fz_key_storable *); 118 119 /** 120 Decrement the (key) reference count for a storable object. 121 When the total reference count hits zero, the drop function for 122 that object is called to free the object. 123 124 Never throws exceptions. 125 */ 126 void fz_drop_key_storable_key(fz_context *, const fz_key_storable *); 127 128 /** 129 The store can be seen as a dictionary that maps keys to 130 fz_storable values. In order to allow keys of different types to 131 be stored, we have a structure full of functions for each key 132 'type'; this fz_store_type pointer is stored with each key, and 133 tells the store how to perform certain operations (like taking/ 134 dropping a reference, comparing two keys, outputting details for 135 debugging etc). 136 137 The store uses a hash table internally for speed where possible. 138 In order for this to work, we need a mechanism for turning a 139 generic 'key' into 'a hashable string'. For this purpose the 140 type structure contains a make_hash_key function pointer that 141 maps from a void * to a fz_store_hash structure. If 142 make_hash_key function returns 0, then the key is determined not 143 to be hashable, and the value is not stored in the hash table. 144 145 Some objects can be used both as values within the store, and as 146 a component of keys within the store. We refer to these objects 147 as "key storable" objects. In this case, we need to take 148 additional care to ensure that we do not end up keeping an item 149 within the store, purely because its value is referred to by 150 another key in the store. 151 152 An example of this are fz_images in PDF files. Each fz_image is 153 placed into the store to enable it to be easily reused. When the 154 image is rendered, a pixmap is generated from the image, and the 155 pixmap is placed into the store so it can be reused on 156 subsequent renders. The image forms part of the key for the 157 pixmap. 158 159 When we close the pdf document (and any associated pages/display 160 lists etc), we drop the images from the store. This may leave us 161 in the position of the images having non-zero reference counts 162 purely because they are used as part of the keys for the 163 pixmaps. 164 165 We therefore use special reference counting functions to keep 166 track of these "key storable" items, and hence store the number 167 of references to these items that are used in keys. 168 169 When the number of references to an object == the number of 170 references to an object from keys in the store, we know that we 171 can remove all the items which have that object as part of the 172 key. This is done by running a pass over the store, 'reaping' 173 those items. 174 175 Reap passes are slower than we would like as they touch every 176 item in the store. We therefore provide a way to 'batch' such 177 reap passes together, using fz_defer_reap_start/ 178 fz_defer_reap_end to bracket a region in which many may be 179 triggered. 180 */ 181 typedef struct 182 { 183 fz_store_drop_fn *drop; 184 union 185 { 186 struct 187 { 188 const void *ptr; 189 int i; 190 } pi; /* 8 or 12 bytes */ 191 struct 192 { 193 const void *ptr; 194 int i; 195 fz_irect r; 196 } pir; /* 24 or 28 bytes */ 197 struct 198 { 199 int id; 200 char has_shape; 201 char has_group_alpha; 202 float m[4]; 203 void *ptr; 204 } im; /* 24 or 28 bytes */ 205 struct 206 { 207 unsigned char src_md5[16]; 208 unsigned char dst_md5[16]; 209 unsigned int ri:2; 210 unsigned int bp:1; 211 unsigned int format:1; 212 unsigned int proof:1; 213 unsigned int src_extras:5; 214 unsigned int dst_extras:5; 215 unsigned int copy_spots:1; 216 unsigned int bgr:1; 217 } link; /* 36 bytes */ 218 } u; 219 } fz_store_hash; /* 40 or 44 bytes */ 220 221 /** 222 Every type of object to be placed into the store defines an 223 fz_store_type. This contains the pointers to functions to 224 make hashes, manipulate keys, and check for needing reaping. 225 */ 226 typedef struct 227 { 228 const char *name; 229 int (*make_hash_key)(fz_context *ctx, fz_store_hash *hash, void *key); 230 void *(*keep_key)(fz_context *ctx, void *key); 231 void (*drop_key)(fz_context *ctx, void *key); 232 int (*cmp_key)(fz_context *ctx, void *a, void *b); 233 void (*format_key)(fz_context *ctx, char *buf, size_t size, void *key); 234 int (*needs_reap)(fz_context *ctx, void *key); 235 } fz_store_type; 236 237 /** 238 Create a new store inside the context 239 240 max: The maximum size (in bytes) that the store is allowed to 241 grow to. FZ_STORE_UNLIMITED means no limit. 242 */ 243 void fz_new_store_context(fz_context *ctx, size_t max); 244 245 /** 246 Increment the reference count for the store context. Returns 247 the same pointer. 248 249 Never throws exceptions. 250 */ 251 fz_store *fz_keep_store_context(fz_context *ctx); 252 253 /** 254 Decrement the reference count for the store context. When the 255 reference count hits zero, the store context is freed. 256 257 Never throws exceptions. 258 */ 259 void fz_drop_store_context(fz_context *ctx); 260 261 /** 262 Add an item to the store. 263 264 Add an item into the store, returning NULL for success. If an 265 item with the same key is found in the store, then our item will 266 not be inserted, and the function will return a pointer to that 267 value instead. This function takes its own reference to val, as 268 required (i.e. the caller maintains ownership of its own 269 reference). 270 271 key: The key used to index the item. 272 273 val: The value to store. 274 275 itemsize: The size in bytes of the value (as counted towards the 276 store size). 277 278 type: Functions used to manipulate the key. 279 */ 280 void *fz_store_item(fz_context *ctx, void *key, void *val, size_t itemsize, const fz_store_type *type); 281 282 /** 283 Find an item within the store. 284 285 drop: The function used to free the value (to ensure we get a 286 value of the correct type). 287 288 key: The key used to index the item. 289 290 type: Functions used to manipulate the key. 291 292 Returns NULL for not found, otherwise returns a pointer to the 293 value indexed by key to which a reference has been taken. 294 */ 295 void *fz_find_item(fz_context *ctx, fz_store_drop_fn *drop, void *key, const fz_store_type *type); 296 297 /** 298 Remove an item from the store. 299 300 If an item indexed by the given key exists in the store, remove 301 it. 302 303 drop: The function used to free the value (to ensure we get a 304 value of the correct type). 305 306 key: The key used to find the item to remove. 307 308 type: Functions used to manipulate the key. 309 */ 310 void fz_remove_item(fz_context *ctx, fz_store_drop_fn *drop, void *key, const fz_store_type *type); 311 312 /** 313 Evict every item from the store. 314 */ 315 void fz_empty_store(fz_context *ctx); 316 317 /** 318 Internal function used as part of the scavenging 319 allocator; when we fail to allocate memory, before returning a 320 failure to the caller, we try to scavenge space within the store 321 by evicting at least 'size' bytes. The allocator then retries. 322 323 size: The number of bytes we are trying to have free. 324 325 phase: What phase of the scavenge we are in. Updated on exit. 326 327 Returns non zero if we managed to free any memory. 328 */ 329 int fz_store_scavenge(fz_context *ctx, size_t size, int *phase); 330 331 /** 332 External function for callers to use 333 to scavenge while trying allocations. 334 335 size: The number of bytes we are trying to have free. 336 337 phase: What phase of the scavenge we are in. Updated on exit. 338 339 Returns non zero if we managed to free any memory. 340 */ 341 int fz_store_scavenge_external(fz_context *ctx, size_t size, int *phase); 342 343 /** 344 Evict items from the store until the total size of 345 the objects in the store is reduced to a given percentage of its 346 current size. 347 348 percent: %age of current size to reduce the store to. 349 350 Returns non zero if we managed to free enough memory, zero 351 otherwise. 352 */ 353 int fz_shrink_store(fz_context *ctx, unsigned int percent); 354 355 /** 356 Callback function called by fz_filter_store on every item within 357 the store. 358 359 Return 1 to drop the item from the store, 0 to retain. 360 */ 361 typedef int (fz_store_filter_fn)(fz_context *ctx, void *arg, void *key); 362 363 /** 364 Filter every element in the store with a matching type with the 365 given function. 366 367 If the function returns 1 for an element, drop the element. 368 */ 369 void fz_filter_store(fz_context *ctx, fz_store_filter_fn *fn, void *arg, const fz_store_type *type); 370 371 /** 372 Output debugging information for the current state of the store 373 to the given output channel. 374 */ 375 void fz_debug_store(fz_context *ctx, fz_output *out); 376 377 /** 378 Increment the defer reap count. 379 380 No reap operations will take place (except for those 381 triggered by an immediate failed malloc) until the 382 defer reap count returns to 0. 383 384 Call this at the start of a process during which you 385 potentially might drop many reapable objects. 386 387 It is vital that every fz_defer_reap_start is matched 388 by a fz_defer_reap_end call. 389 */ 390 void fz_defer_reap_start(fz_context *ctx); 391 392 /** 393 Decrement the defer reap count. 394 395 If the defer reap count returns to 0, and the store 396 has reapable objects in, a reap pass will begin. 397 398 Call this at the end of a process during which you 399 potentially might drop many reapable objects. 400 401 It is vital that every fz_defer_reap_start is matched 402 by a fz_defer_reap_end call. 403 */ 404 void fz_defer_reap_end(fz_context *ctx); 405 406 #ifdef ENABLE_STORE_LOGGING 407 408 void fz_log_dump_store(fz_context *ctx, const char *fmt, ...); 409 410 #define FZ_LOG_STORE(CTX, ...) fz_log_module(CTX, "STORE", __VA_ARGS__) 411 #define FZ_LOG_DUMP_STORE(...) fz_log_dump_store(__VA_ARGS__) 412 413 #else 414 415 #define FZ_LOG_STORE(...) do {} while (0) 416 #define FZ_LOG_DUMP_STORE(...) do {} while (0) 417 418 #endif 419 420 #endif 421