2 +----------------------------------------------------------------------+
4 +----------------------------------------------------------------------+
5 | Copyright (c) 2008 The PHP Group |
6 +----------------------------------------------------------------------+
7 | This source file is subject to version 3.01 of the PHP license, |
8 | that is bundled with this package in the file LICENSE, and is |
9 | available through the world-wide-web at the following url: |
10 | http://www.php.net/license/3_01.txt. |
11 | If you did not receive a copy of the PHP license and are unable to |
12 | obtain it through the world-wide-web, please send a note to |
13 | license@php.net so we can mail you a copy immediately. |
14 +----------------------------------------------------------------------+
15 | Authors: Daniel Cowgill <dcowgill@communityconnect.com> |
16 | Rasmus Lerdorf <rasmus@php.net> |
17 +----------------------------------------------------------------------+
19 This software was contributed to PHP by Community Connect Inc. in 2002
20 and revised in 2005 by Yahoo! Inc. to add support for PHP 5.1.
21 Future revisions and derivatives of this source code must acknowledge
22 Community Connect Inc. as the original contributor of this module by
23 leaving this note intact in the source code.
25 All other licensing and usage conditions are those of the PHP Group.
29 /* $Id: apc_cache.h,v 3.46.2.4 2008/05/11 18:57:00 rasmus Exp $ */
35 * This module defines the shared memory file cache. Basically all of the
36 * logic for storing and retrieving cache entries lives here.
40 #include "apc_compile.h"
43 #define APC_CACHE_ENTRY_FILE 1
44 #define APC_CACHE_ENTRY_USER 2
46 #define APC_CACHE_KEY_FILE 1
47 #define APC_CACHE_KEY_USER 2
48 #define APC_CACHE_KEY_FPFILE 3
50 /* {{{ struct definition: apc_cache_key_t */
51 #define T apc_cache_t*
52 typedef struct apc_cache_t apc_cache_t; /* opaque cache type */
54 typedef union _apc_cache_key_data_t {
56 dev_t device; /* the filesystem device */
57 ino_t inode; /* the filesystem inode */
60 const char *identifier;
67 } apc_cache_key_data_t;
69 typedef struct apc_cache_key_t apc_cache_key_t;
70 struct apc_cache_key_t {
71 apc_cache_key_data_t data;
72 time_t mtime; /* the mtime of this cached entry */
77 /* {{{ struct definition: apc_cache_entry_t */
78 typedef union _apc_cache_entry_value_t {
80 char *filename; /* absolute path to source file */
81 zend_op_array* op_array; /* op_array allocated in shared memory */
82 apc_function_t* functions; /* array of apc_function_t's */
83 apc_class_t* classes; /* array of apc_class_t's */
91 } apc_cache_entry_value_t;
93 typedef struct apc_cache_entry_t apc_cache_entry_t;
94 struct apc_cache_entry_t {
95 apc_cache_entry_value_t data;
103 * apc_cache_create creates the shared memory compiler cache. This function
104 * should be called just once (ideally in the web server parent process, e.g.
105 * in apache), otherwise you will end up with multiple caches (which won't
106 * necessarily break anything). Returns a pointer to the cache object.
108 * size_hint is a "hint" at the total number of source files that will be
109 * cached. It determines the physical size of the hash table. Passing 0 for
110 * this argument will use a reasonable default value.
112 * gc_ttl is the maximum time a cache entry may speed on the garbage
113 * collection list. This is basically a work around for the inherent
114 * unreliability of our reference counting mechanism (see apc_cache_release).
116 * ttl is the maximum time a cache entry can idle in a slot in case the slot
117 * is needed. This helps in cleaning up the cache and ensuring that entries
118 * hit frequently stay cached and ones not hit very often eventually disappear.
120 extern T apc_cache_create(int size_hint, int gc_ttl, int ttl);
123 * apc_cache_destroy releases any OS resources associated with a cache object.
124 * Under apache, this function can be safely called by the child processes
127 extern void apc_cache_destroy(T cache);
130 * apc_cache_clear empties a cache. This can safely be called at any time,
131 * even while other server processes are executing cached source files.
133 extern void apc_cache_clear(T cache);
136 * apc_cache_insert adds an entry to the cache, using a filename as a key.
137 * Internally, the filename is translated to a canonical representation, so
138 * that relative and absolute filenames will map to a single key. Returns
139 * non-zero if the file was successfully inserted, 0 otherwise. If 0 is
140 * returned, the caller must free the cache entry by calling
141 * apc_cache_free_entry (see below).
143 * key is the value created by apc_cache_make_file_key for file keys.
145 * value is a cache entry returned by apc_cache_make_entry (see below).
147 extern int apc_cache_insert(T cache, apc_cache_key_t key,
148 apc_cache_entry_t* value, time_t t);
150 extern int apc_cache_user_insert(T cache, apc_cache_key_t key,
151 apc_cache_entry_t* value, time_t t, int exclusive TSRMLS_DC);
154 * apc_cache_find searches for a cache entry by filename, and returns a
155 * pointer to the entry if found, NULL otherwise.
157 * key is a value created by apc_cache_make_file_key for file keys.
159 extern apc_cache_entry_t* apc_cache_find(T cache, apc_cache_key_t key, time_t t);
162 * apc_cache_user_find searches for a cache entry by its hashed identifier,
163 * and returns a pointer to the entry if found, NULL otherwise.
166 extern apc_cache_entry_t* apc_cache_user_find(T cache, char* strkey, int keylen, time_t t);
169 * apc_cache_user_delete finds an entry in the user cache and deletes it.
171 extern int apc_cache_user_delete(apc_cache_t* cache, char *strkey, int keylen);
173 /* apc_cach_fetch_zval takes a zval in the cache and reconstructs a runtime
177 zval* apc_cache_fetch_zval(zval* dst, const zval* src, apc_malloc_t allocate, apc_free_t deallocate);
180 * apc_cache_release decrements the reference count associated with a cache
181 * entry. Calling apc_cache_find automatically increments the reference count,
182 * and this function must be called post-execution to return the count to its
183 * original value. Failing to do so will prevent the entry from being
186 * entry is the cache entry whose ref count you want to decrement.
188 extern void apc_cache_release(T cache, apc_cache_entry_t* entry);
191 * apc_cache_make_file_key creates a key object given a relative or absolute
192 * filename and an optional list of auxillary paths to search. include_path is
193 * searched if the filename cannot be found relative to the current working
196 * key points to caller-allocated storage (must not be null).
198 * filename is the path to the source file.
200 * include_path is a colon-separated list of directories to search.
202 * and finally we pass in the current request time so we can avoid
203 * caching files with a current mtime which tends to indicate that
204 * they are still being written to.
206 extern int apc_cache_make_file_key(apc_cache_key_t* key,
207 const char* filename,
208 const char* include_path,
213 * apc_cache_make_file_entry creates an apc_cache_entry_t object given a filename
214 * and the compilation results returned by the PHP compiler.
216 extern apc_cache_entry_t* apc_cache_make_file_entry(const char* filename,
217 zend_op_array* op_array,
218 apc_function_t* functions,
219 apc_class_t* classes);
221 * apc_cache_make_user_entry creates an apc_cache_entry_t object given an info string
222 * and the zval to be stored.
224 extern apc_cache_entry_t* apc_cache_make_user_entry(const char* info, int info_len, const zval *val, const unsigned int ttl);
226 extern int apc_cache_make_user_key(apc_cache_key_t* key, char* identifier, int identifier_len, const time_t t);
229 * Frees all memory associated with an object returned by apc_cache_make_entry
232 extern void apc_cache_free_entry(apc_cache_entry_t* entry);
234 /* {{{ struct definition: apc_cache_link_data_t */
235 typedef union _apc_cache_link_data_t {
245 } apc_cache_link_data_t;
248 /* {{{ struct definition: apc_cache_link_t */
249 typedef struct apc_cache_link_t apc_cache_link_t;
250 struct apc_cache_link_t {
251 apc_cache_link_data_t data;
255 time_t creation_time;
256 time_t deletion_time;
260 apc_cache_link_t* next;
264 /* {{{ struct definition: apc_cache_info_t */
265 typedef struct apc_cache_info_t apc_cache_info_t;
266 struct apc_cache_info_t {
271 apc_cache_link_t* list;
272 apc_cache_link_t* deleted_list;
281 /* {{{ struct definition: slot_t */
282 typedef struct slot_t slot_t;
284 apc_cache_key_t key; /* slot key */
285 apc_cache_entry_t* value; /* slot value */
286 slot_t* next; /* next slot in linked list */
287 int num_hits; /* number of hits to this bucket */
288 time_t creation_time; /* time slot was initialized */
289 time_t deletion_time; /* time slot was removed from cache */
290 time_t access_time; /* time slot was last accessed */
294 /* {{{ struct definition: cache_header_t
295 Any values that must be shared among processes should go in here. */
296 typedef struct cache_header_t cache_header_t;
297 struct cache_header_t {
298 apc_lck_t lock; /* read/write lock (exclusive blocking cache lock) */
299 apc_lck_t wrlock; /* write lock (non-blocking used to prevent cache slams) */
300 int num_hits; /* total successful hits in cache */
301 int num_misses; /* total unsuccessful hits in cache */
302 int num_inserts; /* total successful inserts in cache */
303 slot_t* deleted_list; /* linked list of to-be-deleted slots */
304 time_t start_time; /* time the above counters were reset */
305 int expunges; /* total number of expunges */
306 zend_bool busy; /* Flag to tell clients when we are busy cleaning the cache */
307 int num_entries; /* Statistic on the number of entries */
308 size_t mem_size; /* Statistic on the memory size used by this cache */
312 /* {{{ struct definition: apc_cache_t */
314 void* shmaddr; /* process (local) address of shared cache */
315 cache_header_t* header; /* cache header (stored in SHM) */
316 slot_t** slots; /* array of cache slots (stored in SHM) */
317 int num_slots; /* number of slots in cache */
318 int gc_ttl; /* maximum time on GC list for a slot */
319 int ttl; /* if slot is needed and entry's access time is older than this ttl, remove it */
323 extern apc_cache_info_t* apc_cache_info(T cache, zend_bool limited);
324 extern void apc_cache_free_info(apc_cache_info_t* info);
325 extern void apc_cache_expunge(apc_cache_t* cache, time_t t);
326 extern void apc_cache_unlock(apc_cache_t* cache);
327 extern zend_bool apc_cache_busy(apc_cache_t* cache);
328 extern zend_bool apc_cache_write_lock(apc_cache_t* cache);
329 extern void apc_cache_write_unlock(apc_cache_t* cache);
339 * vim600: expandtab sw=4 ts=4 sts=4 fdm=marker
340 * vim<600: expandtab sw=4 ts=4 sts=4