1 /*
2 * gdcache.h
3 *
4 * Caches of pointers to user structs in which the least-recently-used
5 * element is replaced in the event of a cache miss after the cache has
6 * reached a given size.
7 *
8 * John Ellson (ellson@graphviz.org) Oct 31, 1997
9 *
10 * Test this with:
11 * gcc -o gdcache -g -Wall -DTEST gdcache.c
12 *
13 * The cache is implemented by a singly-linked list of elements
14 * each containing a pointer to a user struct that is being managed by
15 * the cache.
16 *
17 * The head structure has a pointer to the most-recently-used
18 * element, and elements are moved to this position in the list each
19 * time they are used. The head also contains pointers to three
20 * user defined functions:
21 * - a function to test if a cached userdata matches some keydata
22 * - a function to provide a new userdata struct to the cache
23 * if there has been a cache miss.
24 * - a function to release a userdata struct when it is
25 * no longer being managed by the cache
26 *
27 * In the event of a cache miss the cache is allowed to grow up to
28 * a specified maximum size. After the maximum size is reached then
29 * the least-recently-used element is discarded to make room for the
30 * new. The most-recently-returned value is always left at the
31 * beginning of the list after retrieval.
32 *
33 * In the current implementation the cache is traversed by a linear
34 * search from most-recent to least-recent. This linear search
35 * probably limits the usefulness of this implementation to cache
36 * sizes of a few tens of elements.
37 */
38
39 /*********************************************************/
40 /* header */
41 /*********************************************************/
42
43 #include <stdlib.h>
44 #if (!defined(__OpenBSD__)) && HAVE_MALLOC_H
45 #include <malloc.h>
46 #endif
47 #ifndef NULL
48 #define NULL (void *)0
49 #endif
50
51 /* user defined function templates */
52 typedef int (*gdCacheTestFn_t)(void *userdata, void *keydata);
53 typedef void *(*gdCacheFetchFn_t)(char **error, void *keydata);
54 typedef void (*gdCacheReleaseFn_t)(void *userdata);
55
56 /* element structure */
57 typedef struct gdCache_element_s gdCache_element_t;
58 struct gdCache_element_s {
59 gdCache_element_t *next;
60 void *userdata;
61 };
62
63 /* head structure */
64 typedef struct gdCache_head_s gdCache_head_t;
65 struct gdCache_head_s {
66 gdCache_element_t *mru;
67 int size;
68 char *error;
69 gdCacheTestFn_t gdCacheTest;
70 gdCacheFetchFn_t gdCacheFetch;
71 gdCacheReleaseFn_t gdCacheRelease;
72 };
73
74 /* function templates */
75 gdCache_head_t *
76 gdCacheCreate(
77 int size,
78 gdCacheTestFn_t gdCacheTest,
79 gdCacheFetchFn_t gdCacheFetch,
80 gdCacheReleaseFn_t gdCacheRelease );
81
82 void
83 gdCacheDelete( gdCache_head_t *head );
84
85 void *
86 gdCacheGet( gdCache_head_t *head, void *keydata );