Skip to content

Commit 3e34af3

Browse files
ajdavisajdavis
committed
CDRIVER-1527 new command funcs with bson_t opts
1 parent f306c1b commit 3e34af3

File tree

51 files changed

+1815
-157
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

51 files changed

+1815
-157
lines changed

‎CMakeLists.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -528,6 +528,7 @@ mongoc_add_example(
528528
example-sdam-monitoring TRUE
529529
${SOURCE_DIR}/examples/example-sdam-monitoring.c)
530530
mongoc_add_example(example-client TRUE ${SOURCE_DIR}/examples/example-client.c)
531+
mongoc_add_example(example-command-with-opts TRUE ${SOURCE_DIR}/examples/example-command-with-opts.c)
531532
mongoc_add_example(example-scram TRUE ${SOURCE_DIR}/examples/example-scram.c)
532533
mongoc_add_example(mongoc-dump TRUE ${SOURCE_DIR}/examples/mongoc-dump.c)
533534
mongoc_add_example(mongoc-ping TRUE ${SOURCE_DIR}/examples/mongoc-ping.c)

‎NEWS

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,26 @@ New features and bug fixes:
1717
* Additional features for Application Performance Monitoring:
1818
* mongoc_topology_description_has_writable_server
1919
* mongoc_topology_description_has_readable_server
20+
* New command functions accept flexible options as a BSON document:
21+
* mongoc_client_read_command_with_opts
22+
* mongoc_client_write_command_with_opts
23+
* mongoc_client_read_write_command_with_opts
24+
* mongoc_database_read_command_with_opts
25+
* mongoc_database_write_command_with_opts
26+
* mongoc_database_read_write_command_with_opts
27+
* mongoc_collection_read_command_with_opts
28+
* mongoc_collection_write_command_with_opts
29+
* mongoc_collection_read_write_command_with_opts
30+
* New helper function to include read concern in one of the above function's
31+
options parameter: mongoc_read_concern_append.
32+
* mongoc_client_command no longer applies the client's read preference and
33+
read concern by default. Same change for mongoc_database_command and
34+
mongoc_collection_command.
35+
* mongoc_collection_count_with_opts now applies the collection's read
36+
preference if no read preference is provided
37+
* mongoc_collection_create_index and mongoc_collection_drop_index now applies the collection's write concern.
38+
* mongoc_collection_create_index_with_opts now applies the collection's
39+
write concern if none is specified in "opts"
2040
* connectTimeoutMS timer now begins after DNS resolution, and resets
2141
for each interface attempted (e.g., if the driver first tries IPv6,
2242
then IPv4).

‎build/generate-future-functions.py

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,7 @@
8484
typedef("mongoc_server_description_ptr", "mongoc_server_description_t *"),
8585
typedef("mongoc_ss_optype_t", None),
8686
typedef("mongoc_topology_ptr", "mongoc_topology_t *"),
87+
typedef("mongoc_write_concern_ptr", "mongoc_write_concern_t *"),
8788

8889
# Const libmongoc.
8990
typedef("const_mongoc_find_and_modify_opts_ptr", "const mongoc_find_and_modify_opts_t *"),
@@ -117,6 +118,35 @@
117118
param("bson_ptr", "reply"),
118119
param("bson_error_ptr", "error")]),
119120

121+
future_function("bool",
122+
"mongoc_client_read_command_with_opts",
123+
[param("mongoc_client_ptr", "client"),
124+
param("const_char_ptr", "db_name"),
125+
param("const_bson_ptr", "command"),
126+
param("const_mongoc_read_prefs_ptr", "read_prefs"),
127+
param("const_bson_ptr", "opts"),
128+
param("bson_ptr", "reply"),
129+
param("bson_error_ptr", "error")]),
130+
131+
future_function("bool",
132+
"mongoc_client_write_command_with_opts",
133+
[param("mongoc_client_ptr", "client"),
134+
param("const_char_ptr", "db_name"),
135+
param("const_bson_ptr", "command"),
136+
param("const_bson_ptr", "opts"),
137+
param("bson_ptr", "reply"),
138+
param("bson_error_ptr", "error")]),
139+
140+
future_function("bool",
141+
"mongoc_client_read_write_command_with_opts",
142+
[param("mongoc_client_ptr", "client"),
143+
param("const_char_ptr", "db_name"),
144+
param("const_bson_ptr", "command"),
145+
param("const_mongoc_read_prefs_ptr", "read_prefs"),
146+
param("const_bson_ptr", "opts"),
147+
param("bson_ptr", "reply"),
148+
param("bson_error_ptr", "error")]),
149+
120150
future_function("void",
121151
"mongoc_client_kill_cursor",
122152
[param("mongoc_client_ptr", "client"),

‎doc/mongoc_client_command.page

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ mongoc_client_command (mongoc_client_t *client,
2626
const bson_t *fields,
2727
const mongoc_read_prefs_t *read_prefs);
2828
]]></code></synopsis>
29-
<p>This function executes a command on the server using the database and command specification provided.</p>
29+
<p>This function executes a command on the server using the database and command specification provided. The client's read preference, read concern, and write concern are not applied to the command.</p>
3030
</section>
3131

3232
<section id="parameters">

‎doc/mongoc_client_command_simple.page

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ mongoc_client_command_simple (mongoc_client_t *client,
2323
bson_t *reply,
2424
bson_error_t *error);
2525
]]></code></synopsis>
26-
<p>This is a simplified interface to <code xref="mongoc_client_command">mongoc_client_command()</code>. It returns the first document from the result cursor into <code>reply</code>.</p>
26+
<p>This is a simplified interface to <code xref="mongoc_client_command">mongoc_client_command()</code>. It returns the first document from the result cursor into <code>reply</code>. The client's read preference, read concern, and write concern are not applied to the command.</p>
2727
<note style="warning"><p><code>reply</code> is always set, and should be released with <code xref="bson:bson_destroy">bson_destroy()</code>.</p></note>
2828
</section>
2929

‎doc/mongoc_client_read_command_with_opts.page

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
<?xml version="1.0"?>
2+
3+
<page xmlns="http://projectmallard.org/1.0/"
4+
type="topic"
5+
style="function"
6+
xmlns:api="http://projectmallard.org/experimental/api/"
7+
xmlns:ui="http://projectmallard.org/experimental/ui/"
8+
id="mongoc_client_read_command_with_opts">
9+
10+
<info>
11+
<link type="guide" xref="mongoc_client_t" group="function"/>
12+
</info>
13+
<title>mongoc_client_read_command_with_opts()</title>
14+
15+
<section id="synopsis">
16+
<title>Synopsis</title>
17+
<synopsis><code mime="text/x-csrc"><![CDATA[bool
18+
mongoc_client_read_command_with_opts (mongoc_client_t *client,
19+
const char *db_name,
20+
const bson_t *command,
21+
const mongoc_read_prefs_t *read_prefs,
22+
const bson_t *opts,
23+
bson_t *reply,
24+
bson_error_t *error);
25+
]]></code></synopsis>
26+
27+
<p>Execute a command on the server, applying logic that is specific to commands that read, and taking the MongoDB server version into account. To send a raw command to the server without any of this logic, use <code xref="mongoc_client_command_simple">mongoc_client_command_simple</code>.</p>
28+
<p>Use this function for commands that read such as "count" or "distinct". Read concern is applied from <code>opts</code> or else from <code>client</code>. (Read concern requires MongoDB 3.2 or later, otherwise an error is returned.) Read preferences are applied from <code>read_prefs</code> or else from <code>client</code>. No write concern is applied.</p>
29+
<p><code>reply</code> is always initialized, and must be freed with <code xref="bson:bson_destroy">bson_destroy()</code>.</p>
30+
</section>
31+
32+
<section id="parameters">
33+
<title>Parameters</title>
34+
<table>
35+
<tr><td><p>client</p></td><td><p>A <code xref="mongoc_client_t">mongoc_client_t</code>.</p></td></tr>
36+
<tr><td><p>db_name</p></td><td><p>The name of the database to run the command on.</p></td></tr>
37+
<tr><td><p>command</p></td><td><p>A <code xref="bson:bson_t">bson_t</code> containing the command specification.</p></td></tr>
38+
<tr><td><p>read_prefs</p></td><td><p>An optional <code xref="mongoc_read_prefs_t">mongoc_read_prefs_t</code>.</p></td></tr>
39+
<tr><td><p>opts</p></td><td><p>A <code xref="bson:bson_t">bson_t</code> containing additional options.</p></td></tr>
40+
<tr><td><p>reply</p></td><td><p>A location for the resulting document.</p></td></tr>
41+
<tr><td><p>error</p></td><td><p>An optional location for a <code xref="errors">bson_error_t</code> or <code>NULL</code>.</p></td></tr>
42+
</table>
43+
</section>
44+
45+
<section id="errors">
46+
<title>Errors</title>
47+
<p>Errors are propagated via the <code>error</code> parameter.</p>
48+
</section>
49+
50+
<section id="return">
51+
<title>Returns</title>
52+
<p><code>true</code> if successful; otherwise <code>false</code> and <code>error</code> is set.</p>
53+
</section>
54+
55+
<section id="example">
56+
<title>Example</title>
57+
<synopsis><code mime="text/x-csrc"><include parse="text" href="../examples/example-command-with-opts.c" xmlns="http://www.w3.org/2001/XInclude" /></code></synopsis>
58+
</section>
59+
60+
</page>

‎doc/mongoc_client_read_write_command_with_opts.page

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
<?xml version="1.0"?>
2+
3+
<page xmlns="http://projectmallard.org/1.0/"
4+
type="topic"
5+
style="function"
6+
xmlns:api="http://projectmallard.org/experimental/api/"
7+
xmlns:ui="http://projectmallard.org/experimental/ui/"
8+
id="mongoc_client_read_write_command_with_opts">
9+
10+
<info>
11+
<link type="guide" xref="mongoc_client_t" group="function"/>
12+
</info>
13+
<title>mongoc_client_read_write_command_with_opts()</title>
14+
15+
<section id="synopsis">
16+
<title>Synopsis</title>
17+
<synopsis><code mime="text/x-csrc"><![CDATA[bool
18+
mongoc_client_read_write_command_with_opts (mongoc_client_t *client,
19+
const char *db_name,
20+
const bson_t *command,
21+
const mongoc_read_prefs_t *read_prefs,
22+
const bson_t *opts,
23+
bson_t *reply,
24+
bson_error_t *error);
25+
]]></code></synopsis>
26+
27+
<p>Execute a command on the server, applying logic for commands that both read and write, and taking the MongoDB server version into account. To send a raw command to the server without any of this logic, use <code xref="mongoc_client_command_simple">mongoc_client_command_simple</code>.</p>
28+
<p>Use this function for commands that both read and write, such as "mapReduce" with an output collection.</p>
29+
<p>Read concern is applied from <code>opts</code> or else from <code>client</code>. (Read concern requires MongoDB 3.2 or later, otherwise an error is returned.) Read preferences are applied from <code>read_prefs</code> or else from <code>client</code>. Write concern is applied from <code>opts</code>, or else from <code>client</code>. The write concern is omitted for MongoDB before 3.2.</p>
30+
<p><code>reply</code> is always initialized, and must be freed with <code xref="bson:bson_destroy">bson_destroy()</code>.</p>
31+
</section>
32+
33+
<section id="parameters">
34+
<title>Parameters</title>
35+
<table>
36+
<tr><td><p>client</p></td><td><p>A <code xref="mongoc_client_t">mongoc_client_t</code>.</p></td></tr>
37+
<tr><td><p>db_name</p></td><td><p>The name of the database to run the command on.</p></td></tr>
38+
<tr><td><p>command</p></td><td><p>A <code xref="bson:bson_t">bson_t</code> containing the command specification.</p></td></tr>
39+
<tr><td><p>read_prefs</p></td><td><p>An optional <code xref="mongoc_read_prefs_t">mongoc_read_prefs_t</code>.</p></td></tr>
40+
<tr><td><p>opts</p></td><td><p>A <code xref="bson:bson_t">bson_t</code> containing additional options.</p></td></tr>
41+
<tr><td><p>reply</p></td><td><p>A location for the resulting document.</p></td></tr>
42+
<tr><td><p>error</p></td><td><p>An optional location for a <code xref="errors">bson_error_t</code> or <code>NULL</code>.</p></td></tr>
43+
</table>
44+
</section>
45+
46+
<section id="errors">
47+
<title>Errors</title>
48+
<p>Errors are propagated via the <code>error</code> parameter.</p>
49+
</section>
50+
51+
<section id="return">
52+
<title>Returns</title>
53+
<p><code>true</code> if successful; otherwise <code>false</code> and <code>error</code> is set.</p>
54+
<p>A write concern timeout or write concern error is considered a failure.</p>
55+
</section>
56+
57+
<section id="example">
58+
<title>Example</title>
59+
<p>See the example code for <code xref="mongoc_client_read_command_with_opts">mongoc_client_read_command_with_opts</code>.</p>
60+
</section>
61+
62+
</page>

‎doc/mongoc_client_write_command_with_opts.page

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
<?xml version="1.0"?>
2+
3+
<page xmlns="http://projectmallard.org/1.0/"
4+
type="topic"
5+
style="function"
6+
xmlns:api="http://projectmallard.org/experimental/api/"
7+
xmlns:ui="http://projectmallard.org/experimental/ui/"
8+
id="mongoc_client_write_command_with_opts">
9+
10+
<info>
11+
<link type="guide" xref="mongoc_client_t" group="function"/>
12+
</info>
13+
<title>mongoc_client_write_command_with_opts()</title>
14+
15+
<section id="synopsis">
16+
<title>Synopsis</title>
17+
<synopsis><code mime="text/x-csrc"><![CDATA[bool
18+
mongoc_client_write_command_with_opts (mongoc_client_t *client,
19+
const char *db_name,
20+
const bson_t *command,
21+
const bson_t *opts,
22+
bson_t *reply,
23+
bson_error_t *error);
24+
]]></code></synopsis>
25+
26+
<p>Execute a command on the server, applying logic that is specific to commands that write, and taking the MongoDB server version into account. To send a raw command to the server without any of this logic, use <code xref="mongoc_client_command_simple">mongoc_client_command_simple</code>.</p>
27+
<p>Use this function for commands that write such as "drop" or "createRole". Write concern is applied from <code>opts</code>, or else from <code>client</code>. The write concern is omitted for MongoDB before 3.2. No read concern or read preferences are applied.</p>
28+
<p><code>reply</code> is always initialized, and must be freed with <code xref="bson:bson_destroy">bson_destroy()</code>.</p>
29+
</section>
30+
31+
<section id="parameters">
32+
<title>Parameters</title>
33+
<table>
34+
<tr><td><p>client</p></td><td><p>A <code xref="mongoc_client_t">mongoc_client_t</code>.</p></td></tr>
35+
<tr><td><p>db_name</p></td><td><p>The name of the database to run the command on.</p></td></tr>
36+
<tr><td><p>command</p></td><td><p>A <code xref="bson:bson_t">bson_t</code> containing the command specification.</p></td></tr>
37+
<tr><td><p>opts</p></td><td><p>A <code xref="bson:bson_t">bson_t</code> containing additional options.</p></td></tr>
38+
<tr><td><p>reply</p></td><td><p>A location for the resulting document.</p></td></tr>
39+
<tr><td><p>error</p></td><td><p>An optional location for a <code xref="errors">bson_error_t</code> or <code>NULL</code>.</p></td></tr>
40+
</table>
41+
</section>
42+
43+
<section id="errors">
44+
<title>Errors</title>
45+
<p>Errors are propagated via the <code>error</code> parameter.</p>
46+
</section>
47+
48+
<section id="return">
49+
<title>Returns</title>
50+
<p><code>true</code> if successful; otherwise <code>false</code> and <code>error</code> is set.</p>
51+
<p>A write concern timeout or write concern error is considered a failure.</p>
52+
</section>
53+
54+
<section id="example">
55+
<title>Example</title>
56+
<p>See the example code for <code xref="mongoc_client_read_command_with_opts">mongoc_client_read_command_with_opts</code>.</p>
57+
</section>
58+
59+
</page>

‎doc/mongoc_collection_command.page

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ BSON_GNUC_WARN_UNUSED_RESULT;
4646
<section id="description">
4747
<title>Description</title>
4848
<p>This function shall execute a command on a collection. This is performed lazily and therefore requires calling <code xref="mongoc_cursor_next">mongoc_cursor_next()</code> on the resulting cursor structure. The cursor should be freed with <code xref="mongoc_cursor_destroy">mongoc_cursor_destroy()</code> when no longer in use.</p>
49+
<p>The collection's read preference, read concern, and write concern are not applied to the command.</p>
4950
</section>
5051

5152
<section id="return">

‎doc/mongoc_collection_command_simple.page

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ mongoc_collection_command_simple (mongoc_collection_t *collection,
3838

3939
<section id="description">
4040
<title>Description</title>
41-
<p>This is a simplified version of <code xref="mongoc_collection_command">mongoc_collection_command()</code> that returns the first result document in <code>reply</code>. The parameter <code>reply</code> is initialized even upon failure to simplify memory management.</p>
41+
<p>This is a simplified version of <code xref="mongoc_collection_command">mongoc_collection_command()</code> that returns the first result document in <code>reply</code>. The collection's read preference, read concern, and write concern are not applied to the command. The parameter <code>reply</code> is initialized even upon failure to simplify memory management.</p>
4242
<p>This function tries to unwrap an embedded error in the command when possible. The unwrapped error will be propagated via the <code>error</code> parameter. Additionally, the result document is set in <code>reply</code>.</p>
4343
</section>
4444

0 commit comments

Comments
 (0)