[CDRIVER-3201] Better clarify socket initialization behavior for single and pool APIs Created: 21/Jun/19  Updated: 31/Mar/22

Status: Backlog
Project: C Driver
Component/s: docs, libmongoc
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Minor - P4
Reporter: Jeremy Mikola Assignee: Unassigned
Resolution: Unresolved Votes: 0
Labels: neweng
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Related

 Description   

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):

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):

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.


Generated at Wed Feb 07 21:17:22 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.