From 811f95575710f30640f837d30373192f6dbabfd0 Mon Sep 17 00:00:00 2001 From: Ruslan Yakushev Date: Wed, 3 Mar 2010 01:43:44 +0000 Subject: [PATCH] Adding documentation for WinCache 1.1.0 release. Documenting the user cache API's. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@295766 c90b9560-bf6c-de11-be94-00142212c4b1 --- .../functions/wincache-ucache-add.xml | 174 +++++++++++++++++ .../functions/wincache-ucache-cas.xml | 121 ++++++++++++ .../functions/wincache-ucache-clear.xml | 96 ++++++++++ .../functions/wincache-ucache-dec.xml | 120 ++++++++++++ .../functions/wincache-ucache-delete.xml | 152 +++++++++++++++ .../functions/wincache-ucache-exists.xml | 100 ++++++++++ .../functions/wincache-ucache-get.xml | 147 +++++++++++++++ .../functions/wincache-ucache-inc.xml | 120 ++++++++++++ .../functions/wincache-ucache-set.xml | 178 ++++++++++++++++++ reference/wincache/versions.xml | 9 + 10 files changed, 1217 insertions(+) create mode 100644 reference/wincache/functions/wincache-ucache-add.xml create mode 100644 reference/wincache/functions/wincache-ucache-cas.xml create mode 100644 reference/wincache/functions/wincache-ucache-clear.xml create mode 100644 reference/wincache/functions/wincache-ucache-dec.xml create mode 100644 reference/wincache/functions/wincache-ucache-delete.xml create mode 100644 reference/wincache/functions/wincache-ucache-exists.xml create mode 100644 reference/wincache/functions/wincache-ucache-get.xml create mode 100644 reference/wincache/functions/wincache-ucache-inc.xml create mode 100644 reference/wincache/functions/wincache-ucache-set.xml diff --git a/reference/wincache/functions/wincache-ucache-add.xml b/reference/wincache/functions/wincache-ucache-add.xml new file mode 100644 index 0000000000..e6a65635d2 --- /dev/null +++ b/reference/wincache/functions/wincache-ucache-add.xml @@ -0,0 +1,174 @@ + + + + + wincache_ucache_add + + Adds a variable in user cache only if variable does not already exist in the cache + + + + &reftitle.description; + + boolwincache_ucache_add + mixedkey + mixedvalue + intttl0 + + + Adds a variable in user cache, only if this variable doesn't already exist in the cache. + The added variable remains in the user cache unless its time to live expires or it is + deleted by using wincache_ucache_delete or wincache_ucache_clear functions. + + + + &reftitle.parameters; + + + + key + + + Store the variable using this key name. If a variable with same key is already present the function + will fail and return false. key is case sensitive. To override the value even if + key is present use wincache_ucache_set function instad. + key can also take array of name => value pairs where names will be used as keys. + This can be used to add multiple values in the cache in one operation, thus avoiding race condition. + + + + + value + + + Value of a variable to store. Value supports all data types except resources, such as file handles. + This paramter is ignored if first argument is an array. A general guidance is to pass NULL + as value while using array as key. + + + + + ttl + + + Time for the variable to live in the cache in seconds. After the value specified in ttl has passed + the stored variable will be deleted from the cache. This parameter takes a default value of 0 which means + the variable will stay in the cache unless explicitly deleted by using wincache_ucache_delete + or wincache_ucache_clear functions. + + + + + + + + &reftitle.returnvalues; + + If key is string, the function returns TRUE on success and FALSE on failure. + + + If key is an array, the function returns: + + + + If all the name => value pairs in the array can be set, function returns an empty array; + + + + + If all the name => value pairs in the array cannot be set, function returns FALSE; + + + + + If some can be set while others cannot, function returns an array with name=>value pair for which the addition failed in the user cache. + + + + + + + &reftitle.examples; + + + <function>wincache_ucache_add</function> with <parameter>key</parameter> as a string + + +]]> + + &example.outputs; + + + + + + + + <function>wincache_ucache_add</function> with <parameter>key</parameter> as an array + + "5", 'Blue' => "6", 'yellow' => "7", 'cyan' => "8"); +var_dump(wincache_ucache_add($colors_array)); +var_dump(wincache_ucache_add($colors_array)); +var_dump(wincache_ucache_get('Blue')); +?> +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + wincache_ucache_set + wincache_ucache_get + wincache_ucache_delete + wincache_ucache_clear + wincache_ucache_exists + + + + + + + diff --git a/reference/wincache/functions/wincache-ucache-cas.xml b/reference/wincache/functions/wincache-ucache-cas.xml new file mode 100644 index 0000000000..cd187db84c --- /dev/null +++ b/reference/wincache/functions/wincache-ucache-cas.xml @@ -0,0 +1,121 @@ + + + + + wincache_ucache_cas + + Compares the variable with old value and assigns new value to it + + + + &reftitle.description; + + mixedwincache_ucache_cas + stringkey + longold_value + longnew_value + + + Compares the variable associated with the key with old_value + and if it matches then assigns the new_value to it. + + + + &reftitle.parameters; + + + + key + + + The key that is used to store the variable in the cache. + key is case sensitive. + + + + + old_value + + + Old value of the variable pointed by key in the user cache. + The value should be of type long, otherwise the function returns + FALSE. + + + + + new_value + + + New value which will get assigned to variable pointer by key if a + match is found. The value should be of type long, otherwise + the function returns FALSE. + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + &reftitle.examples; + + + Using <function>wincache_ucache_cas</function> + + +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + wincache_ucache_inc + wincache_ucache_dec + + + + + + + diff --git a/reference/wincache/functions/wincache-ucache-clear.xml b/reference/wincache/functions/wincache-ucache-clear.xml new file mode 100644 index 0000000000..9df2b98da5 --- /dev/null +++ b/reference/wincache/functions/wincache-ucache-clear.xml @@ -0,0 +1,96 @@ + + + + + wincache_ucache_clear + + Deletes entire content of the user cache + + + + &reftitle.description; + + boolwincache_ucache_clear + + + + Clears/deletes all the values stored in the user cache. + + + + &reftitle.returnvalues; + + &return.success; + + + + &reftitle.examples; + + + using <function>wincache_ucache_clear</function> + + +]]> + + &example.outputs; + + int(1) + ["red"]=> int(2) + ["orange"]=> int(4) + ["blue"]=> int(8) + ["cyan"]=> int(16) } +bool(true) +bool(false) +]]> + + + + + + + &reftitle.seealso; + + + wincache_ucache_set + wincache_ucache_add + wincache_ucache_delete + wincache_ucache_get + wincache_ucache_exists + + + + + + + diff --git a/reference/wincache/functions/wincache-ucache-dec.xml b/reference/wincache/functions/wincache-ucache-dec.xml new file mode 100644 index 0000000000..d722058272 --- /dev/null +++ b/reference/wincache/functions/wincache-ucache-dec.xml @@ -0,0 +1,120 @@ + + + + + wincache_ucache_dec + + Decrements the value associated with the key + + + + &reftitle.description; + + mixedwincache_ucache_dec + stringkey + longdec_by1 + boolsuccess + + + Decrements the value associated with the key by 1 or as specified + by dec_by. + + + + &reftitle.parameters; + + + + key + + + The key that was used to store the variable in the cache. + key is case sensitive. + + + + + dec_by + + + The value by which the variable associated with the key will get decremented. + If the argument is a floating point number it will be truncated to nearest integer. The variable + associated with the key should be of type long, otherwise + the function fails and returns FALSE. + + + + + success + + + Will be set to TRUE on success and FALSE on failure. + + + + + + + + &reftitle.returnvalues; + + Returns the decremented value on success and FALSE on failure. + + + + &reftitle.examples; + + + Using <function>wincache_ucache_dec</function> + + +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + wincache_ucache_inc + wincache_ucache_cas + + + + + + + diff --git a/reference/wincache/functions/wincache-ucache-delete.xml b/reference/wincache/functions/wincache-ucache-delete.xml new file mode 100644 index 0000000000..464f9e6db1 --- /dev/null +++ b/reference/wincache/functions/wincache-ucache-delete.xml @@ -0,0 +1,152 @@ + + + + + wincache_ucache_delete + + Deletes variables from the user cache + + + + &reftitle.description; + + boolwincache_ucache_delete + mixedkey + + + Deletes the elements in the user cache pointed by key. + + + + &reftitle.parameters; + + + + key + + + The key that was used to store the variable in the cache. + key is case sensitive. key can be an + array of keys. + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + If key is an array then the function returns FALSE + if every element of the array fails to get deleted from the user cache, otherwise returns an + array which consists of all the keys that are deleted. + + + + &reftitle.examples; + + + Using <function>wincache_ucache_delete</function> with <parameter>key</parameter> as a string + + +]]> + + &example.outputs; + + + + + + + + Using<function>wincache_ucache_delete</function> with <parameter>key</parameter> as an array + + '5', 'blue' => '6', 'yellow' => '7', 'cyan' => '8'); +wincache_ucache_set($array1); +$array2 = array('green', 'blue', 'yellow', 'cyan'); +var_dump(wincache_ucache_delete($array2)); +?> +]]> + + &example.outputs; + + string(5) "green" + [1]=> string(4) "Blue" + [2]=> string(6) "yellow" + [3]=> string(4) "cyan" } +]]> + + + + + + Using <function>wincache_ucache_delete</function> with <parameter>key</parameter> as an array where some elements cannot be deleted + + '5', 'blue' => '6', 'yellow' => '7', 'cyan' => '8'); +wincache_ucache_set($array1); +$array2 = array('orange', 'red', 'yellow', 'cyan'); +var_dump(wincache_ucache_delete($array2)); +?> +]]> + + &example.outputs; + + string(6) "yellow" + [1]=> string(4) "cyan" } +]]> + + + + + + &reftitle.seealso; + + + wincache_ucache_set + wincache_ucache_add + wincache_ucache_get + wincache_ucache_clear + wincache_ucache_exists + + + + + + + diff --git a/reference/wincache/functions/wincache-ucache-exists.xml b/reference/wincache/functions/wincache-ucache-exists.xml new file mode 100644 index 0000000000..830dc33fe5 --- /dev/null +++ b/reference/wincache/functions/wincache-ucache-exists.xml @@ -0,0 +1,100 @@ + + + + + wincache_ucache_exists + + Checks if a variable exists in the user cache + + + + &reftitle.description; + + boolwincache_ucache_exists + stringkey + + + Checks if a variable with the key exists in the user cache or not. + + + + &reftitle.parameters; + + + + key + + + The key that was used to store the variable in the cache. + key is case sensitive. + + + + + + + + &reftitle.returnvalues; + + Returns TRUE if variable with the key exitsts, + otherwise returns FALSE. + + + + &reftitle.examples; + + + Using <function>wincache_ucache_exists</function> + + +]]> + + &example.outputs; + + + + + + + + &reftitle.seealso; + + + wincache_ucache_set + wincache_ucache_add + wincache_ucache_get + wincache_ucache_clear + wincache_ucache_delete + + + + + + + diff --git a/reference/wincache/functions/wincache-ucache-get.xml b/reference/wincache/functions/wincache-ucache-get.xml new file mode 100644 index 0000000000..7e67826088 --- /dev/null +++ b/reference/wincache/functions/wincache-ucache-get.xml @@ -0,0 +1,147 @@ + + + + + wincache_ucache_get + + Gets a variable stored in the user cache + + + + &reftitle.description; + + mixedwincache_ucache_get + mixedkey + boolsuccess + + + Gets a variable stored in the user cache. + + + + &reftitle.parameters; + + + + key + + + The key that was used to store the variable in the cache. + key is case sensitive. key can be an + array of keys. In this case the return value will be an array of values of each element + in the key array. + + + + + success + + + Will be set to TRUE on success and FALSE on failure. + + + + + + + + &reftitle.returnvalues; + + If key is a string, the function returns the value of the variable stored with that key. + The success is set to TRUE on success and + to FALSE on failure. + + + The key is an array, the parameter success + is always set to TRUE. The returned array (name => value pairs) will + contain only those name => value pairs for which the get operation in user cache was + successful. If none of the keys in the key array finds a match in the user cache + an empty array will be returned. + + + + &reftitle.examples; + + + <function>wincache_ucache_get</function> with <parameter>key</parameter> as a string + + +]]> + + &example.outputs; + + + + + + + + <function>wincache_ucache_get</function> with <parameter>key</parameter> as an array + + '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8'); +wincache_ucache_set($array1); +$array2 = array('green', 'Blue', 'yellow', 'cyan'); +var_dump(wincache_ucache_get($array2, $success)); +var_dump($success); +?> +]]> + + &example.outputs; + + string(1) "5" + ["Blue"]=> string(1) "6" + ["yellow"]=> string(1) "7" + ["cyan"]=> string(1) "8" } +bool(true) +]]> + + + + + + + &reftitle.seealso; + + + wincache_ucache_add + wincache_ucache_set + wincache_ucache_delete + wincache_ucache_clear + wincache_ucache_exists + + + + + + + diff --git a/reference/wincache/functions/wincache-ucache-inc.xml b/reference/wincache/functions/wincache-ucache-inc.xml new file mode 100644 index 0000000000..bcdd66371f --- /dev/null +++ b/reference/wincache/functions/wincache-ucache-inc.xml @@ -0,0 +1,120 @@ + + + + + wincache_ucache_inc + + Increments the value associated with the key + + + + &reftitle.description; + + mixedwincache_ucache_inc + stringkey + longinc_by1 + boolsuccess + + + Increments the value associated with the key by 1 or as specified + by inc_by. + + + + &reftitle.parameters; + + + + key + + + The key that was used to store the variable in the cache. + key is case sensitive. + + + + + inc_by + + + The value by which the variable associated with the key will get incremented. + If the argument is a floating point number it will be truncated to nearest integer. The variable + associated with the key should be of type long, otherwise + the function fails and returns FALSE. + + + + + success + + + Will be set to TRUE on success and FALSE on failure. + + + + + + + + &reftitle.returnvalues; + + Returns the incremented value on success and FALSE on failure. + + + + &reftitle.examples; + + + Using <function>wincache_ucache_inc</function> + + +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + wincache_ucache_dec + wincache_ucache_cas + + + + + + + diff --git a/reference/wincache/functions/wincache-ucache-set.xml b/reference/wincache/functions/wincache-ucache-set.xml new file mode 100644 index 0000000000..495884d23a --- /dev/null +++ b/reference/wincache/functions/wincache-ucache-set.xml @@ -0,0 +1,178 @@ + + + + + wincache_ucache_set + + Adds a variable in user cache and overwrites a variable if it already exists in the cache + + + + &reftitle.description; + + boolwincache_ucache_set + mixedkey + mixedvalue + intttl0 + + + Adds a variable in user cache. Overwrites a variable if it already exists in the cache. + The added or updated variable remains in the user cache unless its time to live expires or it is + deleted by using wincache_ucache_delete or wincache_ucache_clear functions. + + + + &reftitle.parameters; + + + + key + + + Store the variable using this key name. If a variable with same + key is already present the function will overwrite the previous + value with the new one. key is case sensitive. + key can also take array of name => value pairs where names will be used as + keys. This can be used to add multiple values in the cache in one operation, thus avoiding + race condition. + + + + + value + + + Value of a variable to store. Value supports all data types except resources, such as file handles. + This paramter is ignored if first argument is an array. A general guidance is to pass NULL + as value while using array as key. + + + + + ttl + + + Time for the variable to live in the cache in seconds. After the value specified in ttl has passed + the stored variable will be deleted from the cache. This parameter takes a default value of 0 which means + the variable will stay in the cache unless explicitly deleted by using wincache_ucache_delete + or wincache_ucache_clear functions. + + + + + + + + &reftitle.returnvalues; + + If key is string, the function returns TRUE on success and FALSE on failure. + + + If key is an array, the function returns: + + + + If all the name => value pairs in the array can be set, function returns an empty array; + + + + + If all the name => value pairs in the array cannot be set, function returns FALSE; + + + + + If some can be set while others cannot, function returns an array with name=>value pair for which the addition failed in the user cache. + + + + + + + &reftitle.examples; + + + <function>wincache_ucache_set</function> with <parameter>key</parameter> as a string + + +]]> + + &example.outputs; + + + + + + + + <function>wincache_ucache_set</function> with <parameter>key</parameter> as an array + + '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8'); +var_dump(wincache_ucache_set($colors_array)); +var_dump(wincache_ucache_set($colors_array)); +var_dump(wincache_ucache_get('Blue')); +?> +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + wincache_ucache_add + wincache_ucache_get + wincache_ucache_delete + wincache_ucache_clear + wincache_ucache_exists + + + + + + + diff --git a/reference/wincache/versions.xml b/reference/wincache/versions.xml index 10de15e616..55590a5c3d 100644 --- a/reference/wincache/versions.xml +++ b/reference/wincache/versions.xml @@ -11,6 +11,15 @@ + + + + + + + + +