[CXX-994] Fix missing or misleading docs about pools, thread/fork safety and background monitoring Created: 17/Aug/16  Updated: 21/Aug/17  Resolved: 19/Apr/17

Status: Closed
Project: C++ Driver
Component/s: Documentation
Affects Version/s: None
Fix Version/s: 3.2.0-rc0

Type: Bug Priority: Minor - P4
Reporter: David Golden Assignee: Samuel Rossi (Inactive)
Resolution: Done Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Related
related to CXX-995 Add mongocxx::pool examples Closed
related to CXX-967 Document how connection pooling works... Closed

 Description   

Pool docs imply that single clients have a background monitoring thread, but this is incorrect.

More generally, thread safety and monitoring behaviors are not prominently documented:

  • mongocxx::client – not thread-safe and uses the single-threaded monitoring algorithm (stop the world every 60 seconds to scan)
  • mongocxx::pool – thread-safe and uses a background thread per server to monitor every 10 seconds

We should also document Server Discovery and Monitoring and Server Selection options configurable via the URI. See mongoc_uri_t docs for an example.



 Comments   
Comment by Githook User [ 19/Apr/17 ]

Author:

{u'username': u'saghm', u'name': u'Saghm Rossi', u'email': u'saghmrossi@gmail.com'}

Message: CXX-994 Missing or misleading docs about pools, thread/fork safety and background monitoring
Branch: master
https://github.com/mongodb/mongo-cxx-driver/commit/2ad0aa4f72f77e95c91ea9c5a95571148e53fbcf

Comment by David Golden [ 18/Apr/17 ]

On fork, the client's sockets are duplicated. So firing queries from the parent and child at the same time will interleave on the wire, causing havoc. And if I understand CDRIVER-2049, the socket is only properly shut down if destroyed in its original PID, so I think "don't reuse a client across a fork" is the safe guidance.

Comment by Samuel Rossi (Inactive) [ 18/Apr/17 ]

What's the exact reason that creating a standalone client (i.e. not from a pool) is unsafe? Both of the links above about forking focus on the pitfalls of forking and multithreading in the same program, but from what I understand, a standalone client is single-threaded.

Comment by David Golden [ 18/Apr/17 ]

Also see related questions in http://api.mongodb.com/python/current/faq.html#is-pymongo-fork-safe for possibly useful verbiage.

Comment by David Golden [ 18/Apr/17 ]

On forking, read this and include a link to it: http://www.linuxprogrammingblog.com/threads-and-fork-think-twice-before-using-them

Once a pool is created, definitely don't fork because a pool creates threads. If running single-threaded with just client, don't use a client object after the fork; create a new client instead.

Comment by David Golden [ 18/Apr/17 ]

This is my take on what we need for this ticket:

  • Create a "connection pools" docs page (similar to the thread safety page and sorting before it)
    • Describe the benefits of a pooled client and recommend as the default mode even for "single-threaded" applications so users benefit from background monitoring (so their app doesn't stall every 60 seconds)
    • Describe restrictions on use of a pooled client (with link to thread safety page)
    • Describe configuration options available for the URI (e.g. pool size, etc.) – possibly copy from the libmongoc docs
    • Describe (with link to example) how to set up a pooled client
  • Update the thread safety page
    • Revise so that it clearly applies both to standalone clients and clients from a pool
    • Update the title (but not the link URL) to "Thread and fork safety"
    • Add a small section about fork safety – that client/pool can't be used across a fork.
  • Update configuration docs
    • Include a small section about configuring a pooled client and link to the new connection pools page
  • Update doxygen docs for pool and client
    • Include a synopsis of and links to connection pool and/or thread safety docs pages as appropriate
    • Ensure rest of the docs are consistent with respect to the content of those pages
    • Recommend pool over standalone client for all production work (for background monitoring)
Comment by David Golden [ 05/Oct/16 ]

We need to address fork safety as well.

Comment by David Golden [ 29/Aug/16 ]

Clarification: mongocxx::pool gives access to individual client objects; those any any cursors, etc. derived from them must only be used by a single thread.

Comment by David Golden [ 17/Aug/16 ]

Generally speaking, anyone who can use threads should use mongocxx::pool with a replica set, even if their app itself isn't multi-threaded. We should make that very obvious in the docs for mongocxx::client. And possibly, we should switch all the mongocxx examples to use mongocxx::pool and acquire a client from it.

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