<!-- 
RSS generated by JIRA (9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66) at Wed Feb 07 22:01:02 UTC 2024

It is possible to restrict the fields that are returned in this document by specifying the 'field' parameter in your request.
For example, to request only the issue key and summary append 'field=key&field=summary' to the URL of your request.
-->
<rss version="0.92" >
<channel>
    <title>MongoDB Jira</title>
    <link>https://jira.mongodb.org</link>
    <description>This file is an XML representation of an issue</description>
    <language>en-us</language>    <build-info>
        <version>9.7.1</version>
        <build-number>970001</build-number>
        <build-date>13-04-2023</build-date>
    </build-info>


<item>
            <title>[CXX-994] Fix missing or misleading docs about pools, thread/fork safety and background monitoring</title>
                <link>https://jira.mongodb.org/browse/CXX-994</link>
                <project id="11980" key="CXX">C++ Driver</project>
                    <description>&lt;p&gt;Pool docs imply that single clients have a background monitoring thread, but this is incorrect.&lt;/p&gt;

&lt;p&gt;More generally, thread safety and monitoring behaviors are not prominently documented:&lt;/p&gt;

&lt;ul&gt;
	&lt;li&gt;&lt;tt&gt;mongocxx::client&lt;/tt&gt; &#8211; not thread-safe and uses the single-threaded monitoring algorithm (stop the world every 60 seconds to scan)&lt;/li&gt;
	&lt;li&gt;&lt;tt&gt;mongocxx::pool&lt;/tt&gt; &#8211;&#160;thread-safe and uses a background thread per server to monitor every 10 seconds&lt;/li&gt;
&lt;/ul&gt;


&lt;p&gt;We should also document Server Discovery and Monitoring and Server Selection options configurable via the URI.  See &lt;a href=&quot;http://mongoc.org/libmongoc/current/mongoc_uri_t.html&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;mongoc_uri_t&lt;/a&gt; docs for an example.&lt;/p&gt;</description>
                <environment></environment>
        <key id="309613">CXX-994</key>
            <summary>Fix missing or misleading docs about pools, thread/fork safety and background monitoring</summary>
                <type id="1" iconUrl="https://jira.mongodb.org/secure/viewavatar?size=xsmall&amp;avatarId=14703&amp;avatarType=issuetype">Bug</type>
                                            <priority id="4" iconUrl="https://jira.mongodb.org/images/icons/priorities/minor.svg">Minor - P4</priority>
                        <status id="6" iconUrl="https://jira.mongodb.org/images/icons/statuses/closed.png" description="The issue is considered finished, the resolution is correct. Issues which are closed can be reopened.">Closed</status>
                    <statusCategory id="3" key="done" colorName="success"/>
                                    <resolution id="9">Done</resolution>
                                        <assignee username="sam.rossi@mongodb.com">Samuel Rossi</assignee>
                                    <reporter username="david.golden@mongodb.com">David Golden</reporter>
                        <labels>
                    </labels>
                <created>Wed, 17 Aug 2016 14:13:42 +0000</created>
                <updated>Mon, 21 Aug 2017 14:15:58 +0000</updated>
                            <resolved>Wed, 19 Apr 2017 20:22:03 +0000</resolved>
                                                    <fixVersion>3.2.0-rc0</fixVersion>
                                    <component>Documentation</component>
                                        <votes>0</votes>
                                    <watches>3</watches>
                                                                                                                <comments>
                            <comment id="1553034" author="xgen-internal-githook" created="Wed, 19 Apr 2017 20:21:36 +0000"  >&lt;p&gt;Author:&lt;/p&gt;
{u&apos;username&apos;: u&apos;saghm&apos;, u&apos;name&apos;: u&apos;Saghm Rossi&apos;, u&apos;email&apos;: u&apos;saghmrossi@gmail.com&apos;}
&lt;p&gt;Message: &lt;a href=&quot;https://jira.mongodb.org/browse/CXX-994&quot; title=&quot;Fix missing or misleading docs about pools, thread/fork safety and background monitoring&quot; class=&quot;issue-link&quot; data-issue-key=&quot;CXX-994&quot;&gt;&lt;del&gt;CXX-994&lt;/del&gt;&lt;/a&gt; Missing or misleading docs about pools, thread/fork safety and background monitoring&lt;br/&gt;
Branch: master&lt;br/&gt;
&lt;a href=&quot;https://github.com/mongodb/mongo-cxx-driver/commit/2ad0aa4f72f77e95c91ea9c5a95571148e53fbcf&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;https://github.com/mongodb/mongo-cxx-driver/commit/2ad0aa4f72f77e95c91ea9c5a95571148e53fbcf&lt;/a&gt;&lt;/p&gt;</comment>
                            <comment id="1551976" author="david.golden" created="Tue, 18 Apr 2017 20:03:52 +0000"  >&lt;p&gt;On fork, the client&apos;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 &lt;a href=&quot;https://jira.mongodb.org/browse/CDRIVER-2049&quot; title=&quot;Do not shutdown() sockets created by other processes&quot; class=&quot;issue-link&quot; data-issue-key=&quot;CDRIVER-2049&quot;&gt;&lt;del&gt;CDRIVER-2049&lt;/del&gt;&lt;/a&gt;, the socket is only properly shut down if destroyed in its original PID, so I think &quot;don&apos;t reuse a client across a fork&quot; is the safe guidance.&lt;/p&gt;</comment>
                            <comment id="1551951" author="sam.rossi" created="Tue, 18 Apr 2017 19:37:59 +0000"  >&lt;p&gt;What&apos;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.&lt;/p&gt;</comment>
                            <comment id="1551417" author="david.golden" created="Tue, 18 Apr 2017 13:18:10 +0000"  >&lt;p&gt;Also see related questions in &lt;a href=&quot;http://api.mongodb.com/python/current/faq.html#is-pymongo-fork-safe&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;http://api.mongodb.com/python/current/faq.html#is-pymongo-fork-safe&lt;/a&gt; for possibly useful verbiage.&lt;/p&gt;</comment>
                            <comment id="1551415" author="david.golden" created="Tue, 18 Apr 2017 13:14:50 +0000"  >&lt;p&gt;On forking, read this and include a link to it: &lt;a href=&quot;http://www.linuxprogrammingblog.com/threads-and-fork-think-twice-before-using-them&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;http://www.linuxprogrammingblog.com/threads-and-fork-think-twice-before-using-them&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Once a pool is created, definitely don&apos;t fork because a pool creates threads.  If running single-threaded with just client, don&apos;t use a client object after the fork; create a new client instead.&lt;/p&gt;</comment>
                            <comment id="1551149" author="david.golden" created="Tue, 18 Apr 2017 02:51:36 +0000"  >&lt;p&gt;This is my take on what we need for this ticket:&lt;/p&gt;

&lt;ul&gt;
	&lt;li&gt;Create a &quot;connection pools&quot; docs page (similar to the &lt;a href=&quot;https://mongodb.github.io/mongo-cxx-driver/mongocxx-v3/thread-safety/&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;thread safety&lt;/a&gt; page and sorting before it)
	&lt;ul&gt;
		&lt;li&gt;Describe the benefits of a pooled client and recommend as the default mode even for &quot;single-threaded&quot; applications so users benefit from background monitoring (so their app doesn&apos;t stall every 60 seconds)&lt;/li&gt;
		&lt;li&gt;Describe restrictions on use of a pooled client (with link to &lt;a href=&quot;https://mongodb.github.io/mongo-cxx-driver/mongocxx-v3/thread-safety/&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;thread safety&lt;/a&gt; page)&lt;/li&gt;
		&lt;li&gt;Describe configuration options available for the URI (e.g. pool size, etc.) &amp;#8211; possibly copy from the &lt;a href=&quot;http://mongoc.org/libmongoc/current/mongoc_uri_t.html#connection-pool-options&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;libmongoc docs&lt;/a&gt;&lt;/li&gt;
		&lt;li&gt;Describe (with link to example) how to set up a pooled client&lt;/li&gt;
	&lt;/ul&gt;
	&lt;/li&gt;
	&lt;li&gt;Update the &lt;a href=&quot;https://mongodb.github.io/mongo-cxx-driver/mongocxx-v3/thread-safety/&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;thread safety&lt;/a&gt; page
	&lt;ul&gt;
		&lt;li&gt;Revise so that it clearly applies both to standalone clients and clients from a pool&lt;/li&gt;
		&lt;li&gt;Update the title (but not the link URL) to &quot;Thread and fork safety&quot;&lt;/li&gt;
		&lt;li&gt;Add a small section about fork safety &amp;#8211; that client/pool can&apos;t be used across a fork.&lt;/li&gt;
	&lt;/ul&gt;
	&lt;/li&gt;
	&lt;li&gt;Update &lt;a href=&quot;https://mongodb.github.io/mongo-cxx-driver/mongocxx-v3/configuration/&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;configuration docs&lt;/a&gt;
	&lt;ul&gt;
		&lt;li&gt;Include a small section about configuring a pooled client and link to the new connection pools page&lt;/li&gt;
	&lt;/ul&gt;
	&lt;/li&gt;
	&lt;li&gt;Update doxygen docs for pool and client
	&lt;ul&gt;
		&lt;li&gt;Include a synopsis of and links to connection pool and/or thread safety docs pages as appropriate&lt;/li&gt;
		&lt;li&gt;Ensure rest of the docs are consistent with respect to the content of those pages&lt;/li&gt;
		&lt;li&gt;Recommend pool over standalone client for all production work (for background monitoring)&lt;/li&gt;
	&lt;/ul&gt;
	&lt;/li&gt;
&lt;/ul&gt;
</comment>
                            <comment id="1401116" author="david.golden" created="Wed, 5 Oct 2016 17:52:24 +0000"  >&lt;p&gt;We need to address fork safety as well.&lt;/p&gt;</comment>
                            <comment id="1370981" author="david.golden" created="Mon, 29 Aug 2016 18:34:03 +0000"  >&lt;p&gt;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.&lt;/p&gt;</comment>
                            <comment id="1359532" author="david.golden" created="Wed, 17 Aug 2016 14:31:26 +0000"  >&lt;p&gt;Generally speaking, anyone who &lt;b&gt;can&lt;/b&gt; use threads should use &lt;tt&gt;mongocxx::pool&lt;/tt&gt; with a replica set, even if their app itself isn&apos;t multi-threaded.  We should make that very obvious in the docs for &lt;tt&gt;mongocxx::client&lt;/tt&gt;.  And possibly, we should switch all the mongocxx examples to use &lt;tt&gt;mongocxx::pool&lt;/tt&gt; and acquire a client from it.&lt;/p&gt;</comment>
                    </comments>
                <issuelinks>
                            <issuelinktype id="10012">
                    <name>Related</name>
                                            <outwardlinks description="related to">
                                        <issuelink>
            <issuekey id="309614">CXX-995</issuekey>
        </issuelink>
            <issuelink>
            <issuekey id="299994">CXX-967</issuekey>
        </issuelink>
                            </outwardlinks>
                                                        </issuelinktype>
                    </issuelinks>
                <attachments>
                    </attachments>
                <subtasks>
                    </subtasks>
                <customfields>
                                                                                                                                                                                                                                                                                                                                                                    <customfield id="customfield_15850" key="com.atlassian.jira.plugins.jira-development-integration-plugin:devsummary">
                        <customfieldname>Development</customfieldname>
                        <customfieldvalues>
                            
                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        <customfield id="customfield_12550" key="com.pyxis.greenhopper.jira:gh-lexo-rank">
                        <customfieldname>Rank</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>2|hrav8f:</customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                <customfield id="customfield_10558" key="com.pyxis.greenhopper.jira:gh-global-rank">
                        <customfieldname>Rank (Obsolete)</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>9223372036854775807</customfieldvalue>
                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                    <customfield id="customfield_10557" key="com.pyxis.greenhopper.jira:gh-sprint">
                        <customfieldname>Sprint</customfieldname>
                        <customfieldvalues>
                                <customfieldvalue id="1601">Perl/CXX 2017-03-24</customfieldvalue>
    <customfieldvalue id="1675">Perl/CXX 2017-05-05</customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            </customfields>
    </item>
</channel>
</rss>