apc_cache.h

   1 /*
   2   +----------------------------------------------------------------------+
   3   | APC                                                                  |
   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   +----------------------------------------------------------------------+
  18
  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.
  24
  25    All other licensing and usage conditions are those of the PHP Group.
  26
  27  */
  28
  29 /* $Id: apc_cache.h,v 3.46.2.4 2008/05/11 18:57:00 rasmus Exp $ */
  30
  31 #ifndef APC_CACHE_H
  32 #define APC_CACHE_H
  33
  34 /*
  35  * This module defines the shared memory file cache. Basically all of the
  36  * logic for storing and retrieving cache entries lives here.
  37  */
  38
  39 #include "apc.h"
  40 #include "apc_compile.h"
  41 #include "apc_lock.h"
  42
  43 #define APC_CACHE_ENTRY_FILE   1
  44 #define APC_CACHE_ENTRY_USER   2
  45
  46 #define APC_CACHE_KEY_FILE     1
  47 #define APC_CACHE_KEY_USER     2
  48 #define APC_CACHE_KEY_FPFILE   3
  49
  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 */
  53
  54 typedef union _apc_cache_key_data_t {
  55     struct {
  56         dev_t device;             /* the filesystem device */
  57         ino_t inode;              /* the filesystem inode */
  58     } file;
  59     struct {
  60         const char *identifier;
  61         int identifier_len;
  62     } user;
  63     struct {
  64         const char *fullpath;
  65         int fullpath_len;
  66     } fpfile;
  67 } apc_cache_key_data_t;
  68
  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 */
  73     unsigned char type;
  74 };
  75 /* }}} */
  76
  77 /* {{{ struct definition: apc_cache_entry_t */
  78 typedef union _apc_cache_entry_value_t {
  79     struct {
  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 */
  84     } file;
  85     struct {
  86         char *info;
  87         int info_len;
  88         zval *val;
  89         unsigned int ttl;
  90     } user;
  91 } apc_cache_entry_value_t;
  92
  93 typedef struct apc_cache_entry_t apc_cache_entry_t;
  94 struct apc_cache_entry_t {
  95     apc_cache_entry_value_t data;
  96     unsigned char type;
  97     int ref_count;
  98     size_t mem_size;
  99 };
 100 /* }}} */
 101
 102 /*
 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.
 107  *
 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.
 111  *
 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).
 115  *
 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.
 119  */
 120 extern T apc_cache_create(int size_hint, int gc_ttl, int ttl);
 121
 122 /*
 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
 125  * when they exit.
 126  */
 127 extern void apc_cache_destroy(T cache);
 128
 129 /*
 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.
 132  */
 133 extern void apc_cache_clear(T cache);
 134
 135 /*
 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).
 142  *
 143  * key is the value created by apc_cache_make_file_key for file keys.
 144  *
 145  * value is a cache entry returned by apc_cache_make_entry (see below).
 146  */
 147 extern int apc_cache_insert(T cache, apc_cache_key_t key,
 148                             apc_cache_entry_t* value, time_t t);
 149
 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);
 152
 153 /*
 154  * apc_cache_find searches for a cache entry by filename, and returns a
 155  * pointer to the entry if found, NULL otherwise.
 156  *
 157  * key is a value created by apc_cache_make_file_key for file keys.
 158  */
 159 extern apc_cache_entry_t* apc_cache_find(T cache, apc_cache_key_t key, time_t t);
 160
 161 /*
 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.
 164  *
 165  */
 166 extern apc_cache_entry_t* apc_cache_user_find(T cache, char* strkey, int keylen, time_t t);
 167
 168 /*
 169  * apc_cache_user_delete finds an entry in the user cache and deletes it.
 170  */
 171 extern int apc_cache_user_delete(apc_cache_t* cache, char *strkey, int keylen);
 172
 173 /* apc_cach_fetch_zval takes a zval in the cache and reconstructs a runtime
 174  * zval from it.
 175  *
 176  */
 177 zval* apc_cache_fetch_zval(zval* dst, const zval* src, apc_malloc_t allocate, apc_free_t deallocate);
 178
 179 /*
 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
 184  * garbage-collected.
 185  *
 186  * entry is the cache entry whose ref count you want to decrement.
 187  */
 188 extern void apc_cache_release(T cache, apc_cache_entry_t* entry);
 189
 190 /*
 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
 194  * directory.
 195  *
 196  * key points to caller-allocated storage (must not be null).
 197  *
 198  * filename is the path to the source file.
 199  *
 200  * include_path is a colon-separated list of directories to search.
 201  *
 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.
 205  */
 206 extern int apc_cache_make_file_key(apc_cache_key_t* key,
 207                                    const char* filename,
 208                                    const char* include_path,
 209                                    time_t t
 210                                                                TSRMLS_DC);
 211
 212 /*
 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.
 215  */
 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);
 220 /*
 221  * apc_cache_make_user_entry creates an apc_cache_entry_t object given an info string
 222  * and the zval to be stored.
 223  */
 224 extern apc_cache_entry_t* apc_cache_make_user_entry(const char* info, int info_len, const zval *val, const unsigned int ttl);
 225
 226 extern int apc_cache_make_user_key(apc_cache_key_t* key, char* identifier, int identifier_len, const time_t t);
 227
 228 /*
 229  * Frees all memory associated with an object returned by apc_cache_make_entry
 230  * (see above).
 231  */
 232 extern void apc_cache_free_entry(apc_cache_entry_t* entry);
 233
 234 /* {{{ struct definition: apc_cache_link_data_t */
 235 typedef union _apc_cache_link_data_t {
 236     struct {
 237         char *filename;
 238         dev_t device;
 239         ino_t inode;
 240     } file;
 241     struct {
 242         char *info;
 243         unsigned int ttl;
 244     } user;
 245 } apc_cache_link_data_t;
 246 /* }}} */
 247
 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;
 252     unsigned char type;
 253     int num_hits;
 254     time_t mtime;
 255     time_t creation_time;
 256     time_t deletion_time;
 257     time_t access_time;
 258     int ref_count;
 259     size_t mem_size;
 260     apc_cache_link_t* next;
 261 };
 262 /* }}} */
 263
 264 /* {{{ struct definition: apc_cache_info_t */
 265 typedef struct apc_cache_info_t apc_cache_info_t;
 266 struct apc_cache_info_t {
 267     int num_slots;
 268     int num_hits;
 269     int num_misses;
 270     int ttl;
 271     apc_cache_link_t* list;
 272     apc_cache_link_t* deleted_list;
 273     time_t start_time;
 274     int expunges;
 275     int num_entries;
 276     int num_inserts;
 277     size_t mem_size;
 278 };
 279 /* }}} */
 280
 281 /* {{{ struct definition: slot_t */
 282 typedef struct slot_t slot_t;
 283 struct 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 */
 291 };
 292 /* }}} */
 293
 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 */
 309 };
 310 /* }}} */
 311
 312 /* {{{ struct definition: apc_cache_t */
 313 struct 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 */
 320 };
 321 /* }}} */
 322
 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);
 330
 331 #undef T
 332 #endif
 333
 334 /*
 335  * Local variables:
 336  * tab-width: 4
 337  * c-basic-offset: 4
 338  * End:
 339  * vim600: expandtab sw=4 ts=4 sts=4 fdm=marker
 340  * vim<600: expandtab sw=4 ts=4 sts=4
 341  */