MONGOCURSOR.TIMEOUT(3) 1 MONGOCURSOR.TIMEOUT(3)MongoCursor::timeout - Sets a client-side timeout for this query
SYNOPSIS
public MongoCursor MongoCursor::timeout (int $ms)
DESCRIPTION
A timeout can be set at any time and will affect subsequent queries on the cursor, including fetching more results from the database.
PARAMETERS
o $ms
- The number of milliseconds for the cursor to wait for a response. Use -1 to wait forever. By default, the cursor will wait
$30000 milliseconds (30 seconds).
RETURN VALUES
This cursor.
ERRORS /EXCEPTIONS
Causes methods that fetch results to throw a MongoCursorTimeoutException if the query takes longer than the specified number of millisec-
onds.
EXAMPLES
Example #1
MongoCursor.timeout(3) example
In the following example, the driver will wait forever for the initial database response, and then wait 100ms for subsequent
responses.
<?php
$cursor = $collection->find();
$cursor->timeout(-1);
/* $cursor->hasNext() executes the query. An infinite timeout has been set, so
* the driver will wait as long as necessary for a response.
*/
while ($cursor->hasNext()) {
$cursor->timeout(100);
/* A timeout has now been set, so if the cursor needs to get more results
* from the database, it will only wait 100ms for a response.
*/
try {
print_r($cursor->getNext());
} catch (MongoCursorTimeoutException $e) {
echo "query took too long!";
}
}
?>
NOTES
Warning
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 MongoCursorTimeoutException after a set time. If you need to specify a server-side timeout for a query, con-
sider using MongoCursor::maxTimeMS.
SEE ALSO
MongoCursorInterface::timeout, The socketTimeoutMS option for MongoClient.__construct(3).
PHP Documentation Group MONGOCURSOR.TIMEOUT(3)
Check Out this Related Man Page
MONGOCURSOR(3) 1 MONGOCURSOR(3)The MongoCursor classINTRODUCTION
A cursor is used to iterate through the results of a database query. For example, to query the database and see all results, you could do:
Example #1
MongoCursor basic usage
<?php
$cursor = $collection->find();
var_dump(iterator_to_array($cursor));
?>
You don't generally create cursors using the MongoCursor constructor, you get a new cursor by calling MongoCollection.find(3) (as shown
above).
Suppose that, in the example above, $collection was a 50GB collection. We certainly wouldn't want to load that into memory all at once,
which is what a cursor is for: allowing the client to access the collection in dribs and drabs.
If we have a large result set, we can iterate through it, loading a few megabytes of results into memory at a time. For example, we could
do:
Example #2
Iterating over MongoCursor
<?php
$cursor = $collection->find();
foreach ($cursor as $doc) {
// do something to each document
}
?>
This will go through each document in the collection, loading and garbage collecting documents as needed.
Note that this means that a cursor does not "contain" the database results, it just manages them. Thus, if you print a cursor (with, say,
var_dump(3) or print_r(3)), you'll just get the cursor object, not your documents. To get the documents themselves, you can use one of the
methods shown above.
CURSOR STAGES
A MongoCursor has two "life stages": pre- and post- query. When a cursor is created, it has not yet contacted the database, so it is in
its pre-query state. In this state, the client can further specify what they want the query to do, including adding limits, skips, sorts,
and more advanced options.
When the client attempts to get a result (by calling MongoCursor.next(3), directly or indirectly), the cursor moves into the post-query
stage. At this point, the query has been executed by the database and cannot be modified anymore.
Example #3
Adding options to MongoCursor
<?php
$cursor = $collection->find()->limit(10);
// database has not yet been queried, so more search options can be added
$cursor = $cursor->sort(array("a" => 1));
var_dump($cursor->getNext());
// now database has been queried and more options cannot be added
// so this will throw an exception:
$cursor->skip(4);
?>
CLASS SYNOPSIS
MongoCursor
MongoCursorMongoCursorInterfaceIterator
Static Fields
o static boolean$slaveOkay FALSE
o static integer$timeout30000
Methods
o public MongoCursor MongoCursor::addOption (string $key, mixed $value)
o public MongoCursor MongoCursor::awaitData ([bool $wait = true])
o public MongoCursor MongoCursor::batchSize (int $batchSize)
o public MongoCursor::__construct (MongoClient $connection, string $ns, [array $query = array()], [array $fields = array()])
o public int MongoCursor::count FALSE ([bool $foundOnly])
o public array MongoCursor::current (void )
o public bool MongoCursor::dead (void )
o protected void MongoCursor::doQuery (void )
o public array MongoCursor::explain (void )
o public MongoCursor MongoCursor::fields (array $f)
o public array MongoCursor::getNext (void )
o public array MongoCursor::getReadPreference (void )
o public bool MongoCursor::hasNext (void )
o public MongoCursor MongoCursor::hint (mixed $index)
o public MongoCursor MongoCursor::immortal ([bool $liveForever = true])
o public array MongoCursor::info (void )
o public string|int MongoCursor::key (void )
o public MongoCursor MongoCursor::limit (int $num)
o public MongoCursor MongoCursor::maxTimeMS (int $ms)
o public array MongoCursor::next (void )
o public MongoCursor MongoCursor::partial ([bool $okay = true])
o public void MongoCursor::reset (void )
o public void MongoCursor::rewind (void )
o public MongoCursor MongoCursor::setFlag (int $flag, [bool $set = true])
o public MongoCursor MongoCursor::setReadPreference (string $read_preference, [array $tags])
o public MongoCursor MongoCursor::skip (int $num)
o public MongoCursor MongoCursor::slaveOkay ([bool $okay = true])
o public MongoCursor MongoCursor::snapshot (void )
o public MongoCursor MongoCursor::sort (array $fields)
o public MongoCursor MongoCursor::tailable ([bool $tail = true])
o public MongoCursor MongoCursor::timeout (int $ms)
o public bool MongoCursor::valid (void )
STATIC VARIABLES
o $slaveOkay
- If the query should have the "slaveOkay" flag set, which allows reads on the secondary (secondaries are, by default, just for
backup and not queried). Can be overridden with MongoCursor.slaveOkay(3). This functionality is deprecated. Please use "Read
Preferences" instead.
o $timeout
- Set timeout in milliseconds for all database responses. Use -1 to wait forever. Can be overridden with MongoCursor.timeout(3).
This does not cause the MongoDB server to cancel the operation; it only instructs the driver to stop waiting for a response and
throw a MongoCursorTimeoutException after a set time.
SEE ALSO
MongoDB core docs on cursors.
PHP Documentation Group MONGOCURSOR(3)