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