<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>Concurrency — KInterbasDB v3.3.0 documentation</title> <link rel="stylesheet" href="_static/default.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: '', VERSION: '3.3.0', COLLAPSE_MODINDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true }; </script> <script type="text/javascript" src="_static/jquery.js"></script> <script type="text/javascript" src="_static/doctools.js"></script> <link rel="index" title="Index" href="genindex.html" /> <link rel="search" title="Search" href="search.html" /> <link rel="top" title="KInterbasDB v3.3.0 documentation" href="index.html" /> <link rel="next" title="Overview of Firebird Client Library Thread-Safety" href="thread-safety-overview.html" /> <link rel="prev" title="Native Database Engine Features and Extensions Beyond the Python DB API" href="beyond-python-db-api.html" /> </head> <body> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="genindex.html" title="General Index" accesskey="I">index</a></li> <li class="right" > <a href="modindex.html" title="Global Module Index" accesskey="M">modules</a> |</li> <li class="right" > <a href="thread-safety-overview.html" title="Overview of Firebird Client Library Thread-Safety" accesskey="N">next</a> |</li> <li class="right" > <a href="beyond-python-db-api.html" title="Native Database Engine Features and Extensions Beyond the Python DB API" accesskey="P">previous</a> |</li> <li><a href="index.html">KInterbasDB v3.3.0 documentation</a> »</li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body"> <div class="section" id="concurrency"> <h1>Concurrency<a class="headerlink" href="#concurrency" title="Permalink to this headline">¶</a></h1> <div class="section" id="overview"> <h2>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2> <p>Note: This section will not be comprehensible unless you understand the basic characteristics of the Firebird server architectures. These are documented in the “Classic or Superserver?” section of the <cite>doc/Firebird-1.5-QuickStart.pdf</cite> file included with the Firebird distribution.</p> <p>Versions of KInterbasDB prior to 3.2 imposed a global lock over all database client library calls. This lock, referred to as the Global Database API Lock (GDAL), must be active for multithreaded client programs to work correctly with versions of the Firebird client library that do not properly support concurrency. Many such versions are still in use, so the GDAL remains active by default in KInterbasDB 3.2. To determine whether the client library you’re using can correctly handle concurrent database calls, read this <a class="reference external" href="thread-safety-overview.html">Overview of Firebird Client Library Thread-Safety</a>.</p> <p>Note that a single client library might have different thread-safety properties depending on which <em>protocol</em> the client program specifies via the parameters of <a title="kinterbasdb.connect" class="reference external" href="python-db-api-compliance.html#kinterbasdb.connect"><tt class="xref docutils literal"><span class="pre">kinterbasdb.connect()</span></tt></a>. For example, the Firebird 1.5 client library on Windows is thread-safe if the remote protocol is used, as in</p> <div class="highlight-python"><div class="highlight"><pre><span class="n">kinterbasdb</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="n">dsn</span><span class="o">=</span><span class="s">r'localhost:C:\temp\test.db'</span><span class="p">,</span> <span class="o">...</span><span class="p">)</span> </pre></div> </div> <p>but is <em>not</em> thread-safe if the local protocol is used, as in</p> <div class="highlight-python"><div class="highlight"><pre><span class="n">kinterbasdb</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="n">dsn</span><span class="o">=</span><span class="s">r'C:\temp\test.db'</span><span class="p">,</span> <span class="o">...</span><span class="p">)</span> </pre></div> </div> </div> <div class="section" id="selecting-and-activating-a-kinterbasdb-concurrency-level"> <h2>Selecting and Activating a KInterbasDB Concurrency Level<a class="headerlink" href="#selecting-and-activating-a-kinterbasdb-concurrency-level" title="Permalink to this headline">¶</a></h2> <p>KInterbasDB 3.2 supports three levels of concurrency:</p> <ul class="simple"> <li><strong>Level 0:</strong> No lock management whatsoever If the C preprocessor symbol <cite>ENABLE_CONCURRENCY</cite> is not defined when KInterbasDB is compiled, no lock management at all is performed at runtime. In fact, the code to initialize and manage the locks is not even compiled in. Level 0 is intended only for compiling KInterbasDB on non-threaded builds of the Python interpreter. It would not be desirable for a client program running on a normal (threaded) build of the Python interpreter to use Level 0, so no overhead is invested in making it possible to transition to Level 0 at runtime. Since Level 0 is intended for use in Python interpreters that have no Global Interpreter Lock (GIL), the GIL is not manipulated.</li> <li><strong>Level 1:</strong> Global Database API Lock (GDAL) is active (this is the default level) At Level 1, a global lock serializes all calls to the database client library. This lock, called the Global Database API Lock (GDAL), is to the database client library as the GIL is to the Python interpreter: a mechanism to guarantee that at most one thread is using the database client library at any time. Level 1 exists to support those versions of Firebird in which the client library is not thread-safe at the connection level (see the <a class="reference external" href="thread-safety-overview.html">Overview of Firebird Client Library Thread-Safety</a> for details). In environments where the author ofKInterbasDB creates binaries and distributes them to client programmers, there is no way of knowing at compile time which Firebird client library configuration the KInterbasDB binaries will be used with. Level 1 protects client programmers who are not aware of the thread-safety properties of their version of the client library. For these reasons, Level 1 is the default, but Level 2 can be selected at runtime via the <a title="kinterbasdb.init" class="reference external" href="beyond-python-db-api.html#kinterbasdb.init"><tt class="xref docutils literal"><span class="pre">kinterbasdb.init()</span></tt></a> function (see next section). At Level 1, the Python GIL is released and reacquired around most database client library calls in order to avoid blocking the entire Python process for the duration of the call.</li> <li><strong>Level 2:</strong> Global Database API Lock (GDAL) is not active, but connection and disconnection are serialized via the GCDL At Level 2, calls to the database client library are not serialized, except for calls to the connection attachment and detachment functions, which are serialized by a lock called the Global Connection and Disconnection Lock (GCDL). This limited form of serialization is necessary because the Firebird client library makes no guarantees about the thread- safety of connection and disconnection. Since most client programs written with high concurrency in mind use a connection pool that minimizes the need to physically connect and disconnect, the GCDL is not a serious impediment to concurrency. Level 2, which can be activated at runtime by calling <cite>kinterbasdb.init(concurrency_level=2)</cite>, is appropriate for client programmers who are aware of the thread-safety guarantees provided by their version of the Firebird client library, and have written the client program accordingly. For details about the thread-safety of various Firebird client library versions, see the <a class="reference external" href="thread-safety-overview.html">Overview of Firebird Client Library Thread-Safety</a>. At Level 2, the Python GIL is released and reacquired around most database client library calls, just as it is at Level 1.</li> </ul> <p>Level 1 is the default, so if you don’t understand these subtleties, or are using a client library configuration that is not thread-safe, you do not need to take any action to achieve thread-safety.</p> <p>Level 2 can greatly increase the throughput of a database-centric, multithreaded Python application, so you should use it if possible. Once you’ve determined that you’re using an appropriate connection protocol with a capable client library, you can activate Level 2 at runtime with the following call:</p> <div class="highlight-python"><div class="highlight"><pre><span class="n">kinterbasdb</span><span class="o">.</span><span class="n">init</span><span class="p">(</span><span class="n">concurrency_level</span><span class="o">=</span><span class="mf">2</span><span class="p">)</span> </pre></div> </div> <p>The <cite>kinterbasdb.init</cite> function can only be called once during the life of a process. If it has not been called explicitly, the function will be called implicitly when the client program tries to perform any database operation. Therefore, the recommended place to call <cite>kinterbasdb.init</cite> is at the top level of one of the main modules of your program. The importation infrastructure of the Python interpreter serializes all imports, so calling <cite>kinterbasdb.init</cite> at import time avoids the potential for multiple simultaneous calls, which could cause subtle problems.</p> </div> <div class="section" id="caveats"> <h2>Caveats<a class="headerlink" href="#caveats" title="Permalink to this headline">¶</a></h2> <ul class="simple"> <li><cite>threadsafety</cite> versus <cite>concurrency_level</cite> Make sure not to confuse KInterbasDB’s <cite>concurrency_level</cite> with its <cite>threadsafety</cite>. <cite>threadsafety</cite>, a module-level property required by the Python DB API Specification 2.0, represents the highest level of granularity at which the DB API implementation remains thread-safe. KInterbasDB is always “<a class="reference external" href="thread-safety-overview.html#definition">thread-safe at the connection level</a>” (DB API <cite>threadsafety 1</cite>), regardless of which <cite>concurrency_level</cite> is active. Think of <cite>threadsafety</cite> as the level of thread-safety that KInterbasDB guarantees, and <cite>concurrency_level</cite> as the degree to which KInterbasDB’s internals are able to exploit a client program’s potential for concurrency.</li> </ul> </div> <div class="section" id="tips-on-achieving-high-concurrency"> <h2>Tips on Achieving High Concurrency<a class="headerlink" href="#tips-on-achieving-high-concurrency" title="Permalink to this headline">¶</a></h2> <ul> <li><p class="first">Use the Classic server architecture, but the SuperServer client library. At the time of this writing (December 2005), the thread- centric Vulcan had not been released, so the multi-process Classic architecture was the only Firebird server architecture that could take advantage of multiple CPUs. This means that in most scenarios, Classic is far more concurrency-friendly than SuperServer. The Windows version of Firebird–whether Classic or SuperServer–offers a single client library, so the following advice is not relevant to Windows. The non- Windows versions of Firebird Classic include two client libraries:</p> <blockquote> <ul class="simple"> <li><cite>fbclient</cite> ( <cite>libfbclient.so</cite>) communicates with the server solely via the network protocol (possibly over an emulated network such as the local loopback). fbclient <a class="reference external" href="thread-safety-overview.html">is thread-safe in recent versions</a> of Firebird.</li> <li><cite>fbembed</cite> ( <cite>libfbembed.so</cite>) uses an in-process Classic server to manipulate the database file directly. <cite>fbembed</cite> is not thread-safe in any version of Firebird; it should never be used with KInterbasDB concurrency level 2.</li> </ul> </blockquote> <p>At present, the best way to achieve a concurrency-friendly KInterbasDB/Firebird configuration is to use a version of KInterbasDB linked against <a class="reference external" href="thread-safety-overview.html">a thread-safe fbclient</a>, running at concurrency level 2, and communicating with a Classic server. On Linux, such a setup can be created by installing the Classic server, then compiling KInterbasDB with the <cite>database_lib_name</cite> option in <tt class="docutils literal"><span class="pre">setup.cfg</span></tt> set to <cite>fbclient</cite> (this is the default setting). A version of KInterbasDB that was linked against <cite>fbembed</cite> (by setting <cite>database_lib_name=fbembed</cite>) will not work in a multithreaded program if the concurrency level is higher than 1. On Windows, use a Classic server in combination with one of the standard KInterbasDB Windows binaries for Firebird 1.5 or later, and be sure to set KInterbasDB’s concurrency level to 2.</p> </li> </ul> </div> </div> </div> </div> </div> <div class="sphinxsidebar"> <div class="sphinxsidebarwrapper"> <h3><a href="index.html">Table Of Contents</a></h3> <ul> <li><a class="reference external" href="">Concurrency</a><ul> <li><a class="reference external" href="#overview">Overview</a></li> <li><a class="reference external" href="#selecting-and-activating-a-kinterbasdb-concurrency-level">Selecting and Activating a KInterbasDB Concurrency Level</a></li> <li><a class="reference external" href="#caveats">Caveats</a></li> <li><a class="reference external" href="#tips-on-achieving-high-concurrency">Tips on Achieving High Concurrency</a></li> </ul> </li> </ul> <h4>Previous topic</h4> <p class="topless"><a href="beyond-python-db-api.html" title="previous chapter">Native Database Engine Features and Extensions Beyond the Python DB API</a></p> <h4>Next topic</h4> <p class="topless"><a href="thread-safety-overview.html" title="next chapter">Overview of Firebird Client Library Thread-Safety</a></p> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="_sources/concurrency.txt">Show Source</a></li> </ul> <h3>Quick search</h3> <form class="search" action="search.html" method="get"> <input type="text" name="q" size="18" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div> <div class="clearer"></div> </div> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="genindex.html" title="General Index" accesskey="I">index</a></li> <li class="right" > <a href="modindex.html" title="Global Module Index" accesskey="M">modules</a> |</li> <li class="right" > <a href="thread-safety-overview.html" title="Overview of Firebird Client Library Thread-Safety" accesskey="N">next</a> |</li> <li class="right" > <a href="beyond-python-db-api.html" title="Native Database Engine Features and Extensions Beyond the Python DB API" accesskey="P">previous</a> |</li> <li><a href="index.html">KInterbasDB v3.3.0 documentation</a> »</li> </ul> </div> <div class="footer"> © Copyright 2009, David Rushby, Pavel Cisar. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.5.1. </div> </body> </html>