<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="memcached.cas" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>Memcached::cas</refname>
  <refpurpose>Compare and swap an item</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis role="Memcached">
   <modifier>public</modifier> <type>bool</type><methodname>Memcached::cas</methodname>
   <methodparam><type class="union"><type>string</type><type>int</type><type>float</type></type><parameter>cas_token</parameter></methodparam>
   <methodparam><type>string</type><parameter>key</parameter></methodparam>
   <methodparam><type>mixed</type><parameter>value</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>expiration</parameter><initializer>0</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>Memcached::cas</function> performs a "check and set" operation,
   so that the item will be stored only if no other client has updated it
   since it was last fetched by this client. The check is done via the
   <parameter>cas_token</parameter> parameter which is a unique 64-bit
   value assigned to the existing item by memcache. See the documentation for 
   <methodname>Memcached::get*</methodname> methods for how to obtain this
   token. Note that the token is represented as a float due to the
   limitations of PHP's integer space.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>cas_token</parameter></term>
     <listitem>
      <para>
       Unique value associated with the existing item. Generated by memcache.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>key</parameter></term>
     <listitem>
      <para>
       &memcached.parameter.key;
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>value</parameter></term>
     <listitem>
      <para>
       &memcached.parameter.value;
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>expiration</parameter></term>
     <listitem>
      <para>
       &memcached.parameter.expiration;
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
   The <methodname>Memcached::getResultCode</methodname> will return
   <constant>Memcached::RES_DATA_EXISTS</constant> if the item you are trying
   to store has been modified since you last fetched it.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>Memcached::cas</function> example</title>
    <programlisting role="php">
<![CDATA[
<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

do {
    /* fetch IP list and its token */
    $ips = $m->get('ip_block', null, $cas);
    /* if list doesn't exist yet, create it and do
       an atomic add which will fail if someone else already added it */
    if ($m->getResultCode() == Memcached::RES_NOTFOUND) {
        $ips = array($_SERVER['REMOTE_ADDR']);
        $m->add('ip_block', $ips);
    /* otherwise, add IP to the list and store via compare-and-swap
       with the token, which will fail if someone else updated the list */
    } else { 
        $ips[] = $_SERVER['REMOTE_ADDR'];
        $m->cas($cas, 'ip_block', $ips);
    }   
} while ($m->getResultCode() != Memcached::RES_SUCCESS);

?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><methodname>Memcached::casByKey</methodname></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
-->
