hacking/measuring_performance.html - buildstream - Git at Google

 <!DOCTYPE html>
 <html class="writer-html5" lang="en" data-content_root="../">
 <head>
   <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>Measuring performance &mdash; BuildStream 2.2.0+3.gc7274d41d documentation</title>
       <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
       <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=19f00094" />


   <!--[if lt IE 9]>
     <script src="../_static/js/html5shiv.min.js"></script>
   <![endif]-->

         <script src="../_static/jquery.js?v=5d32c60e"></script>
         <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
         <script src="../_static/documentation_options.js?v=f96d84dc"></script>
         <script src="../_static/doctools.js?v=9a2dae69"></script>
         <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../_static/js/theme.js"></script>
     <link rel="index" title="Index" href="../genindex.html" />
     <link rel="search" title="Search" href="../search.html" />
     <link rel="next" title="Making releases" href="making_releases.html" />
     <link rel="prev" title="Adding core plugins" href="writing_plugins.html" />
 </head>

 <body class="wy-body-for-nav">
   <div class="wy-grid-for-nav">
     <nav data-toggle="wy-nav-shift" class="wy-nav-side">
       <div class="wy-side-scroll">
         <div class="wy-side-nav-search" >


           <a href="../index.html" class="icon icon-home">
             BuildStream
           </a>
               <div class="version">
                 2.2.0+3.gc7274d41d
               </div>
 <div role="search">
   <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
     <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
     <input type="hidden" name="check_keywords" value="yes" />
     <input type="hidden" name="area" value="default" />
   </form>
 </div>
         </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
               <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="../main_about.html">About</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../main_install.html">Installing from Source</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../main_using.html">Using</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../main_core.html">Reference</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../main_porting.html">Porting guide</a></li>
 <li class="toctree-l1 current"><a class="reference internal" href="../CONTRIBUTING.html">Contributing</a><ul class="current">
 <li class="toctree-l2"><a class="reference internal" href="../CONTRIBUTING.html#filing-issues">Filing issues</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../CONTRIBUTING.html#fixing-bugs">Fixing bugs</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../CONTRIBUTING.html#adding-new-features">Adding new features</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../CONTRIBUTING.html#submitting-patches">Submitting patches</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../CONTRIBUTING.html#committer-access">Committer access</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../CONTRIBUTING.html#windows-ci">Windows CI</a></li>
 <li class="toctree-l2 current"><a class="reference internal" href="../CONTRIBUTING.html#further-information">Further information</a><ul class="current">
 <li class="toctree-l3"><a class="reference internal" href="coding_guidelines.html">Coding guidelines</a></li>
 <li class="toctree-l3"><a class="reference internal" href="using_the_testsuite.html">Using the test suite</a></li>
 <li class="toctree-l3"><a class="reference internal" href="writing_documentation.html">Writing documentation</a></li>
 <li class="toctree-l3"><a class="reference internal" href="writing_plugins.html">Adding core plugins</a></li>
 <li class="toctree-l3 current"><a class="current reference internal" href="#">Measuring performance</a><ul>
 <li class="toctree-l4"><a class="reference internal" href="#benchmarking-framework">Benchmarking framework</a></li>
 <li class="toctree-l4"><a class="reference internal" href="#profiling-tools">Profiling tools</a></li>
 <li class="toctree-l4"><a class="reference internal" href="#profiling-specific-parts-of-buildstream-with-bst-profile">Profiling specific parts of BuildStream with BST_PROFILE</a></li>
 <li class="toctree-l4"><a class="reference internal" href="#fixing-performance-issues">Fixing performance issues</a></li>
 </ul>
 </li>
 <li class="toctree-l3"><a class="reference internal" href="making_releases.html">Making releases</a></li>
 <li class="toctree-l3"><a class="reference internal" href="grpc_protocols.html">Generating protocol buffers</a></li>
 <li class="toctree-l3"><a class="reference internal" href="managing_data_files.html">Managing data files</a></li>
 <li class="toctree-l3"><a class="reference internal" href="updating_python_deps.html">Updating BuildStream’s Python dependencies</a></li>
 <li class="toctree-l3"><a class="reference internal" href="updating_python_deps.html#adding-support-for-a-new-python-release">Adding support for a new Python release</a></li>
 <li class="toctree-l3"><a class="reference internal" href="updating_python_deps.html#removing-support-for-a-python-release">Removing support for a Python release</a></li>
 <li class="toctree-l3"><a class="reference internal" href="updating_python_deps.html#abi-compatibility-for-binary-python-packages">ABI compatibility for binary Python packages</a></li>
 <li class="toctree-l3"><a class="reference internal" href="ui.html">Contributing to the UI</a></li>
 </ul>
 </li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="../main_architecture.html">Architecture</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../main_glossary.html">Glossary</a></li>
 </ul>

         </div>
       </div>
     </nav>

     <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
           <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
           <a href="../index.html">BuildStream</a>
       </nav>

       <div class="wy-nav-content">
         <div class="rst-content">
           <div role="navigation" aria-label="Page navigation">
   <ul class="wy-breadcrumbs">
       <li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
           <li class="breadcrumb-item"><a href="../CONTRIBUTING.html">Contributing</a></li>
       <li class="breadcrumb-item active">Measuring performance</li>
       <li class="wy-breadcrumbs-aside">
             <a href="../_sources/hacking/measuring_performance.rst.txt" rel="nofollow"> View page source</a>
       </li>
   </ul>
   <hr/>
 </div>
           <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
            <div itemprop="articleBody">

   <section id="measuring-performance">
 <span id="id1"></span><h1>Measuring performance<a class="headerlink" href="#measuring-performance" title="Link to this heading"></a></h1>
 <section id="benchmarking-framework">
 <h2>Benchmarking framework<a class="headerlink" href="#benchmarking-framework" title="Link to this heading"></a></h2>
 <p>BuildStream has a utility to measure performance which is available from a
 separate repository at <a class="reference external" href="https://gitlab.com/BuildStream/benchmarks">https://gitlab.com/BuildStream/benchmarks</a>. This tool
 allows you to run a fixed set of workloads with multiple versions of
 BuildStream. From this you can see whether one version performs better or
 worse than another which is useful when looking for regressions and when
 testing potential optimizations.</p>
 <p>For full documentation on how to use the benchmarking tool see the README in
 the ‘benchmarks’ repository.</p>
 </section>
 <section id="profiling-tools">
 <h2>Profiling tools<a class="headerlink" href="#profiling-tools" title="Link to this heading"></a></h2>
 <p>When looking for ways to speed up the code you should make use of a profiling
 tool.</p>
 <p>Python provides <a class="reference external" href="https://docs.python.org/3/library/profile.html">cProfile</a>
 which gives you a list of all functions called during execution and how much
 time was spent in each function. Here is an example of running <code class="docutils literal notranslate"><span class="pre">bst</span> <span class="pre">--help</span></code>
 under cProfile:</p>
 <blockquote>
 <div><p>python3 -m cProfile -o bst.cprofile – $(which bst) –help</p>
 </div></blockquote>
 <p>You can then analyze the results interactively using the ‘pstats’ module:</p>
 <blockquote>
 <div><p>python3 -m pstats ./bst.cprofile</p>
 </div></blockquote>
 <p>For more detailed documentation of cProfile and ‘pstats’, see:
 <a class="reference external" href="https://docs.python.org/3/library/profile.html">https://docs.python.org/3/library/profile.html</a>.</p>
 <p>For a richer and interactive visualisation of the <cite>.cprofile</cite> files, you can
 try <a class="reference external" href="http://jiffyclub.github.io/snakeviz/#interpreting-results">snakeviz</a>.
 You can install it with <cite>pip install snakeviz</cite>. Here is an example invocation:</p>
 <blockquote>
 <div><p>snakeviz bst.cprofile</p>
 </div></blockquote>
 <p>It will then start a webserver and launch a browser to the relevant page.</p>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
 <p>If you want to also profile cython files, you will need to add
 BST_CYTHON_PROFILE=1 and recompile the cython files.
 <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span></code> would take care of that.</p>
 </div>
 </section>
 <section id="profiling-specific-parts-of-buildstream-with-bst-profile">
 <h2>Profiling specific parts of BuildStream with BST_PROFILE<a class="headerlink" href="#profiling-specific-parts-of-buildstream-with-bst-profile" title="Link to this heading"></a></h2>
 <p>BuildStream can also turn on cProfile for specific parts of execution
 using BST_PROFILE.</p>
 <p>BST_PROFILE can be set to a section name, or a list of section names separated
 by “:”. You can also use “all” for getting all profiles at the same time.
 There is a list of topics in <cite>src/buildstream/_profile.py</cite>. For example, running:</p>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">BST_PROFILE</span><span class="o">=</span><span class="n">load</span><span class="o">-</span><span class="n">pipeline</span> <span class="n">bst</span> <span class="n">build</span> <span class="n">bootstrap</span><span class="o">-</span><span class="n">system</span><span class="o">-</span><span class="n">x86</span><span class="o">.</span><span class="n">bst</span>
 </pre></div>
 </div>
 <p>will produce a profile in the current directory for the time take to
 call most of <cite>initialized</cite>, for each element. These profile files
 are in the same cProfile format as those mentioned in the previous
 section, and can be analysed in the same way.</p>
 </section>
 <section id="fixing-performance-issues">
 <h2>Fixing performance issues<a class="headerlink" href="#fixing-performance-issues" title="Link to this heading"></a></h2>
 <p>BuildStream uses <a class="reference external" href="https://cython.org/">Cython</a> in order to speed up specific parts of the
 code base.</p>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
 <p>When optimizing for performance, please ensure that you optimize the algorithms before
 jumping into Cython code. Cython will make the code harder to maintain and less accessible
 to all developers.</p>
 </div>
 <p>When adding a new cython file to the codebase, you will need to register it in <code class="docutils literal notranslate"><span class="pre">setup.py</span></code>.</p>
 <p>For example, for a module <code class="docutils literal notranslate"><span class="pre">buildstream._my_module</span></code>, to be written in <code class="docutils literal notranslate"><span class="pre">src/buildstream/_my_module.pyx</span></code>, you would do:</p>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">register_cython_module</span><span class="p">(</span><span class="s2">&quot;buildstream._my_module&quot;</span><span class="p">)</span>
 </pre></div>
 </div>
 <p>In <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> and the build tool will automatically use your module.</p>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
 <p>Please register cython modules at the same place as the others.</p>
 </div>
 <p>When adding a definition class to share cython symbols between modules, please document the implementation file
 and only expose the required definitions.</p>
 </section>
 </section>


            </div>
           </div>
           <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
         <a href="writing_plugins.html" class="btn btn-neutral float-left" title="Adding core plugins" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
         <a href="making_releases.html" class="btn btn-neutral float-right" title="Making releases" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
     </div>

   <hr/>

   <div role="contentinfo">
     <p>&#169; Copyright 2017-2022, The Apache Software Foundation.</p>
   </div>

   Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
     <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
     provided by <a href="https://readthedocs.org">Read the Docs</a>.


 </footer>
         </div>
       </div>
     </section>
   </div>
   <script>
       jQuery(function () {
           SphinxRtdTheme.Navigation.enable(true);
       });
   </script>

 </body>
 </html>
	<!DOCTYPE html>
	<html class="writer-html5" lang="en" data-content_root="../">
	<head>
	<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

	<meta name="viewport" content="width=device-width, initial-scale=1.0" />
	<title>Measuring performance — BuildStream 2.2.0+3.gc7274d41d documentation</title>
	<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
	<link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=19f00094" />


	<!--[if lt IE 9]>
	<script src="../_static/js/html5shiv.min.js"></script>
	<![endif]-->

	<script src="../_static/jquery.js?v=5d32c60e"></script>
	<script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
	<script src="../_static/documentation_options.js?v=f96d84dc"></script>
	<script src="../_static/doctools.js?v=9a2dae69"></script>
	<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
	<script src="../_static/js/theme.js"></script>
	<link rel="index" title="Index" href="../genindex.html" />
	<link rel="search" title="Search" href="../search.html" />
	<link rel="next" title="Making releases" href="making_releases.html" />
	<link rel="prev" title="Adding core plugins" href="writing_plugins.html" />
	</head>

	<body class="wy-body-for-nav">
	<div class="wy-grid-for-nav">
	<nav data-toggle="wy-nav-shift" class="wy-nav-side">
	<div class="wy-side-scroll">
	<div class="wy-side-nav-search" >



	<a href="../index.html" class="icon icon-home">
	BuildStream
	</a>
	<div class="version">
	2.2.0+3.gc7274d41d
	</div>
	<div role="search">
	<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
	<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
	<input type="hidden" name="check_keywords" value="yes" />
	<input type="hidden" name="area" value="default" />
	</form>
	</div>
	</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
	<ul class="current">
	<li class="toctree-l1"><a class="reference internal" href="../main_about.html">About</a></li>
	<li class="toctree-l1"><a class="reference internal" href="../main_install.html">Installing from Source</a></li>
	<li class="toctree-l1"><a class="reference internal" href="../main_using.html">Using</a></li>
	<li class="toctree-l1"><a class="reference internal" href="../main_core.html">Reference</a></li>
	<li class="toctree-l1"><a class="reference internal" href="../main_porting.html">Porting guide</a></li>
	<li class="toctree-l1 current"><a class="reference internal" href="../CONTRIBUTING.html">Contributing</a><ul class="current">
	<li class="toctree-l2"><a class="reference internal" href="../CONTRIBUTING.html#filing-issues">Filing issues</a></li>
	<li class="toctree-l2"><a class="reference internal" href="../CONTRIBUTING.html#fixing-bugs">Fixing bugs</a></li>
	<li class="toctree-l2"><a class="reference internal" href="../CONTRIBUTING.html#adding-new-features">Adding new features</a></li>
	<li class="toctree-l2"><a class="reference internal" href="../CONTRIBUTING.html#submitting-patches">Submitting patches</a></li>
	<li class="toctree-l2"><a class="reference internal" href="../CONTRIBUTING.html#committer-access">Committer access</a></li>
	<li class="toctree-l2"><a class="reference internal" href="../CONTRIBUTING.html#windows-ci">Windows CI</a></li>
	<li class="toctree-l2 current"><a class="reference internal" href="../CONTRIBUTING.html#further-information">Further information</a><ul class="current">
	<li class="toctree-l3"><a class="reference internal" href="coding_guidelines.html">Coding guidelines</a></li>
	<li class="toctree-l3"><a class="reference internal" href="using_the_testsuite.html">Using the test suite</a></li>
	<li class="toctree-l3"><a class="reference internal" href="writing_documentation.html">Writing documentation</a></li>
	<li class="toctree-l3"><a class="reference internal" href="writing_plugins.html">Adding core plugins</a></li>
	<li class="toctree-l3 current"><a class="current reference internal" href="#">Measuring performance</a><ul>
	<li class="toctree-l4"><a class="reference internal" href="#benchmarking-framework">Benchmarking framework</a></li>
	<li class="toctree-l4"><a class="reference internal" href="#profiling-tools">Profiling tools</a></li>
	<li class="toctree-l4"><a class="reference internal" href="#profiling-specific-parts-of-buildstream-with-bst-profile">Profiling specific parts of BuildStream with BST_PROFILE</a></li>
	<li class="toctree-l4"><a class="reference internal" href="#fixing-performance-issues">Fixing performance issues</a></li>
	</ul>
	</li>
	<li class="toctree-l3"><a class="reference internal" href="making_releases.html">Making releases</a></li>
	<li class="toctree-l3"><a class="reference internal" href="grpc_protocols.html">Generating protocol buffers</a></li>
	<li class="toctree-l3"><a class="reference internal" href="managing_data_files.html">Managing data files</a></li>
	<li class="toctree-l3"><a class="reference internal" href="updating_python_deps.html">Updating BuildStream’s Python dependencies</a></li>
	<li class="toctree-l3"><a class="reference internal" href="updating_python_deps.html#adding-support-for-a-new-python-release">Adding support for a new Python release</a></li>
	<li class="toctree-l3"><a class="reference internal" href="updating_python_deps.html#removing-support-for-a-python-release">Removing support for a Python release</a></li>
	<li class="toctree-l3"><a class="reference internal" href="updating_python_deps.html#abi-compatibility-for-binary-python-packages">ABI compatibility for binary Python packages</a></li>
	<li class="toctree-l3"><a class="reference internal" href="ui.html">Contributing to the UI</a></li>
	</ul>
	</li>
	</ul>
	</li>
	<li class="toctree-l1"><a class="reference internal" href="../main_architecture.html">Architecture</a></li>
	<li class="toctree-l1"><a class="reference internal" href="../main_glossary.html">Glossary</a></li>
	</ul>

	</div>
	</div>
	</nav>

	<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
	<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
	<a href="../index.html">BuildStream</a>
	</nav>

	<div class="wy-nav-content">
	<div class="rst-content">
	<div role="navigation" aria-label="Page navigation">
	<ul class="wy-breadcrumbs">
	<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
	<li class="breadcrumb-item"><a href="../CONTRIBUTING.html">Contributing</a></li>
	<li class="breadcrumb-item active">Measuring performance</li>
	<li class="wy-breadcrumbs-aside">
	<a href="../_sources/hacking/measuring_performance.rst.txt" rel="nofollow"> View page source</a>
	</li>
	</ul>
	<hr/>
	</div>
	<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
	<div itemprop="articleBody">

	<section id="measuring-performance">
	<span id="id1"></span><h1>Measuring performance<a class="headerlink" href="#measuring-performance" title="Link to this heading"></a></h1>
	<section id="benchmarking-framework">
	<h2>Benchmarking framework<a class="headerlink" href="#benchmarking-framework" title="Link to this heading"></a></h2>
	<p>BuildStream has a utility to measure performance which is available from a
	separate repository at <a class="reference external" href="https://gitlab.com/BuildStream/benchmarks">https://gitlab.com/BuildStream/benchmarks</a>. This tool
	allows you to run a fixed set of workloads with multiple versions of
	BuildStream. From this you can see whether one version performs better or
	worse than another which is useful when looking for regressions and when
	testing potential optimizations.</p>
	<p>For full documentation on how to use the benchmarking tool see the README in
	the ‘benchmarks’ repository.</p>
	</section>
	<section id="profiling-tools">
	<h2>Profiling tools<a class="headerlink" href="#profiling-tools" title="Link to this heading"></a></h2>
	<p>When looking for ways to speed up the code you should make use of a profiling
	tool.</p>
	<p>Python provides <a class="reference external" href="https://docs.python.org/3/library/profile.html">cProfile</a>
	which gives you a list of all functions called during execution and how much
	time was spent in each function. Here is an example of running <code class="docutils literal notranslate"><span class="pre">bst</span> <span class="pre">--help</span></code>
	under cProfile:</p>
	<blockquote>
	<div><p>python3 -m cProfile -o bst.cprofile – $(which bst) –help</p>
	</div></blockquote>
	<p>You can then analyze the results interactively using the ‘pstats’ module:</p>
	<blockquote>
	<div><p>python3 -m pstats ./bst.cprofile</p>
	</div></blockquote>
	<p>For more detailed documentation of cProfile and ‘pstats’, see:
	<a class="reference external" href="https://docs.python.org/3/library/profile.html">https://docs.python.org/3/library/profile.html</a>.</p>
	<p>For a richer and interactive visualisation of the <cite>.cprofile</cite> files, you can
	try <a class="reference external" href="http://jiffyclub.github.io/snakeviz/#interpreting-results">snakeviz</a>.
	You can install it with <cite>pip install snakeviz</cite>. Here is an example invocation:</p>
	<blockquote>
	<div><p>snakeviz bst.cprofile</p>
	</div></blockquote>
	<p>It will then start a webserver and launch a browser to the relevant page.</p>
	<div class="admonition note">
	<p class="admonition-title">Note</p>
	<p>If you want to also profile cython files, you will need to add
	BST_CYTHON_PROFILE=1 and recompile the cython files.
	<code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span></code> would take care of that.</p>
	</div>
	</section>
	<section id="profiling-specific-parts-of-buildstream-with-bst-profile">
	<h2>Profiling specific parts of BuildStream with BST_PROFILE<a class="headerlink" href="#profiling-specific-parts-of-buildstream-with-bst-profile" title="Link to this heading"></a></h2>
	<p>BuildStream can also turn on cProfile for specific parts of execution
	using BST_PROFILE.</p>
	<p>BST_PROFILE can be set to a section name, or a list of section names separated
	by “:”. You can also use “all” for getting all profiles at the same time.
	There is a list of topics in <cite>src/buildstream/_profile.py</cite>. For example, running:</p>
	<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">BST_PROFILE</span><span class="o">=</span><span class="n">load</span><span class="o">-</span><span class="n">pipeline</span> <span class="n">bst</span> <span class="n">build</span> <span class="n">bootstrap</span><span class="o">-</span><span class="n">system</span><span class="o">-</span><span class="n">x86</span><span class="o">.</span><span class="n">bst</span>
	</pre></div>
	</div>
	<p>will produce a profile in the current directory for the time take to
	call most of <cite>initialized</cite>, for each element. These profile files
	are in the same cProfile format as those mentioned in the previous
	section, and can be analysed in the same way.</p>
	</section>
	<section id="fixing-performance-issues">
	<h2>Fixing performance issues<a class="headerlink" href="#fixing-performance-issues" title="Link to this heading"></a></h2>
	<p>BuildStream uses <a class="reference external" href="https://cython.org/">Cython</a> in order to speed up specific parts of the
	code base.</p>
	<div class="admonition note">
	<p class="admonition-title">Note</p>
	<p>When optimizing for performance, please ensure that you optimize the algorithms before
	jumping into Cython code. Cython will make the code harder to maintain and less accessible
	to all developers.</p>
	</div>
	<p>When adding a new cython file to the codebase, you will need to register it in <code class="docutils literal notranslate"><span class="pre">setup.py</span></code>.</p>
	<p>For example, for a module <code class="docutils literal notranslate"><span class="pre">buildstream._my_module</span></code>, to be written in <code class="docutils literal notranslate"><span class="pre">src/buildstream/_my_module.pyx</span></code>, you would do:</p>
	<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">register_cython_module</span><span class="p">(</span><span class="s2">"buildstream._my_module"</span><span class="p">)</span>
	</pre></div>
	</div>
	<p>In <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> and the build tool will automatically use your module.</p>
	<div class="admonition note">
	<p class="admonition-title">Note</p>
	<p>Please register cython modules at the same place as the others.</p>
	</div>
	<p>When adding a definition class to share cython symbols between modules, please document the implementation file
	and only expose the required definitions.</p>
	</section>
	</section>


	</div>
	</div>
	<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
	<a href="writing_plugins.html" class="btn btn-neutral float-left" title="Adding core plugins" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
	<a href="making_releases.html" class="btn btn-neutral float-right" title="Making releases" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
	</div>

	<hr/>

	<div role="contentinfo">
	<p>© Copyright 2017-2022, The Apache Software Foundation.</p>
	</div>

	Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
	<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
	provided by <a href="https://readthedocs.org">Read the Docs</a>.


	</footer>
	</div>
	</div>
	</section>
	</div>
	<script>
	jQuery(function () {
	SphinxRtdTheme.Navigation.enable(true);
	});
	</script>

	</body>
	</html>