[CDRIVER-1917] Document use of server_id in mongoc_cursor_new_from_command_reply Created: 14/Nov/16  Updated: 05/May/17  Resolved: 05/May/17

Status: Closed
Project: C Driver
Component/s: docs, libmongoc
Affects Version/s: None
Fix Version/s: 1.7.0

Type: Improvement Priority: Major - P3
Reporter: David Golden Assignee: A. Jesse Jiryu Davis
Resolution: Done Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

mongoc_cursor_new_from_command_reply takes a "server_id" parameter. However, HLL wrappers that want to use this command to synthesize a cursor response have no idea what to put for that parameter. I suspect that "0" is acceptable in such a case, but this is not documented.



 Comments   
Comment by Githook User [ 05/May/17 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1917 update mongoc_cursor_new_from_command_reply.rst
Branch: master
https://github.com/mongodb/mongo-c-driver/commit/65d43fbbfde2533df56c709fe470e699b7cc1af8

Comment by A. Jesse Jiryu Davis [ 16/Nov/16 ]

That's safe and correct.

Comment by David Golden [ 15/Nov/16 ]

For my purpose, it would be sufficient to say something like this:

When synthesizing a complete cursor response (i.e. with cursor id 0), set the server_id to 0 as well.

If that is, in fact, a safe and correct thing to do.

Comment by A. Jesse Jiryu Davis [ 15/Nov/16 ]

If you might send getMore commands for this cursor, then server id must be set in order to ensure you send them to the right server. Use it like this:

https://github.com/mongodb/mongo-c-driver/blob/d23e71f533748106486dbe8831e8ad7b33ecb820/tests/test-mongoc-cursor.c#L657-L657

Except this test uses some private APIs, so the full public API usage goes like this:

Get a mongoc_server_description_t using mongoc_client_select_server, get its id with mongoc_server_description_id. Pass that as "serverId" in "opts" to mongoc_client_read_command_with_opts or a similar function. When you get the reply, pass the reply and server id to mongoc_cursor_new_from_command_reply.

Do we need to document this? I've been resisting it, since the whole server id API is designed for PHP's odd habit of selecting a server as a distinct step before executing operations on the server. I'd rather guide regular C programmers away from server ids and away from mongoc_cursor_new_from_command_reply.

Generated at Wed Feb 07 21:13:36 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.