From 41f441d8fb8a37042c66f77bf9299ac65656cb4b Mon Sep 17 00:00:00 2001 From: Sean Coates Date: Sun, 14 Aug 2005 04:01:15 +0000 Subject: [PATCH] initial apc docs -- feel free to tweak git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@193356 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/apc/functions/apc-cache-info.xml | 107 ++++++ reference/apc/functions/apc-clear-cache.xml | 38 ++ .../apc/functions/apc-define-constants.xml | 146 ++++++++ reference/apc/functions/apc-delete.xml | 90 +++++ reference/apc/functions/apc-fetch.xml | 95 +++++ .../apc/functions/apc-load-constants.xml | 116 ++++++ reference/apc/functions/apc-sma-info.xml | 97 +++++ reference/apc/functions/apc-store.xml | 129 +++++++ reference/apc/ini.xml | 342 ++++++++++++++++++ reference/apc/reference.xml | 66 ++++ 10 files changed, 1226 insertions(+) create mode 100644 reference/apc/functions/apc-cache-info.xml create mode 100644 reference/apc/functions/apc-clear-cache.xml create mode 100644 reference/apc/functions/apc-define-constants.xml create mode 100644 reference/apc/functions/apc-delete.xml create mode 100644 reference/apc/functions/apc-fetch.xml create mode 100644 reference/apc/functions/apc-load-constants.xml create mode 100644 reference/apc/functions/apc-sma-info.xml create mode 100644 reference/apc/functions/apc-store.xml create mode 100644 reference/apc/ini.xml create mode 100644 reference/apc/reference.xml diff --git a/reference/apc/functions/apc-cache-info.xml b/reference/apc/functions/apc-cache-info.xml new file mode 100644 index 0000000000..8d8aaf0c69 --- /dev/null +++ b/reference/apc/functions/apc-cache-info.xml @@ -0,0 +1,107 @@ + + + + + apc_cache_info + + Retrieves cached information (and meta-data) from APC's data store + + + + &reftitle.description; + + arrayapc_cache_info + + + + + + &reftitle.returnvalues; + + Array of cached data (and meta-data), or &false; on failure + + + + apc_cache_info will raise a warning if it is unable to + retrieve APC cache data. This typically occurs when APC is not enabled. + + + + + + &reftitle.examples; + + + A <function>apc_cache_info</function> example + + +]]> + + &example.outputs.similar; + + 2000 + [ttl] => 0 + [num_hits] => 9 + [num_misses] => 3 + [start_time] => 1123958803 + [cache_list] => Array + ( + [0] => Array + ( + [filename] => /path/to/apc_test.php + [device] => 29954 + [inode] => 1130511 + [type] => file + [num_hits] => 1 + [mtime] => 1123960686 + [creation_time] => 1123960696 + [deletion_time] => 0 + [access_time] => 1123962864 + [ref_count] => 1 + [mem_size] => 677 + ) + [1] => Array (...iterates for each cached file) +) +]]> + + + + + + + &reftitle.seealso; + + + APC configuration directives + + + + + + + diff --git a/reference/apc/functions/apc-clear-cache.xml b/reference/apc/functions/apc-clear-cache.xml new file mode 100644 index 0000000000..50bfd701dd --- /dev/null +++ b/reference/apc/functions/apc-clear-cache.xml @@ -0,0 +1,38 @@ + + + + + apc_clear_cache + + Clears the APC cache + + + + &reftitle.description; + + voidapc_clear_cache + + + + + + diff --git a/reference/apc/functions/apc-define-constants.xml b/reference/apc/functions/apc-define-constants.xml new file mode 100644 index 0000000000..a59e37a115 --- /dev/null +++ b/reference/apc/functions/apc-define-constants.xml @@ -0,0 +1,146 @@ + + + + + apc_define_constants + + Defines a set of constants for later retrieval and mass-definition + + + + &reftitle.description; + + mixedapc_define_constants + stringkey + arrayconstants + boolcase_sensitive + + + + define is notoriously slow. Since the main benefit of + APC is to increase the performance of scripts/applications, this mechanism + is provided to streamline the process of mass constant definition. + + + + + To remove a set of stored constants (without clearing the entire cache), an + empty array may be passed as the constants + parameter, effectively clearing the stored value(s). + + + + + + &reftitle.parameters; + + + + key + + + The key serves as the name of the constant set + being stored. This key is used to retrieve the + stored constants in apc_load_constants. + + + + + constants + + + An associative array of constant_name => value + pairs. The constant_name must follow the normal + constant naming rules. + value must evaluate to a scalar value. + + + + + case_sensitive + + + The default behaviour for constants is to be declared case-sensitive; + i.e. CONSTANT and Constant + represent different values. If this parameter evaluates to &false; the + constants will be declared as case-insensitive symbols. + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + + &reftitle.examples; + + + <function>apc_define_constants</function> example + + 1, + 'TWO' => 2, + 'THREE' => 3, +); +apc_define_constants('numbers', $constants); +apc_load_constants('numbers'); +echo ONE, TWO, THREE; +?> +]]> + + &example.outputs; + + + + + + + + + + &reftitle.seealso; + + + apc_load_constants + define + constant + + Or the PHP constants reference + + + + + + + + diff --git a/reference/apc/functions/apc-delete.xml b/reference/apc/functions/apc-delete.xml new file mode 100644 index 0000000000..2109f4ffc7 --- /dev/null +++ b/reference/apc/functions/apc-delete.xml @@ -0,0 +1,90 @@ + + + + + apc_delete + + Removes a stored variable from the cache + + + + &reftitle.description; + + boolapc_delete + stringkey + + + + &reftitle.parameters; + + + + key + + + The key used to store the value (with + apc_store). + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.examples; + + + A <function>apc_delete</function> example + + +]]> + + + + + + + &reftitle.seealso; + + + apc_store + apc_fetch + + + + + + + diff --git a/reference/apc/functions/apc-fetch.xml b/reference/apc/functions/apc-fetch.xml new file mode 100644 index 0000000000..ed32702dba --- /dev/null +++ b/reference/apc/functions/apc-fetch.xml @@ -0,0 +1,95 @@ + + + + + apc_fetch + + Fetch a stored variable from the cache + + + + &reftitle.description; + + mixedapc_fetch + stringkey + + + + &reftitle.parameters; + + + + key + + + The key used to store the value (with + apc_store). + + + + + + + + &reftitle.returnvalues; + + The stored variable on success; &false; on failure + + + + + &reftitle.examples; + + + A <function>apc_fetch</function> example + + +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + apc_store + apc_delete + + + + + + + diff --git a/reference/apc/functions/apc-load-constants.xml b/reference/apc/functions/apc-load-constants.xml new file mode 100644 index 0000000000..4134594e01 --- /dev/null +++ b/reference/apc/functions/apc-load-constants.xml @@ -0,0 +1,116 @@ + + + + + apc_load_constants + + Loads a set of constants from the cache + + + + &reftitle.description; + + mixedapc_load_constants + stringkey + boolcase_sensitive + + + + &reftitle.parameters; + + + + key + + + The name of the constant set (that was stored with + apc_define_constants) to be retrieved. + + + + + case_sensitive + + + The default behaviour for constants is to be declared case-sensitive; + i.e. CONSTANT and Constant + represent different values. If this parameter evaluates to &false; the + constants will be declared as case-insensitive symbols. + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.examples; + + + <function>apc_load_constants</function> example + + 1, + 'TWO' => 2, + 'THREE' => 3, +); +apc_define_constants('numbers', $constants); +apc_load_constants('numbers'); +echo ONE, TWO, THREE; +?> +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + apc_define_constants + define + constant + + Or the PHP constants reference + + + + + + + + diff --git a/reference/apc/functions/apc-sma-info.xml b/reference/apc/functions/apc-sma-info.xml new file mode 100644 index 0000000000..5f905c6a75 --- /dev/null +++ b/reference/apc/functions/apc-sma-info.xml @@ -0,0 +1,97 @@ + + + + + apc_sma_info + + Retrieves APC's Shared Memory Allocation information + + + + &reftitle.description; + + arrayapc_sma_info + + + + + &reftitle.returnvalues; + + Array of Shared Memory Allocation data; &false; on failure. + + + + + &reftitle.examples; + + + A <function>apc_sma_info</function> example + + +]]> + + &example.outputs.similar; + + 1 + [seg_size] => 31457280 + [avail_mem] => 31448408 + [block_lists] => Array + ( + [0] => Array + ( + [0] => Array + ( + [size] => 31448408 + [offset] => 8864 + ) + + ) + + ) + +) +]]> + + + + + + + &reftitle.seealso; + + + + APC configuration directives + + + + + + + + diff --git a/reference/apc/functions/apc-store.xml b/reference/apc/functions/apc-store.xml new file mode 100644 index 0000000000..8a2e26468b --- /dev/null +++ b/reference/apc/functions/apc-store.xml @@ -0,0 +1,129 @@ + + + + + apc_store + + Cache a variable in the data store + + + + &reftitle.description; + + boolapc_store + stringkey + mixedvar + intttl + + + + + Unlike many other mechanisms in PHP, variables stored using + apc_store will persist between requests (until the + value is removed from the cache). + + + + + &reftitle.parameters; + + + + key + + + Store the variable using this name. keys are + cache-unique, so storing a second value with the same + key will overwrite the original value. + + + + + var + + + The variable to store + + + + + ttl + + + Time To Live; store var in the cache for + ttl seconds. After the + ttl has passed, the stored variable will be + automatically expunged from the cache. If no ttl + is supplied (or if the ttl is + 0), the value will persist until it is removed from + the cache manually, or otherwise fails to exist in the cache (clear, + restart, etc.). + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.examples; + + + A <function>apc_store</function> example + + +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + apc_fetch + apc_delete + + + + + + + diff --git a/reference/apc/ini.xml b/reference/apc/ini.xml new file mode 100644 index 0000000000..aaa7950e4f --- /dev/null +++ b/reference/apc/ini.xml @@ -0,0 +1,342 @@ + + +
+ &reftitle.runtime; + &extension.runtime; + + Although the default APC settings are fine for many installations, serious + users should consider tuning the following parameters. + + + + APC configuration options + + + + Name + Default + Changeable + Changelog + + + + + apc.enabled + 1 + PHP_INI_ALL + + + + apc.shm_segments + 1 + PHP_INI_SYSTEM + + + + apc.shm_size + 30 + PHP_INI_SYSTEM + + + + apc.optimization + 0 + PHP_INI_ALL + + + + apc.num_files_hint + 1000 + PHP_INI_SYSTEM + + + + apc.ttl + 0 + PHP_INI_SYSTEM + + + + apc.gc_ttl + 3600 + PHP_INI_SYSTEM + + + + apc.cache_by_default + On + PHP_INI_SYSTEM + + + + apc.filters + "" + PHP_INI_SYSTEM + + + + apc.mmap_file_mask + "" + PHP_INI_SYSTEM + + + + apc.slam_defense + 0 + PHP_INI_SYSTEM + + + + apc.file_update_protection + 2 + PHP_INI_SYSTEM + + + + +
+ &ini.php.constants; + + + &ini.descriptions.title; + + + + + + apc.enabled + boolean + + + + apc.enabled can be set to 0 to disable APC. This is + primarily useful when APC is statically compiled + into PHP, since there is no other way to disable + it (when compiled as a DSO, the zend_extension + line can just be commented-out). + + + + + + apc.shm_segments + integer + + + + The number of shared memory segments to allocate + for the compiler cache. If APC is running out of + shared memory but you have already set + apc.shm_size as high as your system allows, you + can try raising this value. + + + + + + apc.shm_size + integer + + + + The size of each shared memory segment in MB. + By default, some systems (including most BSD + variants) have very low limits on the size of a + shared memory segment. + + + + + + apc.optimization + integer + + + + The optimization level. Zero disables the + optimizer, and higher values use more aggressive + optimizations. Expect very modest speed + improvements. This is experimental. + + + + + + apc.num_files_hint + integer + + + + A "hint" about the number of distinct source files + that will be included or requested on your web + server. Set to zero or omit if you're not sure; + this setting is mainly useful for sites that have + many thousands of source files. + + + + + + apc.ttl + integer + + + + The number of seconds a cache entry is allowed to + idle in a slot in case this cache entry slot is + needed by another entry. Leaving this at zero + means that your cache could potentially fill up + with stale entries while newer entries won't be + cached. + + + + + + apc.gc_ttl + integer + + + + The number of seconds that a cache entry may + remain on the garbage-collection list. This value + provides a failsafe in the event that a server + process dies while executing a cached source file; + if that source file is modified, the memory + allocated for the old version will not be + reclaimed until this TTL reached. Set to zero to + disable this feature. + + + + + + apc.cache_by_default + boolean + + + + On by default, but can be set to off and used in + conjunction with positive apc.filters so that files + are only cached if matched by a positive filter. + + + + + + apc.filters + string + + + + A comma-separated list of POSIX extended regular + expressions. If any pattern matches the source + filename, the file will not be cached. Note that + the filename used for matching is the one passed + to include/require, not the absolute path. If the + first character of the expression is a + then the + expression will be additive in the sense that any + files matched by the expression will be cached, and + if the first character is a - then anything matched + will not be cached. The - case is the default, so + it can be left off. + + + + + + apc.mmap_file_mask + string + + + + If compiled with MMAP support by using --enable-mmap + this is the mktemp-style file_mask to pass to the + mmap module for determing whether your mmap'ed memory + region is going to be file-backed or shared memory + backed. For straight file-backed mmap, set it to + something like /tmp/apc.XXXXXX + (exactly 6 Xs). + To use POSIX-style shm_open/mmap put a .shm + somewhere in your mask. e.g. /apc.shm.XXXXXX + You can also set it to /dev/zero to use your + kernel's /dev/zero interface to anonymous mmap'ed + memory. Leaving it undefined will force an anonymous mmap. + + + + + + apc.slam_defense + integer + + + + On very busy servers whenever you start the server or + modify files you can create a race of many processes + all trying to cache the same file at the same time. + This option sets the percentage of processes that will + skip trying to cache an uncached file. Or think of it + as the probability of a single process to skip caching. + For example, setting apc.slam_defense + to 75 would mean that there is + a 75% chance that the process will not cache an uncached + file. So, the higher the setting the greater the defense + against cache slams. Setting this to 0 + disables this feature. + + + + + + apc.file_update_protection + integer + + + + When you modify a file on a live web server you really + should do so in an atomic manner. That is, write to a + temporary file and rename (mv) the file into its + permanent position when it is ready. Many text editors, cp, tar and + other such programs don't do this. This means that there + is a chance that a file is accessed (and cached) while it + is still being written to. This apc.file_update_protection + setting puts a delay on caching brand new files. The + default is 2 seconds which means that if the modification + timestamp (mtime) on a file shows that it is less than 2 + seconds old when it is accessed, it will not be cached. + The unfortunate person who accessed this half-written file + will still see weirdness, but at least it won't persist. + If you are certain you always atomically update your files + by using something like rsync which does this correctly, you + can turn this protection off by setting it to 0. If you + have a system that is flooded with io causing some update + procedure to take longer than 2 seconds, you may want to + increase this a bit. + + + + + +
+ + diff --git a/reference/apc/reference.xml b/reference/apc/reference.xml new file mode 100644 index 0000000000..f5ea6d00d3 --- /dev/null +++ b/reference/apc/reference.xml @@ -0,0 +1,66 @@ + + + + Alternative PHP Cache + APC + + +
+ &reftitle.intro; + + The Alternative PHP Cache (APC) is a free and open opcode cache for PHP. + It was conceived of to provide a free, open, and robust framework for + caching and optimizing PHP intermediate code. + +
+ +
+ &reftitle.install; + + &pecl.moved; + + + &pecl.info; + &url.pecl.package;apc. + + + &pecl.windows.download; + +
+ + &reference.apc.ini; + +
+ &reftitle.resources; + &no.resource; +
+ +
+ &reftitle.constants; + &no.constants; +
+ + +&reference.apc.functions; + + +