<!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 a client-side timeout for this command</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mongocommandcursor.setreadpreference.html">MongoCommandCursor::setReadPreference</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mongocommandcursor.valid.html">MongoCommandCursor::valid</a></div>
<div class="up"><a href="class.mongocommandcursor.html">MongoCommandCursor</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="mongocommandcursor.timeout" class="refentry">
<div class="refnamediv">
<h1 class="refname">MongoCommandCursor::timeout</h1>
<p class="verinfo">(PECL mongo >=1.6.0)</p><p class="refpurpose"><span class="refname">MongoCommandCursor::timeout</span> — <span class="dc-title">Sets a client-side timeout for this command</span></p>
</div>
<div class="refsect1 description" id="refsect1-mongocommandcursor.timeout-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="type"><a href="class.mongocommandcursor.html" class="type MongoCommandCursor">MongoCommandCursor</a></span> <span class="methodname"><strong>MongoCommandCursor::timeout</strong></span>
( <span class="methodparam"><span class="type">int</span> <code class="parameter">$ms</code></span>
)</div>
<p class="para rdfs-comment">
A timeout can be set at any time and will affect subsequent data retrieval
associated with this cursor, including fetching more results from the
database.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-mongocommandcursor.timeout-parameters">
<h3 class="title">Parameters</h3>
<dl>
<dt>
<code class="parameter">ms</code>
</dt>
<dd>
<p class="para">
The number of milliseconds for the cursor to wait for a response. Use
<em>-1</em> to wait forever. By default, the cursor will wait
<var class="varname"><var class="varname">30000</var></var> milliseconds (30 seconds).
</p>
</dd>
</dl>
</div>
<div class="refsect1 returnvalues" id="refsect1-mongocommandcursor.timeout-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
This cursor.
</p>
</div>
<div class="refsect1 errors" id="refsect1-mongocommandcursor.timeout-errors">
<h3 class="title">Errors/Exceptions</h3>
<p class="para">
Causes methods that fetch results to throw a
<a href="class.mongocursortimeoutexception.html" class="classname">MongoCursorTimeoutException</a> if the data fetch takes
longer than the specified number of milliseconds.
</p>
</div>
<div class="refsect1 examples" id="refsect1-mongocommandcursor.timeout-examples">
<h3 class="title">Examples</h3>
<div class="example" id="example-1640">
<p><strong>Example #1 <span class="function"><strong>MongoCommandCursor::timeout()</strong></span> example</strong></p>
<div class="example-contents"><p>
In the following example, the driver will wait for 60 seconds for the
first response from the aggregate command. It will also wait for 60
seconds each time the server needs to be polled for more information.
</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$m </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoClient</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$col </span><span style="color: #007700">= </span><span style="color: #0000BB">$m</span><span style="color: #007700">-></span><span style="color: #0000BB">database</span><span style="color: #007700">-></span><span style="color: #0000BB">collection</span><span style="color: #007700">;<br /><br /></span><span style="color: #0000BB">$pipeline </span><span style="color: #007700">= [ </span><span style="color: #0000BB">… </span><span style="color: #007700">];<br /><br /></span><span style="color: #0000BB">$cursor </span><span style="color: #007700">= </span><span style="color: #0000BB">$col</span><span style="color: #007700">-></span><span style="color: #0000BB">aggregateCursor</span><span style="color: #007700">( </span><span style="color: #0000BB">$pipeline </span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$cursor</span><span style="color: #007700">-></span><span style="color: #0000BB">timeout</span><span style="color: #007700">( </span><span style="color: #0000BB">60000 </span><span style="color: #007700">); </span><span style="color: #FF8000">// for 60 seconds<br /><br /></span><span style="color: #007700">foreach ( </span><span style="color: #0000BB">$cursor </span><span style="color: #007700">as </span><span style="color: #0000BB">$result </span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">…<br /></span><span style="color: #007700">}<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</div>
<div class="refsect1 notes" id="refsect1-mongocommandcursor.timeout-notes">
<h3 class="title">Notes</h3>
<div class="warning"><strong class="warning">Warning</strong>
<p class="para">
This does not cause the MongoDB server to cancel long-running operations;
it only instructs the driver to stop waiting for a response and throw a
<a href="class.mongocursortimeoutexception.html" class="classname">MongoCursorTimeoutException</a> after a set time.
If you need to specify a server-side timeout for a command, considering
passing the <em>maxTimeMS</em> option to
<span class="methodname"><a href="mongocollection.aggregatecursor.html" class="methodname">MongoCollection::aggregateCursor()</a></span>.
</p>
</div>
</div>
<div class="refsect1 seealso" id="refsect1-mongocommandcursor.timeout-seealso">
<h3 class="title">See Also</h3>
<ul class="simplelist">
<li class="member"><span class="function"><a href="mongocollection.aggregatecursor.html" class="function" rel="rdfs-seeAlso">MongoCollection::aggregateCursor()</a> - Execute an aggregation pipeline command and retrieve results through a cursor</span></li>
<li class="member"><span class="methodname"><a href="mongocursorinterface.timeout.html" class="methodname" rel="rdfs-seeAlso">MongoCursorInterface::timeout()</a> - Sets a client-side timeout for this query</span></li>
<li class="member">The <em>socketTimeoutMS</em> option for <span class="function"><a href="mongoclient.construct.html" class="function">MongoClient::__construct()</a></span></li>
</ul>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mongocommandcursor.setreadpreference.html">MongoCommandCursor::setReadPreference</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mongocommandcursor.valid.html">MongoCommandCursor::valid</a></div>
<div class="up"><a href="class.mongocommandcursor.html">MongoCommandCursor</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
