From e7dbde68a1ab13d08c81251818131fe8affef90e Mon Sep 17 00:00:00 2001 From: Hannes Magnusson Date: Wed, 28 Nov 2012 20:18:45 +0000 Subject: [PATCH] More WriteConcern updates git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@328544 c90b9560-bf6c-de11-be94-00142212c4b1 --- .../mongo/mongocollection/batchinsert.xml | 11 ++++---- reference/mongo/mongocollection/distinct.xml | 2 +- .../mongo/mongocollection/ensureindex.xml | 4 +-- reference/mongo/mongocollection/save.xml | 6 ++-- reference/mongo/tutorial.xml | 28 ++++++++----------- reference/mongo/writeconcerns.xml | 4 +-- 6 files changed, 26 insertions(+), 29 deletions(-) diff --git a/reference/mongo/mongocollection/batchinsert.xml b/reference/mongo/mongocollection/batchinsert.xml index 025e226546..c1b3b21b29 100644 --- a/reference/mongo/mongocollection/batchinsert.xml +++ b/reference/mongo/mongocollection/batchinsert.xml @@ -67,20 +67,21 @@ &reftitle.returnvalues; - If "safe" is set, returns an associative array with the status of the inserts - ("ok") and any error that may have occured ("err"). Otherwise, returns - &true; if the batch insert was successfully sent, &false; otherwise. + If the w parameter is set to acknowledge the write, + returns an associative array with the status of the inserts ("ok") and any + error that may have occured ("err"). Otherwise, returns &true; if the + batch insert was successfully sent, &false; otherwise. &reftitle.errors; - Throws MongoCursorException if the "safe" option is + Throws MongoCursorException if the "w" option is set and the insert fails. - Throws MongoCursorTimeoutException if the "safe" + Throws MongoCursorTimeoutException if the "w" option is set to a value greater than one and the database cannot replicate the operation in MongoCollection::$wtimeout milliseconds. diff --git a/reference/mongo/mongocollection/distinct.xml b/reference/mongo/mongocollection/distinct.xml index 2a3ce59ab1..82f96380d9 100644 --- a/reference/mongo/mongocollection/distinct.xml +++ b/reference/mongo/mongocollection/distinct.xml @@ -106,7 +106,7 @@ array(2) { insert(array("user" => array("points" => 25))); $c->insert(array("user" => array("points" => 31))); -$c->insert(array("user" => array("points" => 25)), array("safe" => true)); +$c->insert(array("user" => array("points" => 25))); $retval = $c->distinct("user.points"); var_dump($retval); diff --git a/reference/mongo/mongocollection/ensureindex.xml b/reference/mongo/mongocollection/ensureindex.xml index c348fdc79d..72f6ff992d 100644 --- a/reference/mongo/mongocollection/ensureindex.xml +++ b/reference/mongo/mongocollection/ensureindex.xml @@ -216,11 +216,11 @@ 128 bytes. (Version 1.0.11+) - Throws MongoCursorException if the "safe" option is + Throws MongoCursorException if the "w" option is set and the index creation fails. - Throws MongoCursorTimeoutException if the "safe" + Throws MongoCursorTimeoutException if the "w" option is set and the operation takes longer than MongoCursor::$timeout milliseconds to complete. This does not kill the operation on the server, it is a client-side timeout. diff --git a/reference/mongo/mongocollection/save.xml b/reference/mongo/mongocollection/save.xml index 1b72df8451..ebd80bd9a9 100644 --- a/reference/mongo/mongocollection/save.xml +++ b/reference/mongo/mongocollection/save.xml @@ -57,7 +57,7 @@ &reftitle.returnvalues; - If safe was set, returns an array containing the status of the save. + If w was set, returns an array containing the status of the save. Otherwise, returns a boolean representing if the array was not empty (an empty array will not be inserted). @@ -66,11 +66,11 @@ &reftitle.errors; - Throws MongoCursorException if the "safe" option is + Throws MongoCursorException if the "w" option is set and the save fails. - Throws MongoCursorTimeoutException if the "safe" + Throws MongoCursorTimeoutException if the "w" option is set and the operation takes longer than MongoCursor::$timeout milliseconds to complete. This does not kill the operation on the server, it is a client-side timeout. diff --git a/reference/mongo/tutorial.xml b/reference/mongo/tutorial.xml index 36e2d86663..889c2c3531 100644 --- a/reference/mongo/tutorial.xml +++ b/reference/mongo/tutorial.xml @@ -291,26 +291,24 @@ array(6) { foo->insert(array("_id" => 1), array("w" => 1)); +$db->foo->insert(array("_id" => 1)); // this will throw an exception -$db->foo->insert(array("_id" => 1), array("w" => 1)); +$db->foo->insert(array("_id" => 1)); // this is fine, as it is a different collection -$db->bar->insert(array("_id" => 1), array("w" => 1)); +$db->bar->insert(array("_id" => 1)); ?> ]]> - Note that these inserts pass a second array: - array("safe" => true). This second field specifies - options for the insert. By default, the driver does not wait for a database - response for writes, so the driver would not catch the the - _id. As we specify that this is a "safe" write, the - driver will wait for a database response and see that the write did not go - through. In general, all writes should use the "safe" option (it is omitted - in previous examples for simplicity). + By default the driver will ensure the servers has acknowledged the write + before returning. You can optionally turn this behaviour off by passing + array("w" => 0) as the second argument - + array("w" => 1). meaning the driver should not wait + for the database to acknowledge the writes, so the driver would not throw + the duplicate _id exception.
See Also @@ -322,11 +320,9 @@ $db->bar->insert(array("_id" => 1), array("w" => 1)); MongoId goes into more detail on unique ids. - The writes section covers safe - writes in more depth, as do the writing functions such as - MongoCollection::insert, - MongoCollection::update, and - MongoCollection::remove. + The writes section covers + writes in more depth, and the + chapter goes into details of the various Write Concern options.
diff --git a/reference/mongo/writeconcerns.xml b/reference/mongo/writeconcerns.xml index e5f2d1fc59..90a671f69e 100644 --- a/reference/mongo/writeconcerns.xml +++ b/reference/mongo/writeconcerns.xml @@ -117,9 +117,9 @@ to a system collection). - While developing, you should always use safe writes (to protect against + While developing, you should always use acknowledged writes (to protect against inadvertent mistakes, such as syntax errors, invalid operators, duplicate key errors and so on). In - production, unsafe writes can be used for "unimportant" data. Unimportant + production, unacknowledged writes can be used for "unimportant" data. Unimportant data varies on application, but it's generally automatically (instead of user generated) data, such as click tracking or GPS locations, where you can get thousands of records per second.