[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: |
|
||||
| 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 poolFor 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 APIsI 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. |