php-doc-en/reference/mongo/mongocursor/immortal.xml

<?xml version="1.0" encoding="utf-8"?>

<!-- $Revision$ -->
<refentry xml:id="mongocursor.immortal" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>MongoCursor::immortal</refname>
  <refpurpose>Sets whether this cursor will timeout</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <modifier>public</modifier> <type>MongoCursor</type><methodname>MongoCursor::immortal</methodname>
   <methodparam choice="opt"><type>bool</type><parameter>liveForever</parameter><initializer>true</initializer></methodparam>
  </methodsynopsis>
  <para>
   After remaining idle for some amount of time, cursor, by default, "die."  
   This is generally the behavior one wants. The database cleans up a cursor
   once all of its results have been sent to the client, but if the client
   doesn't request all of the results, the cursor will languish there, taking up
   resources.  Thus, after a few minutes, the cursor "times out" and the 
   database assumes the client has gotten everything it needs and cleans up its 
   the cursor's resources.
  </para>
  <para>
   If, for some reason, you need a cursor to hang around for a long time, you 
   can prevent the database from cleaning it up by using this method.  However,
   if you make a cursor immortal, you need to iterate through all of its results
   (or at least until <function>Cursor::dead</function> returns &true;) or the
   cursor will hang around the database forever, taking up resources.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term>
      <parameter>liveForever</parameter>
     </term>
     <listitem>
      <para>
       If the cursor should be immortal.
      </para>
     </listitem>
    </varlistentry>   
   </variablelist>
  </para>
 </refsect1> 

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;  
  <para>
   Returns this cursor.
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   Throws <classname>MongoCursorException</classname> if this cursor has started iterating.
  </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
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
-->