From 172e7cec9a3dff032e1e53529ba3f17e7fb30735 Mon Sep 17 00:00:00 2001 From: Kristina Chodorow Date: Tue, 16 Aug 2011 20:17:25 +0000 Subject: [PATCH] added more examples for cursor exceptions git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@315036 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/mongo/mongocursorexception.xml | 177 ++++++++++++++++++----- 1 file changed, 140 insertions(+), 37 deletions(-) diff --git a/reference/mongo/mongocursorexception.xml b/reference/mongo/mongocursorexception.xml index 4f448133fb..a32e41408b 100644 --- a/reference/mongo/mongocursorexception.xml +++ b/reference/mongo/mongocursorexception.xml @@ -12,14 +12,52 @@
&reftitle.intro; - Caused by accessing a cursor incorrectly or a error receiving a reply. + Caused by accessing a cursor incorrectly or a error receiving a reply. Note + that this can be thrown by any database request that receives a reply, not + just queries. Writes, commands, and any other operation that sends + information to the database and waits for a response can throw a + MongoCursorException. The only exception is + new Mongo() (creating a new connection), which will only + throw MongoConnectionExceptions. - If there is an error receiving a reply, there will be a more - specific error message to help diagnose the problem. As it is a bit - programmatically awkward to parse an exception message, there is also an - error code associated with each cause of the exception. + This returns a specific error message to help diagnose the problem and a + numeric error code associated with the cause of the exception. + + + + For example, suppose you tried to insert two documents with the same _id: + +insert(array("_id" => 1), array("safe" => true)); + $collection->insert(array("_id" => 1), array("safe" => true)); +} +catch (MongoCursorException $e) { + echo "error message: ".$e->getMessage()."\n"; + echo "error code: ".$e->getCode()."\n"; +} + +?> +]]> + + This would produce output like: + + + + Note that the MongoDB error code (11000) is used for the PHP error code. The + PHP driver uses the "native" error code wherever possible. + + + + The following is a list of common errors, codes, and causes. Exact errors + are in italics, errors where the message can vary are described in obliques. @@ -34,6 +72,33 @@ You are calling a method that sets up the query after executing the query. Reset the cursor and try again. + + An example: + +find(); + var_dump($cursor->getNext()); + + // getNext() queried the database, it's too late to set a limit + $cursor->limit(1); +} +catch (MongoCursorException $e) { + echo "error message: ".$e->getMessage()."\n"; + echo "error code: ".$e->getCode()."\n"; +} + +// this will work, though: +$cursor->getNext(); +$cursor->reset(); +$cursor->limit(1); + +?> +]]> + + @@ -44,7 +109,7 @@ Code: 1 - Could not send the query to the database. Make sure the database is + Could not send the query to the database. Make sure the database is still up and the network is okay. @@ -59,19 +124,36 @@ The driver was trying to fetch more results from the database, but the database did not have a record of the query. This usually means that the - cursor timed out on the server side: after a few minutes of inactivity, - the database will kill a cursor (see + cursor timed out on the server side: after a few minutes of inactivity, + the database will kill a cursor (see MongoCursor::immortal for information on preventing this). - + + An example: + + - - Couldn't get response header. - - - Code: 4 +try { + $cursor = $collection->find(); + $cursor->getNext(); + + // sleep for 15 minutes + sleep(60*15); + + while ($cursor->hasNext()) { + $cursor->getNext(); + } +} +catch (MongoCursorException $e) { + echo "error message: ".$e->getMessage()."\n"; + echo "error code: ".$e->getCode()."\n"; +} + +?> +]]> + @@ -83,8 +165,8 @@ Code: 3 - This may indicate you are out of hard driver space or some other - extraordinary circumstance. + This may indicate you are out of RAM or some other extraordinary + circumstance. @@ -96,9 +178,8 @@ Code: 4 - The driver could not fetch a reply header from the database, so it gave - up. Check if the database is still up and the network is connected and - try the query again. + A common error if the database or network goes down. This means that the + driver couldn't get a response from the connection. @@ -110,24 +191,22 @@ Code: 5 - This may not even be an error, for example, the database command - "shutdown" returns no response. However, if you were expecting a + This may not even be an error, for example, the database command + "shutdown" returns no response. However, if you were expecting a response, this means the database didn't give one. - bad response length: %d, max: %d, did the db assert? + bad response length: %d, did the db assert? Code: 6 - This means that the database said that its response was greater than 4Mb - or less than 0. Generally, a number greater than 5Mb should be reported - to the developers as a potential database bug (max response length is - 4Mb). A response of less than 0 often means a database assertion occured. + This means that the database said that its response was less than 0. This + error probably indicates a network error or database corruption. @@ -139,7 +218,7 @@ Code: 7 - Highly unusual. Occurs if the database response started out correctly, + Highly unusual. Occurs if the database response started out correctly, but broke off in the middle. Probably indicates a network problem. @@ -152,7 +231,7 @@ Code: 8 - Highly unusual. Occurs if the database response started out correctly, + Highly unusual. Occurs if the database response started out correctly, but broke off in the middle. Probably indicates a network problem. @@ -177,7 +256,7 @@ Code: 10 - The socket was closed or encountered an error. The driver should + The socket was closed or encountered an error. The driver should automatically reconnect (if possible) on the next operation. @@ -190,8 +269,8 @@ Code: 11 - The driver saves any database responses it cannot immediately match with a - request. This exception occurs if the driver has already passed your + The driver saves any database responses it cannot immediately match with a + request. This exception occurs if the driver has already passed your request's response and cannot find your response in its cache. @@ -204,7 +283,7 @@ WSA error getting database response: errstr - "errstr" is an io error reported directly from the C socket + "errstr" is an io error reported directly from the C socket subsystem. On Windows, the error message is prefixed with "WSA". @@ -232,6 +311,29 @@ C socket error on send. + + + + max number of retries exhausted, couldn't send query + + + Code: 19 + + + The driver will automatically retry "plain" queries (not commands) a + couple of times if the first attempt failed for certain reasons. This is + to cause fewer exceptions during replica set failover (although you will + probably still have to deal with some) and gloss over transient network + issues. + + + This can also be caused by the driver not being able to reconnect at all + to the database (if, for example, the database is unreachable). + + + Version 1.2.2+. + +
@@ -239,7 +341,8 @@
Errors passed through by the database - Database errors should always trigger MongoCursorExceptions on queries. + Database errors should always trigger + MongoCursorExceptions on queries. Error messages and codes are sent directly from the database and you should be able to see matching errors in the database log. @@ -269,9 +372,9 @@ Codes: 10107, 13435, and 10058 - Not master errors, piped through by the database. Each of these will + Not master errors, piped through by the database. Each of these will cause the driver to disconnect and attempt to find a new master. The - actual error you get on failover may not be a "not master" error, + actual error you get on failover may not be a "not master" error, depending on when the change in master occurs. @@ -295,7 +398,7 @@ - +