[CDRIVER-3166] Clarify requirements around returning clients to a pool before destroying the pool Created: 03/Jun/19  Updated: 28/Oct/23  Resolved: 04/Feb/20

Status: Closed
Project: C Driver
Component/s: docs
Affects Version/s: None
Fix Version/s: 1.17.0-beta, 1.17.0

Type: Task Priority: Major - P3
Reporter: Kaitlin Mahar Assignee: Kevin Albertson
Resolution: Fixed Votes: 0
Labels: neweng
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

Per recent conversation with jmikola in #mongoc, it's unclear what happens if you don't return all the mongoc_client_t s checked out from a pool before you call mongoc_client_pool_destroy on the pool. 

From my limited testing, it appears that the pool will be destroyed without complaint and attempting to use any still-checked out clients will lead to a server selection error.

If it's required that all clients are returned to the pool before it's destroyed, this should be documented.

Alternatively, maybe it's acceptable for the user to just manually destroy a still-checked out client with mongoc_client_destroy if they discover this occurred. 

Either way it would be helpful for the documentation to clarify this. 



 Comments   
Comment by Githook User [ 04/Feb/20 ]

Author:

{'username': 'kevinAlbs', 'name': 'Kevin Albertson', 'email': 'kevin.albertson@mongodb.com'}

Message: CDRIVER-3166 doc pool/client push/destroy
Branch: master
https://github.com/mongodb/mongo-c-driver/commit/7e801593f2bcf0b26178e3d775be295c612e110f

Comment by Kevin Albertson [ 31/Jan/20 ]

If the parent mongoc_client_pool_t is destroyed, you cannot call mongoc_client_destroy on a mongoc_client_t. The shared topology object is destroyed in mongoc_client_pool_t, and calling mongo_client_destroy accesses that topology object here:
https://github.com/mongodb/mongo-c-driver/blob/1.16.0/src/libmongoc/src/mongoc/mongoc-client.c/#L1127
(Testing with ASAN revelealed this through a use-after-free).

It technically seems ok to call mongoc_client_destroy on a client prior to the pool being destroyed, but we already have explicit documentation about handling multi-threaded clients. The Object Lifecycle page says:

A program that uses libmongoc from multiple threads should create a mongoc_client_pool_t with mongoc_client_pool_new(). Each thread acquires a mongoc_client_t from the pool with mongoc_client_pool_pop() and returns it with mongoc_client_pool_push() when the thread is finished using it. To destroy the pool, first return all clients, then call mongoc_client_pool_destroy().

So I think we should reiterate that documentation in the relevant pool/client functions.

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