File: //usr/share/doc/varnish-6.0.3/html/phk/apispaces.html
<!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="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>API spaces — Varnish version 6.0.3 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.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="next" title="Yah! A security issue - finally!" href="VSV00001.html" />
<link rel="prev" title="Poul-Hennings random outbursts" href="index.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="index.html" title="Poul-Hennings random outbursts"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Varnish version 6.0.3 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Poul-Hennings random outbursts</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="api-spaces">
<span id="phk-api-spaces"></span><h1>API spaces<a class="headerlink" href="#api-spaces" title="Permalink to this headline">¶</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"><math.h></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->push()</span></code> and <code class="docutils literal notranslate"><span class="pre">stack->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>
<div class="section" id="general-namespace-rules">
<h2>General namespace rules<a class="headerlink" href="#general-namespace-rules" title="Permalink to this headline">¶</a></h2>
<ol class="arabic simple">
<li>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.)</li>
<li>Public symbols has upper case prefix.</li>
<li>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.</li>
<li>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.</li>
</ol>
</div>
<div class="section" id="vmod-api-abi-levels">
<h2>VMOD API/ABI levels<a class="headerlink" href="#vmod-api-abi-levels" title="Permalink to this headline">¶</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>
</div>
<div class="section" id="the-vmod-vrt-api-abi">
<h2>The VMOD VRT API/ABI<a class="headerlink" href="#the-vmod-vrt-api-abi" title="Permalink to this headline">¶</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">"vdef.h"</span></code></div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">#include</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">"vrt_obj.h"</span></code></div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">"vcl.h"</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">"vrt.h"</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>       <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>       <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>
</div>
<div class="section" id="the-vmod-package-api-abi">
<h2>The VMOD PACKAGE API/ABI<a class="headerlink" href="#the-vmod-package-api-abi" title="Permalink to this headline">¶</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">"cache.h"</span>            <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">"cache_backend.h"</span></code></div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">"cache_director.h"</span></code></div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">"cache_filter.h"</span></code></div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">"waiter/waiter.h"</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">"cache.h"</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>       <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>       <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>
</div>
<div class="section" id="the-vmod-source-api-abi">
<h2>The VMOD SOURCE API/ABI<a class="headerlink" href="#the-vmod-source-api-abi" title="Permalink to this headline">¶</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>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<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>
<h4>Previous topic</h4>
<p class="topless"><a href="index.html"
title="previous chapter">Poul-Hennings random outbursts</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="VSV00001.html"
title="next chapter">Yah! A security issue - finally!</a></p>
<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>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</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="index.html" title="Poul-Hennings random outbursts"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Varnish version 6.0.3 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" >Poul-Hennings random outbursts</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2010-2014, Varnish Software AS.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>