[CDRIVER-1527] Add mongoc_client_[read|write|read_write]_command_with_opts Created: 07/Sep/16 Updated: 15/Nov/17 Resolved: 20/Oct/16 |
|
| Status: | Closed |
| Project: | C Driver |
| Component/s: | libmongoc |
| Affects Version/s: | None |
| Fix Version/s: | 1.5.0 |
| Type: | New Feature | Priority: | Major - P3 |
| Reporter: | A. Jesse Jiryu Davis | Assignee: | Backlog - C Driver Team |
| Resolution: | Done | Votes: | 0 |
| Labels: | None | ||
| Remaining Estimate: | Not Specified | ||
| Time Spent: | Not Specified | ||
| Original Estimate: | Not Specified | ||
| Issue Links: |
|
||||||||||||||||||||||||||||||||||||||||
| Epic Link: | Flexible opts | ||||||||||||||||||||||||||||||||||||||||
| Description |
|
*Update*: the API proposed below was not what we implemented. See the first linked commit for an overview of the actual API. Currently we have mongoc_client_command and mongoc_client_command_simple (and equivalents for database and collection). These functions are "generic command methods" and follow driver specs that require they do no special handling of writeConcern, readConcern, or collation. They don't obey the read preference set on the client, database, or collection object. They don't parse writeConcernError from the server reply. This matches various specs that say things like:
And in the Server Selection Spec:
The relevant specs are Read and Write Concern, Collation, and Server Selection. HLL drivers built on the C Driver can take advantage of our implementation of driver specs when the HLL drivers call our command-specific helper functions. E.g., when the PHP driver calls mongoc_collection_aggregate_with_opts ( Implementing this special logic in the C Driver gives us two benefits: it consolidates logic in the C Driver so it need not be reimplemented in HLL drivers, and it executes the logic after selecting a server and verifying we have an open connection to it, which eliminates all race conditions during server upgrades. However, to keep taking advantage of these two benefits for all future commands and features, we have to keep adding helper functions with names like mongoc_client_do_new_command_with_opts. I propose a function that can execute any command, but applies special rules for writeConcern, readConcern, and collation, and all future options with special behavior:
We'll also add equivalents at the database and collection level: mongoc_database_command_with_opts and mongoc_collection_command_with_opts. Each of these functions:
In the future this will be our "porcelain" command helper for future specs that require special handling of options. mongoc_client_command_simple and other generic command functions remain "plumbing" with no special handling. |
| Comments |
| Comment by Githook User [ 22/Oct/16 ] |
|
Author: {u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}Message: |
| Comment by Githook User [ 20/Oct/16 ] |
|
Author: {u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}Message: |
| Comment by Githook User [ 20/Oct/16 ] |
|
Author: {u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}Message: |
| Comment by Githook User [ 19/Oct/16 ] |
|
Author: {u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}Message: |
| Comment by A. Jesse Jiryu Davis [ 18/Oct/16 ] |
|
I hadn't been thinking about cursor commands, but that's a good point. I suppose that's an intended use case: I always forget that the PHP driver let users select servers and run operations in distinct steps. We have to support that: |
| Comment by Jeremy Mikola [ 17/Oct/16 ] |
|
Are the new "with_opts" functions (i.e. read, read_write, and write) intended to be used for commands that return a cursor? I realize that they return a single result document, but I found no examples for using these in conjunction with something like aggregation or listCollections. Perhaps the PR should include an example using mongoc_cursor_new_from_command_reply(). Second question: will these new functions allow consumers to specify their own hint for server selection, or does this API require libmongoc to perform internal server selection? PHPC and HHVM won't be able to use this API without a configurable hint, since we already provide APIs for executing commands on pre-selected servers. |
| Comment by A. Jesse Jiryu Davis [ 29/Sep/16 ] |
|
After re-reading |