src/cairo-cache-private.h

   1 /* cairo - a vector graphics library with display and print output
   2  *
   3  * Copyright © 2004 Red Hat, Inc.
   4  * Copyright © 2005 Red Hat, Inc.
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it either under the terms of the GNU Lesser General Public
   8  * License version 2.1 as published by the Free Software Foundation
   9  * (the "LGPL") or, at your option, under the terms of the Mozilla
  10  * Public License Version 1.1 (the "MPL"). If you do not alter this
  11  * notice, a recipient may use your version of this file under either
  12  * the MPL or the LGPL.
  13  *
  14  * You should have received a copy of the LGPL along with this library
  15  * in the file COPYING-LGPL-2.1; if not, write to the Free Software
  16  * Foundation, Inc., 51 Franklin Street, Suite 500, Boston, MA 02110-1335, USA
  17  * You should have received a copy of the MPL along with this library
  18  * in the file COPYING-MPL-1.1
  19  *
  20  * The contents of this file are subject to the Mozilla Public License
  21  * Version 1.1 (the "License"); you may not use this file except in
  22  * compliance with the License. You may obtain a copy of the License at
  23  * http://www.mozilla.org/MPL/
  24  *
  25  * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY
  26  * OF ANY KIND, either express or implied. See the LGPL or the MPL for
  27  * the specific language governing rights and limitations.
  28  *
  29  * The Original Code is the cairo graphics library.
  30  *
  31  * The Initial Developer of the Original Code is Red Hat, Inc.
  32  *
  33  * Contributor(s):
  34  *      Keith Packard <keithp@keithp.com>
  35  *      Graydon Hoare <graydon@redhat.com>
  36  *      Carl Worth <cworth@cworth.org>
  37  */
  38
  39 #ifndef CAIRO_CACHE_PRIVATE_H
  40 #define CAIRO_CACHE_PRIVATE_H
  41
  42 #include "cairo-compiler-private.h"
  43 #include "cairo-types-private.h"
  44
  45 /**
  46  * cairo_cache_entry_t:
  47  *
  48  * A #cairo_cache_entry_t contains both a key and a value for
  49  * #cairo_cache_t. User-derived types for #cairo_cache_entry_t must
  50  * have a #cairo_cache_entry_t as their first field. For example:
  51  *
  52  *      typedef _my_entry {
  53  *          cairo_cache_entry_t base;
  54  *          ... Remainder of key and value fields here ..
  55  *      } my_entry_t;
  56  *
  57  * which then allows a pointer to my_entry_t to be passed to any of
  58  * the #cairo_cache_t functions as follows without requiring a cast:
  59  *
  60  *      _cairo_cache_insert (cache, &my_entry->base, size);
  61  *
  62  * IMPORTANT: The caller is responsible for initializing
  63  * my_entry->base.hash with a hash code derived from the key.  The
  64  * essential property of the hash code is that keys_equal must never
  65  * return %TRUE for two keys that have different hashes. The best hash
  66  * code will reduce the frequency of two keys with the same code for
  67  * which keys_equal returns %FALSE.
  68  *
  69  * The user must also initialize my_entry->base.size to indicate
  70  * the size of the current entry. What units to use for size is
  71  * entirely up to the caller, (though the same units must be used for
  72  * the max_size parameter passed to _cairo_cache_create()). If all
  73  * entries are close to the same size, the simplest thing to do is to
  74  * just use units of "entries", (eg. set size==1 in all entries and
  75  * set max_size to the number of entries which you want to be saved
  76  * in the cache).
  77  *
  78  * Which parts of the entry make up the "key" and which part make up
  79  * the value are entirely up to the caller, (as determined by the
  80  * computation going into base.hash as well as the keys_equal
  81  * function). A few of the #cairo_cache_t functions accept an entry which
  82  * will be used exclusively as a "key", (indicated by a parameter name
  83  * of key). In these cases, the value-related fields of the entry need
  84  * not be initialized if so desired.
  85  **/
  86 typedef struct _cairo_cache_entry {
  87     unsigned long hash;
  88     unsigned long size;
  89 } cairo_cache_entry_t;
  90
  91 typedef cairo_bool_t (*cairo_cache_predicate_func_t) (const void *entry);
  92
  93 struct _cairo_cache {
  94     cairo_hash_table_t *hash_table;
  95
  96     cairo_cache_predicate_func_t predicate;
  97     cairo_destroy_func_t entry_destroy;
  98
  99     unsigned long max_size;
 100     unsigned long size;
 101
 102     int freeze_count;
 103 };
 104
 105 typedef cairo_bool_t
 106 (*cairo_cache_keys_equal_func_t) (const void *key_a, const void *key_b);
 107
 108 typedef void
 109 (*cairo_cache_callback_func_t) (void *entry,
 110                                 void *closure);
 111
 112 cairo_private cairo_status_t
 113 _cairo_cache_init (cairo_cache_t *cache,
 114                    cairo_cache_keys_equal_func_t keys_equal,
 115                    cairo_cache_predicate_func_t  predicate,
 116                    cairo_destroy_func_t    entry_destroy,
 117                    unsigned long                   max_size);
 118
 119 cairo_private void
 120 _cairo_cache_fini (cairo_cache_t *cache);
 121
 122 cairo_private void
 123 _cairo_cache_freeze (cairo_cache_t *cache);
 124
 125 cairo_private void
 126 _cairo_cache_thaw (cairo_cache_t *cache);
 127
 128 cairo_private void *
 129 _cairo_cache_lookup (cairo_cache_t        *cache,
 130                      cairo_cache_entry_t  *key);
 131
 132 cairo_private cairo_status_t
 133 _cairo_cache_insert (cairo_cache_t       *cache,
 134                      cairo_cache_entry_t *entry);
 135
 136 cairo_private void
 137 _cairo_cache_remove (cairo_cache_t       *cache,
 138                      cairo_cache_entry_t *entry);
 139
 140 cairo_private void
 141 _cairo_cache_foreach (cairo_cache_t              *cache,
 142                       cairo_cache_callback_func_t cache_callback,
 143                       void                       *closure);
 144
 145 #endif