1MONGOC_CONNECTION_POOLING(3)       libmongoc      MONGOC_CONNECTION_POOLING(3)
2
3
4

NAME

6       mongoc_connection_pooling - Connection Pooling
7
8       The  MongoDB  C  driver  has  two connection modes: single-threaded and
9       pooled. Single-threaded mode is  optimized  for  embedding  the  driver
10       within  languages  like  PHP. Multi-threaded programs should use pooled
11       mode: this mode minimizes the total connection  count,  and  in  pooled
12       mode  background  threads  monitor  the MongoDB server topology, so the
13       program need not block to scan it.
14

SINGLE MODE

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

POOLED MODE

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

AUTHOR

106       MongoDB, Inc
107

109       2017-present, MongoDB, Inc
110
111
112
113
1141.24.3                           Aug 17, 2023     MONGOC_CONNECTION_POOLING(3)
Impressum