apcu-entry.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.apcu-entry" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>apcu_entry</refname>
  <refpurpose>
   Atomically fetch or generate a cache entry
  </refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>mixed</type><methodname>apcu_entry</methodname>
   <methodparam><type>string</type><parameter>key</parameter></methodparam>
   <methodparam><type>callable</type><parameter>generator</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>ttl</parameter><initializer>0</initializer></methodparam>
  </methodsynopsis>
  <para>
   Atomically attempts to find <parameter>key</parameter> in the cache, if it cannot be found <parameter>generator</parameter>
   is called, passing <parameter>key</parameter> as the only argument. The return value of the call is then cached with the optionally specified
   <parameter>ttl</parameter>, and returned.
  </para>
  <note>
   <simpara>
    When control enters <function>apcu_entry</function> the lock for the cache is acquired exclusively, it is released when control leaves <function>apcu_entry</function>: 
    In effect, this turns the body of <parameter>generator</parameter> into a critical section, disallowing two processes from executing the same code paths concurrently.
    In addition, it prohibits the concurrent execution of any other APCu functions, since they will acquire the same lock.
   </simpara>
  </note>
  <warning>
   <simpara>
    The only APCu function that can be called safely by <parameter>generator</parameter> is <function>apcu_entry</function>.
   </simpara>
  </warning>
 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>key</parameter></term>
     <listitem>
      <para>
       Identity of cache entry
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>generator</parameter></term>
     <listitem>
      <para>
       A callable that accepts <parameter>key</parameter> as the only argument and returns the value to cache.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>ttl</parameter></term>
     <listitem>
      <para>
       Time To Live; store <parameter>var</parameter> in the cache for
       <parameter>ttl</parameter> seconds. After the
       <parameter>ttl</parameter> has passed, the stored variable will be
       expunged from the cache (on the next request). If no <parameter>ttl</parameter>
       is supplied (or if the <parameter>ttl</parameter> is
       <literal>0</literal>), the value will persist until it is removed from
       the cache manually, or otherwise fails to exist in the cache (clear,
       restart, etc.).
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns the cached value
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>An <function>apcu_entry</function> example</title>
    <programlisting role="php">
<![CDATA[
<?php
$config = apcu_entry("config", function($key) {
 return [
   "fruit" => apcu_entry("config.fruit", function($key){
     return [
       "apples",
       "pears"
     ];
   }), 
   "people" => apcu_entry("config.people", function($key){
     return [
      "bob",
      "joe",
      "niki"
     ];
   })
 ];
});

var_dump($config);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
array(2) {
  ["fruit"]=>
  array(2) {
    [0]=>
    string(6) "apples"
    [1]=>
    string(5) "pears"
  }
  ["people"]=>
  array(3) {
    [0]=>
    string(3) "bob"
    [1]=>
    string(3) "joe"
    [2]=>
    string(4) "niki"
  }
}
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>apcu_store</function></member>
    <member><function>apcu_fetch</function></member>
    <member><function>apcu_delete</function></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->