1MONGOC_CONNECTION_POOLING(3)   MongoDB C Driver   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  a  background thread monitors 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
25       responded 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 launches
49       a background thread for monitoring. The thread fans out and connects to
50       all  servers in the connection string, using non-blocking sockets and a
51       simple event loop. As it receives ismaster responses from the  servers,
52       it  updates  its view of the server topology. Each time the thread dis‐
53       covers a new server it begins connecting to it, and adds the new socket
54       to the list of non-blocking sockets in the event loop.
55
56       Each  thread  that  executes MongoDB operations must check out a client
57       from the pool:
58
59          mongoc_client_t *client = mongoc_client_pool_pop (pool);
60
61          /* use the client for operations ... */
62
63          mongoc_client_pool_push (pool, client);
64
65       The  mongoc_client_t  object  is  not  thread-safe,   only   the   mon‐
66       goc_client_pool_t is.
67
68       When  the  driver  is  in  pooled  mode,  your program's operations are
69       unblocked as soon as monitoring discovers a usable server. For example,
70       if  a  thread  in your program is waiting to execute an "insert" on the
71       primary, it is unblocked as soon as the primary is  discovered,  rather
72       than waiting for all secondaries to be checked as well.
73
74       The  pool  opens  one  connection  per  server for monitoring, and each
75       client opens its own connection to each server it uses for  application
76       operations.  The background thread re-scans the server topology roughly
77       every 10 seconds. This interval is configurable with  heartbeatFrequen‐
78       cyMS in the connection string. (See mongoc_uri_t.)
79
80       See  connection_pool_options  to  configure pool size and behavior, and
81       see mongoc_client_pool_t for an extended example  of  a  multi-threaded
82       program that uses the driver in pooled mode.
83

AUTHOR

85       MongoDB, Inc
86
88       2017-present, MongoDB, Inc
89
90
91
92
931.14.0                           Feb 22, 2019     MONGOC_CONNECTION_POOLING(3)
Impressum