← Back to branch summary

~ubuntu-branches/ubuntu/karmic/moon/karmic

« back to all changes in this revision

Viewing changes to cairo/src/cairo-cache-private.h

  • Committer: Bazaar Package Importer
  • Author(s): Jo Shields
  • Date: 2009-02-14 12:01:08 UTC
  • Revision ID: james.westby@ubuntu.com-20090214120108-06539vb25vhbd8bn
Tags: upstream-1.0
Import upstream version 1.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
cairo/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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 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
 
92
(*cairo_cache_keys_equal_func_t) (const void *key_a, const void *key_b);
 
93
 
 
94
typedef void
 
95
(*cairo_cache_callback_func_t) (void *entry,
 
96
                                void *closure);
 
97
 
 
98
cairo_private cairo_cache_t *
 
99
_cairo_cache_create (cairo_cache_keys_equal_func_t keys_equal,
 
100
                     cairo_destroy_func_t          entry_destroy,
 
101
                     unsigned long                 max_size);
 
102
 
 
103
cairo_private void
 
104
_cairo_cache_destroy (cairo_cache_t *cache);
 
105
 
 
106
cairo_private void
 
107
_cairo_cache_freeze (cairo_cache_t *cache);
 
108
 
 
109
cairo_private void
 
110
_cairo_cache_thaw (cairo_cache_t *cache);
 
111
 
 
112
cairo_private cairo_bool_t
 
113
_cairo_cache_lookup (cairo_cache_t        *cache,
 
114
                     cairo_cache_entry_t  *key,
 
115
                     cairo_cache_entry_t **entry_return);
 
116
 
 
117
cairo_private cairo_status_t
 
118
_cairo_cache_insert (cairo_cache_t       *cache,
 
119
                     cairo_cache_entry_t *entry);
 
120
 
 
121
cairo_private void
 
122
_cairo_cache_foreach (cairo_cache_t              *cache,
 
123
                      cairo_cache_callback_func_t cache_callback,
 
124
                      void                       *closure);
 
125
 
 
126
#endif