Enhanced PHP File Manager

⬆️ Go Up (..)

📊 Server Information

Server:

nginx/1.28.0

System:

Linux 6.8.0-90-generic

PHP Version:

8.4.15

User:

alqudsvolunteers

Directory:

/home/alqudsvolunteers/rootlink/proc/self/root/proc/thread-self/root/usr/share/doc/varnish/html/phk

Free Space:

80.01 GB

🔧 Quick Actions

✏️ Editing: apispaces.html

<!DOCTYPE html>

<title>API spaces &#8212; Varnish version 7.5.0 documentation</title>
    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
    <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=e2714048" />
    
    <script src="../_static/documentation_options.js?v=8214db13"></script>
    <script src="../_static/doctools.js?v=888ff710"></script>
    <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
    
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="Yah! A security issue - finally!" href="VSV00001.html" />
    <link rel="prev" title="Do you feel lucky ?" href="lucky.html" /> 
  </head><body>
    <div class="related" role="navigation" aria-label="related navigation">
      <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="VSV00001.html" title="Yah! A security issue - finally!"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="lucky.html" title="Do you feel lucky ?"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="../index.html">Varnish version 7.5.0 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Poul-Hennings random outbursts</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">API spaces</a></li> 
      </ul>
    </div>

<div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="api-spaces">
<span id="phk-api-spaces"></span><h1>API spaces<a class="headerlink" href="#api-spaces" title="Link to this heading">¶</a></h1>
<p>The reason you cant remember hearing about “API spaces” at university
is that I just made that concept up, as a title for this piece.</p>
<p>We need a name for the collision where APIs meet namespaces.</p>
<p>At some point in their career, most C programmers learn that <code class="docutils literal notranslate"><span class="pre">j0</span></code>,
<code class="docutils literal notranslate"><span class="pre">j1</span></code>, <code class="docutils literal notranslate"><span class="pre">y0</span></code> and <code class="docutils literal notranslate"><span class="pre">y1</span></code> are names to avoid whereas <code class="docutils literal notranslate"><span class="pre">j2</span></code> and
<code class="docutils literal notranslate"><span class="pre">y2</span></code> up to, but not including <code class="docutils literal notranslate"><span class="pre">jn</span></code> and <code class="docutils literal notranslate"><span class="pre">yn</span></code> are OK.</p>
<p>The reason is that somebody back when I was a child thought it would
be really neat if the math library supported Bessel functions,
without thinking about <code class="docutils literal notranslate"><span class="pre">&lt;math.h&gt;</span></code> as an API which had to coexist
in the flat namespace of the C language along many other APIs.</p>
<p>One of the big attractions of Object Oriented programming is that
it solves exactly that problem:
Nobody is confused about <code class="docutils literal notranslate"><span class="pre">car-&gt;push()</span></code> and <code class="docutils literal notranslate"><span class="pre">stack-&gt;push()</span></code>.</p>
<p>But Varnish is written in C which has a flat namespace and we must
live with it.</p>
<p>From the very start, we defined cadastral boundaries in the flat
namespace by assigning VTLA prefixes to various chunks of code.</p>
<p><code class="docutils literal notranslate"><span class="pre">VSB_something</span></code> has to do with the sbufs we adopted from FreeBSD,
<code class="docutils literal notranslate"><span class="pre">VGC_something</span></code> is Vcc Generated C-source and so on.</p>
<p>Mostly we have stuck with the ‘V’ prefix, which for some reason
is almost unused everywhere else, but we also have prominent
exceptions.  <code class="docutils literal notranslate"><span class="pre">WS_something</span></code> for workspaces for instance.</p>
<p>As long as all the C-code was in-project, inconsistencies and
the precise location of function prototypes didn’t matter much,
it was “just something you had to know”.</p>
<p>Now that we have VMODs, and even more so, now that we want to provide
some semblance of API stability for VMODs, we have a lot of sorting
and some renaming to do, in order to clearly delineate APIs within
our flat namespace and our include files.</p>
<p>Frederick P. Brooks points out in his classic “The Mythical Man-Month”,
that is the difference between a program-product and a programming-product,
and he makes the case that the effort required tripples, going from
the former to the latter.</p>
<p>Having spent some weeks on what I thought would be a three day task
I suspect that his was an underestimate.</p>
<p>I will now try to lay out what I think will be our policy on APIs
and name-space sharing going forward, but please understand that
this is mostly just an aspirational goal at this point.</p>
<section id="general-namespace-rules">
<h2>General namespace rules<a class="headerlink" href="#general-namespace-rules" title="Link to this heading">¶</a></h2>
<ol class="arabic simple">
<li><p>Each API or otherwise isolated section of code gets a unique
prefix, ending with an underscore, (<code class="docutils literal notranslate"><span class="pre">VSB_</span></code>, <code class="docutils literal notranslate"><span class="pre">V1F_</span></code> etc.)</p></li>
<li><p>Public symbols has upper case prefix.</p></li>
<li><p>Private symbols use prefix in lower case, both as <code class="docutils literal notranslate"><span class="pre">static</span></code>
symbols in source files, and when exposed to other source
files in the same section of code.</p></li>
<li><p>Friends-With-Benefit symbols have an additional underscore
after the prefix:  <code class="docutils literal notranslate"><span class="pre">FOO__bar()</span></code> and are only to be used with
explicit permission, which should be clearly documented in
the relevant #include file.</p></li>
</ol>
</section>
<section id="vmod-api-abi-levels">
<h2>VMOD API/ABI levels<a class="headerlink" href="#vmod-api-abi-levels" title="Link to this heading">¶</a></h2>
<p>Vmods can be written against one of three API/ABI levels, called
respectively <code class="docutils literal notranslate"><span class="pre">VRT</span></code>, <code class="docutils literal notranslate"><span class="pre">PACKAGE</span></code> and <code class="docutils literal notranslate"><span class="pre">SOURCE</span></code>, defined in
detail below.</p>
<p>A VMOD which restricts itself to the <code class="docutils literal notranslate"><span class="pre">VRT</span></code> API/ABI gets maximum
stability and will, we hope, work without recompilation across
many major and minor releases of Varnish.</p>
<p>A VMOD which uses the <code class="docutils literal notranslate"><span class="pre">PACKAGE</span></code> API, will likely keep working
across minor releases of varnish releases, but will usually
need to be recompiled for new major releases of varnish.</p>
<p>A VMOD which uses the <code class="docutils literal notranslate"><span class="pre">SOURCE</span></code> API is compiled against one
specific version of Varnish, and will not work with another
version until recompiled.</p>
</section>
<section id="the-vmod-vrt-api-abi">
<h2>The VMOD VRT API/ABI<a class="headerlink" href="#the-vmod-vrt-api-abi" title="Link to this heading">¶</a></h2>
<p>This API space could also have been called ‘inline’, because it
is basically what you see in the C-source generated by VCC:</p>
<div class="line-block">
<div class="line">Include files allowed:</div>
<div class="line"><br /></div>
<div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">&quot;vdef.h&quot;</span></code></div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">&quot;vrt.h&quot;</span></code></div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">&quot;vrt_obj.h&quot;</span></code></div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">&quot;vcl.h&quot;</span></code></div>
</div>
</div>
<p>Any private and Friends-With-Benefits symbols are off-limits
to VMODs, (it is usually stuff VCC needs for the compiled
code, and likely as not, you will crash if you mess with it.)</p>
<p>The <code class="docutils literal notranslate"><span class="pre">&quot;vrt.h&quot;</span></code> contains two #defines which together defines
the level of this API:</p>
<div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">#define</span> <span class="pre">VRT_MAJOR_VERSION</span>&#160;&#160;&#160;&#160;&#160;&#160; <span class="pre">6U</span></code></div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">#define</span> <span class="pre">VRT_MINOR_VERSION</span>&#160;&#160;&#160;&#160;&#160;&#160; <span class="pre">2U</span></code></div>
</div>
<p>A snapshot of these will be automatically compiled into the
VMOD shared library, and they will be checked for compatibility
when the VMOD is imported by the VCL compiler.</p>
</section>
<section id="the-vmod-package-api-abi">
<h2>The VMOD PACKAGE API/ABI<a class="headerlink" href="#the-vmod-package-api-abi" title="Link to this heading">¶</a></h2>
<p>This API space provides access to everything in the <code class="docutils literal notranslate"><span class="pre">VRT</span></code> API
space plus the other exposed and supported APIs in varnishd.</p>
<div class="line-block">
<div class="line">Include files allowed:</div>
<div class="line"><br /></div>
<div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">&quot;cache.h&quot;</span>&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; <span class="pre">//</span> <span class="pre">NB:</span> <span class="pre">includes</span> <span class="pre">vdef.h</span> <span class="pre">and</span> <span class="pre">vrt.h</span></code></div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">&quot;cache_backend.h&quot;</span></code></div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">&quot;cache_director.h&quot;</span></code></div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">&quot;cache_filter.h&quot;</span></code></div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">&quot;waiter/waiter.h&quot;</span></code></div>
</div>
</div>
<p>Any private and Friends-With-Benefits symbols are off-limits
to VMODs.</p>
<p>In addition to the two-part VRT version, <code class="docutils literal notranslate"><span class="pre">&quot;cache.h&quot;</span></code> will
contain two #defines for levels of this API.</p>
<div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">#define</span> <span class="pre">PACKAGE_MAJOR_VERSION</span>&#160;&#160;&#160;&#160;&#160;&#160; <span class="pre">1U</span></code></div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">#define</span> <span class="pre">PACKAGE</span> <span class="pre">MINOR_VERSION</span>&#160;&#160;&#160;&#160;&#160;&#160; <span class="pre">3U</span></code></div>
</div>
<p>Compile-time snapshots of these will be checked, along with
their VRT cousins be checked for compatibility on VMOD import.</p>
</section>
<section id="the-vmod-source-api-abi">
<h2>The VMOD SOURCE API/ABI<a class="headerlink" href="#the-vmod-source-api-abi" title="Link to this heading">¶</a></h2>
<p>This API space provides access to private parts of varnishd and its
use is highly discouraged, unless you absolutely have to,</p>
<p>You can #include any file from the varnish source tree and use
anything you find in them - but don’t come crying to us if it
all ends in tears:  No refunds at this window.</p>
<p>A hash value of all the .h files in the source tree will be
compiled into the VMOD and will be checked to match exactly
on VMOD import.</p>
<p><em>phk</em></p>
</section>
</section>

<div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <div>
    <h3><a href="../index.html">Table of Contents</a></h3>
    <ul>
<li><a class="reference internal" href="#">API spaces</a><ul>
<li><a class="reference internal" href="#general-namespace-rules">General namespace rules</a></li>
<li><a class="reference internal" href="#vmod-api-abi-levels">VMOD API/ABI levels</a></li>
<li><a class="reference internal" href="#the-vmod-vrt-api-abi">The VMOD VRT API/ABI</a></li>
<li><a class="reference internal" href="#the-vmod-package-api-abi">The VMOD PACKAGE API/ABI</a></li>
<li><a class="reference internal" href="#the-vmod-source-api-abi">The VMOD SOURCE API/ABI</a></li>
</ul>
</li>
</ul>

</div>
  <div>
    <h4>Previous topic</h4>
    <p class="topless"><a href="lucky.html"
                          title="previous chapter">Do you feel lucky ?</a></p>
  </div>
  <div>
    <h4>Next topic</h4>
    <p class="topless"><a href="VSV00001.html"
                          title="next chapter">Yah!  A security issue - finally!</a></p>
  </div>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="../_sources/phk/apispaces.rst.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>
    </div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="VSV00001.html" title="Yah! A security issue - finally!"
             >next</a> |</li>
        <li class="right" >
          <a href="lucky.html" title="Do you feel lucky ?"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="../index.html">Varnish version 7.5.0 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="index.html" >Poul-Hennings random outbursts</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">API spaces</a></li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
    &#169; Copyright 2010-2014, Varnish Software AS.
      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.
    </div>
  </body>
</html>

❌ Cancel

🗂️ Enhanced PHP File Manager

📊 Server Information

🔧 Quick Actions

✏️ Editing: apispaces.html

📤 Upload File

📁 Create Folder

📄 Create File

✏️ Rename Item

🗑️ Delete Confirmation