<!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>Sets whether this cursor will be left open after fetching the last results</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mongocursor.sort.html">MongoCursor::sort</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mongocursor.timeout.html">MongoCursor::timeout</a></div>
<div class="up"><a href="class.mongocursor.html">MongoCursor</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="mongocursor.tailable" class="refentry">
<div class="refnamediv">
<h1 class="refname">MongoCursor::tailable</h1>
<p class="verinfo">(PECL mongo >=0.9.4)</p><p class="refpurpose"><span class="refname">MongoCursor::tailable</span> — <span class="dc-title">Sets whether this cursor will be left open after fetching the last results</span></p>
</div>
<div class="refsect1 description" id="refsect1-mongocursor.tailable-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="type"><a href="class.mongocursor.html" class="type MongoCursor">MongoCursor</a></span> <span class="methodname"><strong>MongoCursor::tailable</strong></span>
([ <span class="methodparam"><span class="type">bool</span> <code class="parameter">$tail</code><span class="initializer"> = true</span></span>
] )</div>
<p class="para rdfs-comment">
Mongo has a feature known as tailable cursors which are similar to the Unix
"tail -f" command.
</p>
<p class="para">
Tailable means cursor is not closed when the last data is retrieved. Rather,
the cursor marks the final object's position. you can resume using the
cursor later, from where it was located, if more data were received.
</p>
<p class="para">
Like any "latent cursor", the cursor may become invalid at some point -- for
example if that final object it references were deleted. Thus, you should be
prepared to requery if the cursor is <span class="function"><a href="mongocursor.dead.html" class="function">MongoCursor::dead()</a></span>.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-mongocursor.tailable-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term">
<em><code class="parameter">tail</code></em>
</span>
<dd>
<p class="para">
If the cursor should be tailable.
</p>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-mongocursor.tailable-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns this cursor.
</p>
</div>
<div class="refsect1 errors" id="refsect1-mongocursor.tailable-errors">
<h3 class="title">Errors/Exceptions</h3>
<p class="para">
Throws <a href="class.mongocursorexception.html" class="classname">MongoCursorException</a> if this cursor has started iterating.
</p>
</div>
<div class="refsect1 examples" id="refsect1-mongocursor.tailable-examples">
<h3 class="title">Examples</h3>
<div class="example" id="example-1487">
<p><strong>Example #1 <span class="function"><strong>MongoCursor::tailable()</strong></span> example</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$cursor </span><span style="color: #007700">= </span><span style="color: #0000BB">$collection</span><span style="color: #007700">-></span><span style="color: #0000BB">find</span><span style="color: #007700">()-></span><span style="color: #0000BB">tailable</span><span style="color: #007700">();<br /><br /></span><span style="color: #0000BB">$results </span><span style="color: #007700">= array();<br /><br />while (</span><span style="color: #0000BB">1</span><span style="color: #007700">) {<br /> if (!</span><span style="color: #0000BB">$cursor</span><span style="color: #007700">-></span><span style="color: #0000BB">hasNext</span><span style="color: #007700">()) {<br /> </span><span style="color: #FF8000">// we've read all the results, exit<br /> </span><span style="color: #007700">if (</span><span style="color: #0000BB">$cursor</span><span style="color: #007700">-></span><span style="color: #0000BB">dead</span><span style="color: #007700">()) {<br /> break;<br /> }<br /> </span><span style="color: #FF8000">// read all results so far, wait for more<br /> </span><span style="color: #0000BB">sleep</span><span style="color: #007700">(</span><span style="color: #0000BB">10</span><span style="color: #007700">);<br /> }<br /> else {<br /> </span><span style="color: #0000BB">$results</span><span style="color: #007700">[] = </span><span style="color: #0000BB">$cursor</span><span style="color: #007700">-></span><span style="color: #0000BB">getNext</span><span style="color: #007700">();<br /> }<br />}<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</div>
<div class="refsect1 seealso" id="refsect1-mongocursor.tailable-seealso">
<h3 class="title">See Also</h3>
<p class="para">
MongoDB core docs on <a href="http://docs.mongodb.org/manual/tutorial/create-tailable-cursor/" class="link external">» tailable cursors</a>.
</p>
<p class="para">
<ul class="simplelist">
<li class="member"> <span class="function"><a href="mongocursor.awaitdata.html" class="function" rel="rdfs-seeAlso">MongoCursor::awaitData()</a> - Sets whether this cursor will wait for a while for a tailable cursor to return more data</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="mongocursor.sort.html">MongoCursor::sort</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mongocursor.timeout.html">MongoCursor::timeout</a></div>
<div class="up"><a href="class.mongocursor.html">MongoCursor</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
