In this mongodb-user thread, I ended up clarifying our documentation to advise a user on how the existing connection pool API can be primed with clients.
Reading Connection Pooling, I realized that the we only fully discuss socket initialization for the single-threaded API. For the multi-threaded (i.e. pool) API, we mention that the first pop initializes monitoring, but we say nothing about application sockets for popped clients being initialized.
Adding examples for priming a connection pool
For the benefit of our users, it'd be good to clarify how popped clients can be initialized. Perhaps a section with a code snippet demonstrating the pool-priming example I provided in the aforementioned mongodb-user thread would be helpful. We might show an example for a basic pop/push just to initialize monitoring for a pool, and a second example to prime the pool with 10 clients (using a ping command).
Noting socket initialization behavior for single/multi-threaded APIs
I think the following docs for the single-threaded API should mention that a client's shared monitoring/application sockets will be initialized on-demand (e.g. after a ping command or the first operation):
- http://mongoc.org/libmongoc/current/mongoc_client_new.html
- http://mongoc.org/libmongoc/current/mongoc_client_new_from_uri.html
For the multi-threaded API, it would be helpful if these pages mentioned some details from the Connection Pooling page. Namely, that monitoring (and its sockets) are initialized on the first pop, and a popped client's application sockets are initialized on-demand (e.g. ping or other operation):
- http://mongoc.org/libmongoc/current/mongoc_client_pool_pop.html
- http://mongoc.org/libmongoc/current/mongoc_client_pool_try_pop.html
- http://mongoc.org/libmongoc/current/mongoc_client_pool_new.html
The top-level mongoc_client_t and mongoc_client_pool_t pages already link to Connection Pooling, so I don't think those require any changes.