1MONGOC_CONNECTION_POOLING(3)       libmongoc      MONGOC_CONNECTION_POOLING(3)
2
3
4
5The  MongoDB  C  driver  has two connection modes: single-threaded and pooled.
6Single-threaded mode is optimized for embedding the  driver  within  languages
7like  PHP. Multi-threaded programs should use pooled mode: this mode minimizes
8the total connection count, and in pooled mode background threads monitor  the
9MongoDB server topology, so the program need not block to scan it.
10

SINGLE MODE

12       In single mode, your program creates a mongoc_client_t directly:
13
14          mongoc_client_t *client = mongoc_client_new (
15             "mongodb://hostA,hostB/?replicaSet=my_rs");
16
17       The  client  connects  on  demand when your program first uses it for a
18       MongoDB operation. Using a non-blocking socket per server, it begins  a
19       check  on  each  server concurrently, and uses the asynchronous poll or
20       select function to receive events from the sockets, until all have  re‐
21       sponded  or  timed  out. Put another way, in single-threaded mode the C
22       Driver fans out to begin all checks concurrently, then fans in once all
23       checks have completed or timed out. Once the scan completes, the client
24       executes your program's operation and returns.
25
26       In single mode, the client re-scans the server  topology  roughly  once
27       per  minute. If more than a minute has elapsed since the previous scan,
28       the next operation on the client will block while the client  completes
29       its  scan.  This  interval is configurable with heartbeatFrequencyMS in
30       the connection string. (See mongoc_uri_t.)
31
32       A single client opens one connection per server in your topology: these
33       connections are used both for scanning the topology and performing nor‐
34       mal operations.
35

POOLED MODE

37       To activate pooled mode, create a mongoc_client_pool_t:
38
39          mongoc_uri_t *uri = mongoc_uri_new (
40             "mongodb://hostA,hostB/?replicaSet=my_rs");
41
42          mongoc_client_pool_t *pool = mongoc_client_pool_new (uri);
43
44       When  your  program  first  calls  mongoc_client_pool_pop(),  the  pool
45       launches monitoring threads in the background. Monitoring threads inde‐
46       pendently connect to all servers in the connection string. As  monitor‐
47       ing  threads  receive hello responses from the servers, they update the
48       shared view of the server topology. Additional monitoring  threads  and
49       connections  are  created  as  new  servers  are discovered. Monitoring
50       threads are terminated when servers are removed from the shared view of
51       the server topology.
52
53       Each  thread  that  executes MongoDB operations must check out a client
54       from the pool:
55
56          mongoc_client_t *client = mongoc_client_pool_pop (pool);
57
58          /* use the client for operations ... */
59
60          mongoc_client_pool_push (pool, client);
61
62       The   mongoc_client_t   object   is   not   thread-safe,    only    the
63       mongoc_client_pool_t is.
64
65       When  the  driver  is in pooled mode, your program's operations are un‐
66       blocked as soon as monitoring discovers a usable server.  For  example,
67       if  a  thread  in your program is waiting to execute an "insert" on the
68       primary, it is unblocked as soon as the primary is  discovered,  rather
69       than waiting for all secondaries to be checked as well.
70
71       The  pool  opens  one  connection  per  server for monitoring, and each
72       client opens its own connection to each server it uses for  application
73       operations. Background monitoring threads re-scan servers independently
74       roughly every 10 seconds. This interval is configurable with heartbeat‐
75       FrequencyMS in the connection string. (See mongoc_uri_t.)
76
77       The  connection string can also specify waitQueueTimeoutMS to limit the
78       time that mongoc_client_pool_pop() will wait  for  a  client  from  the
79       pool.  (See mongoc_uri_t.)  If waitQueueTimeoutMS is specified, then it
80       is necessary to confirm that a client was actually returned:
81
82          mongoc_uri_t *uri = mongoc_uri_new (
83             "mongodb://hostA,hostB/?replicaSet=my_rs&waitQueueTimeoutMS=1000");
84
85          mongoc_client_pool_t *pool = mongoc_client_pool_new (uri);
86
87          mongoc_client_t *client = mongoc_client_pool_pop (pool);
88
89          if (client) {
90             /* use the client for operations ... */
91
92             mongoc_client_pool_push (pool, client);
93          } else {
94             /* take appropriate action for a timeout */
95          }
96
97       See Connection Pool Options to configure pool size  and  behavior,  and
98       see  mongoc_client_pool_t  for  an extended example of a multi-threaded
99       program that uses the driver in pooled mode.
100

AUTHOR

102       MongoDB, Inc
103

105       2017-present, MongoDB, Inc
106
107
108
109
1101.25.1                           Nov 08, 2023     MONGOC_CONNECTION_POOLING(3)
Impressum