<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Compare and swap an item</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="memcached.appendbykey.html">Memcached::appendByKey</a></div>
<div class="next" style="text-align: right; float: right;"><a href="memcached.casbykey.html">Memcached::casByKey</a></div>
<div class="up"><a href="class.memcached.html">Memcached</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="memcached.cas" class="refentry">
<div class="refnamediv">
<h1 class="refname">Memcached::cas</h1>
<p class="verinfo">(PECL memcached >= 0.1.0)</p><p class="refpurpose"><span class="refname">Memcached::cas</span> — <span class="dc-title">Compare and swap an item</span></p>
</div>
<div class="refsect1 description" id="refsect1-memcached.cas-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="type">bool</span> <span class="methodname"><strong>Memcached::cas</strong></span>
( <span class="methodparam"><span class="type">float</span> <code class="parameter">$cas_token</code></span>
, <span class="methodparam"><span class="type">string</span> <code class="parameter">$key</code></span>
, <span class="methodparam"><span class="type"><a href="language.pseudo-types.html#language.types.mixed" class="type mixed">mixed</a></span> <code class="parameter">$value</code></span>
[, <span class="methodparam"><span class="type">int</span> <code class="parameter">$expiration</code></span>
] )</div>
<p class="para rdfs-comment">
<span class="function"><strong>Memcached::cas()</strong></span> 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
<em><code class="parameter">cas_token</code></em> parameter which is a unique 64-bit
value assigned to the existing item by memcache. See the documentation for
<span class="methodname"><strong>Memcached::get*()</strong></span> methods for how to obtain this
token. Note that the token is represented as a double due to the
limitations of PHP's integer space.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-memcached.cas-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">cas_token</code></em></span>
<dd>
<p class="para">
Unique value associated with the existing item. Generated by memcache.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">key</code></em></span>
<dd>
<p class="para">
The key under which to store the value.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">value</code></em></span>
<dd>
<p class="para">
The value to store.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">expiration</code></em></span>
<dd>
<p class="para">
The expiration time, defaults to 0. See <a href="memcached.expiration.html" class="link">Expiration Times</a> for more info.
</p>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-memcached.cas-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns <strong><code>TRUE</code></strong> on success or <strong><code>FALSE</code></strong> on failure.
The <span class="methodname"><a href="memcached.getresultcode.html" class="methodname">Memcached::getResultCode()</a></span> will return
<strong><code>Memcached::RES_DATA_EXISTS</code></strong> if the item you are trying
to store has been modified since you last fetched it.
</p>
</div>
<div class="refsect1 examples" id="refsect1-memcached.cas-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-4431">
<p><strong>Example #1 <span class="function"><strong>Memcached::cas()</strong></span> example</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$m </span><span style="color: #007700">= new </span><span style="color: #0000BB">Memcached</span><span style="color: #007700">();<br /></span><span style="color: #0000BB">$m</span><span style="color: #007700">-></span><span style="color: #0000BB">addServer</span><span style="color: #007700">(</span><span style="color: #DD0000">'localhost'</span><span style="color: #007700">, </span><span style="color: #0000BB">11211</span><span style="color: #007700">);<br /><br />do {<br /> </span><span style="color: #FF8000">/* fetch IP list and its token */<br /> </span><span style="color: #0000BB">$ips </span><span style="color: #007700">= </span><span style="color: #0000BB">$m</span><span style="color: #007700">-></span><span style="color: #0000BB">get</span><span style="color: #007700">(</span><span style="color: #DD0000">'ip_block'</span><span style="color: #007700">, </span><span style="color: #0000BB">null</span><span style="color: #007700">, </span><span style="color: #0000BB">$cas</span><span style="color: #007700">);<br /> </span><span style="color: #FF8000">/* if list doesn't exist yet, create it and do<br /> an atomic add which will fail if someone else already added it */<br /> </span><span style="color: #007700">if (</span><span style="color: #0000BB">$m</span><span style="color: #007700">-></span><span style="color: #0000BB">getResultCode</span><span style="color: #007700">() == </span><span style="color: #0000BB">Memcached</span><span style="color: #007700">::</span><span style="color: #0000BB">RES_NOTFOUND</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">$ips </span><span style="color: #007700">= array(</span><span style="color: #0000BB">$_SERVER</span><span style="color: #007700">[</span><span style="color: #DD0000">'REMOTE_ADDR'</span><span style="color: #007700">]);<br /> </span><span style="color: #0000BB">$m</span><span style="color: #007700">-></span><span style="color: #0000BB">add</span><span style="color: #007700">(</span><span style="color: #DD0000">'ip_block'</span><span style="color: #007700">, </span><span style="color: #0000BB">$ips</span><span style="color: #007700">);<br /> </span><span style="color: #FF8000">/* otherwise, add IP to the list and store via compare-and-swap<br /> with the token, which will fail if someone else updated the list */<br /> </span><span style="color: #007700">} else { <br /> </span><span style="color: #0000BB">$ips</span><span style="color: #007700">[] = </span><span style="color: #0000BB">$_SERVER</span><span style="color: #007700">[</span><span style="color: #DD0000">'REMOTE_ADDR'</span><span style="color: #007700">];<br /> </span><span style="color: #0000BB">$m</span><span style="color: #007700">-></span><span style="color: #0000BB">cas</span><span style="color: #007700">(</span><span style="color: #0000BB">$cas</span><span style="color: #007700">, </span><span style="color: #DD0000">'ip_block'</span><span style="color: #007700">, </span><span style="color: #0000BB">$ips</span><span style="color: #007700">);<br /> } <br />} while (</span><span style="color: #0000BB">$m</span><span style="color: #007700">-></span><span style="color: #0000BB">getResultCode</span><span style="color: #007700">() != </span><span style="color: #0000BB">Memcached</span><span style="color: #007700">::</span><span style="color: #0000BB">RES_SUCCESS</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
</div>
<div class="refsect1 seealso" id="refsect1-memcached.cas-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"> <span class="methodname"><a href="memcached.casbykey.html" class="methodname" rel="rdfs-seeAlso">Memcached::casByKey()</a> - Compare and swap an item on a specific server</span></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="memcached.appendbykey.html">Memcached::appendByKey</a></div>
<div class="next" style="text-align: right; float: right;"><a href="memcached.casbykey.html">Memcached::casByKey</a></div>
<div class="up"><a href="class.memcached.html">Memcached</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
