1MONGOC_CONNECTION_POOLING(3) libmongoc MONGOC_CONNECTION_POOLING(3)
2
6 mongoc_connection_pooling - Connection Pooling
7 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
16 In single mode, your program creates a mongoc_client_t directly:
17 mongoc_client_t *client = mongoc_client_new (
19 "mongodb://hostA,hostB/?replicaSet=my_rs");
20 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 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 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
41 To activate pooled mode, create a mongoc_client_pool_t:
42 mongoc_uri_t *uri = mongoc_uri_new (
44 "mongodb://hostA,hostB/?replicaSet=my_rs");
45 mongoc_client_pool_t *pool = mongoc_client_pool_new (uri);
47 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 Each thread that executes MongoDB operations must check out a client
57 from the pool:
58 mongoc_client_t *client = mongoc_client_pool_pop (pool);
60 /* use the client for operations ... */
62 mongoc_client_pool_push (pool, client);
64 The mongoc_client_t object is not thread-safe, only the mon‐
66 goc_client_pool_t is.
67 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 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 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
85 MongoDB, Inc
86
88 2017-present, MongoDB, Inc
891.16.2 Feb 25, 2020 MONGOC_CONNECTION_POOLING(3)