bionic (3) mongoc_connection_pooling.3.gz

NAME

       mongoc_connection_pooling - Connection Pooling

       The  MongoDB  C  driver  has  two  connection  modes: single-threaded and pooled. Single-threaded mode is
       optimized for embedding the driver within languages like PHP. Multi-threaded programs should  use  pooled
       mode: this mode minimizes the total connection count, and in pooled mode a background thread monitors the
       MongoDB server topology, so the program need not block to scan it.

SINGLE MODE

       In single mode, your program creates a mongoc_client_t directly:

          mongoc_client_t *client = mongoc_client_new (
             "mongodb://hostA,hostB/?replicaSet=my_rs");

       The client connects on demand when  your  program  first  uses  it  for  a  MongoDB  operation.  Using  a
       non-blocking  socket per server, it begins a check on each server concurrently, and uses the asynchronous
       poll or select function to receive events from the sockets, until all have responded or  timed  out.  Put
       another way, in single-threaded mode the C Driver fans out to begin all checks concurrently, then fans in
       once all checks have completed or timed out. Once the scan completes, the client executes your  program's
       operation and returns.

       In  single  mode,  the client re-scans the server topology roughly once per minute. If more than a minute
       has elapsed since the previous scan, the next operation  on  the  client  will  block  while  the  client
       completes  its  scan.  This  interval is configurable with heartbeatFrequencyMS in the connection string.
       (See mongoc_uri_t.)

       A single client opens one connection per server in your topology: these connections  are  used  both  for
       scanning the topology and performing normal operations.

POOLED MODE

       To activate pooled mode, create a mongoc_client_pool_t:

          mongoc_uri_t *uri = mongoc_uri_new (
             "mongodb://hostA,hostB/?replicaSet=my_rs");

          mongoc_client_pool_t *pool = mongoc_client_pool_new (uri);

       When  your  program  first  calls  mongoc_client_pool_pop,  the  pool  launches  a  background thread for
       monitoring. The thread fans out and connects to all servers in the connection string, using  non-blocking
       sockets  and a simple event loop. As it receives ismaster responses from the servers, it updates its view
       of the server topology. Each time the thread discovers a new server it begins connecting to it, and  adds
       the new socket to the list of non-blocking sockets in the event loop.

       Each thread that executes MongoDB operations must check out a client from the pool:

          mongoc_client_t *client = mongoc_client_pool_pop (pool);

          /* use the client for operations ... */

          mongoc_client_pool_push (pool, client);

       The mongoc_client_t object is not thread-safe, only the mongoc_client_pool_t is.

       When  the  driver  is  in  pooled  mode,  your  program's  operations are unblocked as soon as monitoring
       discovers a usable server. For example, if a thread in your program is waiting to execute an "insert"  on
       the  primary,  it  is  unblocked  as  soon  as  the  primary  is  discovered, rather than waiting for all
       secondaries to be checked as well.

       The pool opens one connection per server for monitoring, and each client opens its own connection to each
       server  it  uses  for  application operations. The background thread re-scans the server topology roughly
       every 10 seconds. This interval is configurable with heartbeatFrequencyMS in the connection string.  (See
       mongoc_uri_t.)

       See  connection_pool_options  to  configure  pool  size and behavior, and see mongoc_client_pool_t for an
       extended example of a multi-threaded program that uses the driver in pooled mode.

AUTHOR

       MongoDB, Inc

COPYRIGHT

       2018, MongoDB, Inc