xref: /PHP-7.4/ext/gd/libgd/gdcache.h (revision c12e0315)
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 );
87