/usr/share/doc/knot-resolver/modules_api.html is in knot-resolver-doc 2.1.1-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 | <!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>Modules API reference — Knot DNS Resolver 2.1.1 documentation</title>
<link rel="stylesheet" href="_static/nature.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '2.1.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</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="prev" title="Knot DNS Resolver library" href="lib.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="lib.html" title="Knot DNS Resolver library"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Knot DNS Resolver 2.1.1 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="modules-api-reference">
<span id="modules-api"></span><h1>Modules API reference<a class="headerlink" href="#modules-api-reference" title="Permalink to this headline">¶</a></h1>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><a class="reference internal" href="#supported-languages" id="id3">Supported languages</a></li>
<li><a class="reference internal" href="#the-anatomy-of-an-extension" id="id4">The anatomy of an extension</a></li>
<li><a class="reference internal" href="#writing-a-module-in-lua" id="id5">Writing a module in Lua</a></li>
<li><a class="reference internal" href="#writing-a-module-in-c" id="id6">Writing a module in C</a></li>
<li><a class="reference internal" href="#writing-a-module-in-go" id="id7">Writing a module in Go</a></li>
<li><a class="reference internal" href="#configuring-modules" id="id8">Configuring modules</a></li>
<li><a class="reference internal" href="#exposing-c-go-module-properties" id="id9">Exposing C/Go module properties</a></li>
</ul>
</div>
<div class="section" id="supported-languages">
<h2><a class="toc-backref" href="#id3">Supported languages</a><a class="headerlink" href="#supported-languages" title="Permalink to this headline">¶</a></h2>
<p>Currently modules written in C and LuaJIT are supported.
There is also a support for writing modules in Go 1.5+ — the library has no native Go bindings, library is accessible using <a class="reference external" href="http://golang.org/cmd/cgo/">CGO</a>.</p>
</div>
<div class="section" id="the-anatomy-of-an-extension">
<h2><a class="toc-backref" href="#id4">The anatomy of an extension</a><a class="headerlink" href="#the-anatomy-of-an-extension" title="Permalink to this headline">¶</a></h2>
<p>A module is a shared object or script defining specific functions, here’s an overview.</p>
<p><em>Note</em> — the <a class="reference internal" href="lib.html#lib-api-modules"><span class="std std-ref">Modules</span></a> header documents the module loading and API.</p>
<table border="1" class="docutils">
<colgroup>
<col width="25%" />
<col width="25%" />
<col width="25%" />
<col width="25%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">C/Go</th>
<th class="head">Lua</th>
<th class="head">Params</th>
<th class="head">Comment</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal"><span class="pre">X_api()</span></code> <a class="footnote-reference" href="#id2" id="id1">[1]</a></td>
<td> </td>
<td> </td>
<td>API version</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal"><span class="pre">X_init()</span></code></td>
<td><code class="docutils literal"><span class="pre">X.init()</span></code></td>
<td><code class="docutils literal"><span class="pre">module</span></code></td>
<td>Constructor</td>
</tr>
<tr class="row-even"><td><code class="docutils literal"><span class="pre">X_deinit()</span></code></td>
<td><code class="docutils literal"><span class="pre">X.deinit()</span></code></td>
<td><code class="docutils literal"><span class="pre">module,</span> <span class="pre">key</span></code></td>
<td>Destructor</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal"><span class="pre">X_config()</span></code></td>
<td><code class="docutils literal"><span class="pre">X.config()</span></code></td>
<td><code class="docutils literal"><span class="pre">module</span></code></td>
<td>Configuration</td>
</tr>
<tr class="row-even"><td><code class="docutils literal"><span class="pre">X_layer()</span></code></td>
<td><code class="docutils literal"><span class="pre">X.layer</span></code></td>
<td><code class="docutils literal"><span class="pre">module</span></code></td>
<td><a class="reference internal" href="lib.html#lib-layers"><span class="std std-ref">Module layer</span></a></td>
</tr>
<tr class="row-odd"><td><code class="docutils literal"><span class="pre">X_props()</span></code></td>
<td> </td>
<td> </td>
<td>List of properties</td>
</tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>Mandatory symbol.</td></tr>
</tbody>
</table>
<p>The <code class="docutils literal"><span class="pre">X</span></code> corresponds to the module name, if the module name is <code class="docutils literal"><span class="pre">hints</span></code>, then the prefix for constructor would be <code class="docutils literal"><span class="pre">hints_init()</span></code>.
This doesn’t apply for Go, as it for now always implements <cite>main</cite> and requires capitalized first letter in order to export its symbol.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>The resolution context <code class="xref c c-type docutils literal"><span class="pre">struct</span> <span class="pre">kr_context</span></code> holds loaded modules for current context. A module can be registered with <code class="xref c c-func docutils literal"><span class="pre">kr_context_register()</span></code>, which triggers module constructor <em>immediately</em> after the load. Module destructor is automatically called when the resolution context closes.</p>
<p class="last">If the module exports a layer implementation, it is automatically discovered by <code class="xref c c-func docutils literal"><span class="pre">kr_resolver()</span></code> on resolution init and plugged in. The order in which the modules are registered corresponds to the call order of layers.</p>
</div>
</div>
<div class="section" id="writing-a-module-in-lua">
<h2><a class="toc-backref" href="#id5">Writing a module in Lua</a><a class="headerlink" href="#writing-a-module-in-lua" title="Permalink to this headline">¶</a></h2>
<p>The probably most convenient way of writing modules is Lua since you can use already installed modules
from system and have first-class access to the scripting engine. You can also tap to all the events, that
the C API has access to, but keep in mind that transitioning from the C to Lua function is slower than
the other way round.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The Lua functions retrieve an additional first parameter compared to the C counterparts - a “state”.
There is no Lua wrapper for C structures used in the resolution context, until they’re implemented
you can inspect the structures using the <a class="reference external" href="http://luajit.org/ext_ffi.html">ffi</a> library.</p>
</div>
<p>The modules follow the <a class="reference external" href="http://lua-users.org/wiki/ModuleDefinition">Lua way</a>, where the module interface is returned in a named table.</p>
<div class="highlight-lua"><div class="highlight"><pre><span></span><span class="c1">--- @module Count incoming queries</span>
<span class="kd">local</span> <span class="n">counter</span> <span class="o">=</span> <span class="p">{}</span>
<span class="kr">function</span> <span class="nc">counter</span><span class="p">.</span><span class="nf">init</span><span class="p">(</span><span class="n">module</span><span class="p">)</span>
<span class="n">counter</span><span class="p">.</span><span class="n">total</span> <span class="o">=</span> <span class="mi">0</span>
<span class="n">counter</span><span class="p">.</span><span class="n">last</span> <span class="o">=</span> <span class="mi">0</span>
<span class="n">counter</span><span class="p">.</span><span class="n">failed</span> <span class="o">=</span> <span class="mi">0</span>
<span class="kr">end</span>
<span class="kr">function</span> <span class="nc">counter</span><span class="p">.</span><span class="nf">deinit</span><span class="p">(</span><span class="n">module</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="s1">'counted'</span><span class="p">,</span> <span class="n">counter</span><span class="p">.</span><span class="n">total</span><span class="p">,</span> <span class="s1">'queries'</span><span class="p">)</span>
<span class="kr">end</span>
<span class="c1">-- @function Run the q/s counter with given interval.</span>
<span class="kr">function</span> <span class="nc">counter</span><span class="p">.</span><span class="nf">config</span><span class="p">(</span><span class="n">conf</span><span class="p">)</span>
<span class="c1">-- We can use the scripting facilities here</span>
<span class="kr">if</span> <span class="n">counter</span><span class="p">.</span><span class="n">ev</span> <span class="kr">then</span> <span class="n">event</span><span class="p">.</span><span class="n">cancel</span><span class="p">(</span><span class="n">counter</span><span class="p">.</span><span class="n">ev</span><span class="p">)</span>
<span class="n">event</span><span class="p">.</span><span class="n">recurrent</span><span class="p">(</span><span class="n">conf</span><span class="p">.</span><span class="n">interval</span><span class="p">,</span> <span class="kr">function</span> <span class="p">()</span>
<span class="nb">print</span><span class="p">(</span><span class="n">counter</span><span class="p">.</span><span class="n">total</span> <span class="o">-</span> <span class="n">counter</span><span class="p">.</span><span class="n">last</span><span class="p">,</span> <span class="s1">'q/s'</span><span class="p">)</span>
<span class="n">counter</span><span class="p">.</span><span class="n">last</span> <span class="o">=</span> <span class="n">counter</span><span class="p">.</span><span class="n">total</span>
<span class="kr">end</span><span class="p">)</span>
<span class="kr">end</span>
<span class="kr">return</span> <span class="n">counter</span>
</pre></div>
</div>
<div class="admonition tip">
<p class="first admonition-title">Tip</p>
<p class="last">The API functions may return an integer value just like in other languages, but they may also return a coroutine that will be continued asynchronously. A good use case for this approach is is a deferred initialization, e.g. loading a chunks of data or waiting for I/O.</p>
</div>
<div class="highlight-lua"><div class="highlight"><pre><span></span><span class="kr">function</span> <span class="nc">counter</span><span class="p">.</span><span class="nf">init</span><span class="p">(</span><span class="n">module</span><span class="p">)</span>
<span class="n">counter</span><span class="p">.</span><span class="n">total</span> <span class="o">=</span> <span class="mi">0</span>
<span class="n">counter</span><span class="p">.</span><span class="n">last</span> <span class="o">=</span> <span class="mi">0</span>
<span class="n">counter</span><span class="p">.</span><span class="n">failed</span> <span class="o">=</span> <span class="mi">0</span>
<span class="kr">return</span> <span class="nb">coroutine.create</span><span class="p">(</span><span class="kr">function</span> <span class="p">()</span>
<span class="kr">for</span> <span class="n">line</span> <span class="kr">in</span> <span class="nb">io.lines</span><span class="p">(</span><span class="s1">'/etc/hosts'</span><span class="p">)</span> <span class="kr">do</span>
<span class="nb">load</span><span class="p">(</span><span class="n">module</span><span class="p">,</span> <span class="n">line</span><span class="p">)</span>
<span class="nb">coroutine.yield</span><span class="p">()</span>
<span class="kr">end</span>
<span class="kr">end</span><span class="p">)</span>
<span class="kr">end</span>
</pre></div>
</div>
<p>The created module can be then loaded just like any other module, except it isn’t very useful since it
doesn’t provide any layer to capture events. The Lua module can however provide a processing layer, just
<a class="reference internal" href="lib.html#lib-layers"><span class="std std-ref">like its C counterpart</span></a>.</p>
<div class="highlight-lua"><div class="highlight"><pre><span></span><span class="c1">-- Notice it isn't a function, but a table of functions</span>
<span class="n">counter</span><span class="p">.</span><span class="n">layer</span> <span class="o">=</span> <span class="p">{</span>
<span class="n">begin</span> <span class="o">=</span> <span class="kr">function</span> <span class="p">(</span><span class="n">state</span><span class="p">,</span> <span class="n">data</span><span class="p">)</span>
<span class="n">counter</span><span class="p">.</span><span class="n">total</span> <span class="o">=</span> <span class="n">counter</span><span class="p">.</span><span class="n">total</span> <span class="o">+</span> <span class="mi">1</span>
<span class="kr">return</span> <span class="n">state</span>
<span class="kr">end</span><span class="p">,</span>
<span class="n">finish</span> <span class="o">=</span> <span class="kr">function</span> <span class="p">(</span><span class="n">state</span><span class="p">,</span> <span class="n">req</span><span class="p">,</span> <span class="n">answer</span><span class="p">)</span>
<span class="kr">if</span> <span class="n">state</span> <span class="o">==</span> <span class="n">kres</span><span class="p">.</span><span class="n">FAIL</span> <span class="kr">then</span>
<span class="n">counter</span><span class="p">.</span><span class="n">failed</span> <span class="o">=</span> <span class="n">counter</span><span class="p">.</span><span class="n">failed</span> <span class="o">+</span> <span class="mi">1</span>
<span class="kr">end</span>
<span class="kr">return</span> <span class="n">state</span>
<span class="kr">end</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Since the modules are like any other Lua modules, you can interact with them through the CLI and and any interface.</p>
<div class="admonition tip">
<p class="first admonition-title">Tip</p>
<p class="last">The module can be placed anywhere in the Lua search path, in the working directory or in the MODULESDIR.</p>
</div>
</div>
<div class="section" id="writing-a-module-in-c">
<h2><a class="toc-backref" href="#id6">Writing a module in C</a><a class="headerlink" href="#writing-a-module-in-c" title="Permalink to this headline">¶</a></h2>
<p>As almost all the functions are optional, the minimal module looks like this:</p>
<div class="highlight-c"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf">"lib/module.h"</span><span class="cp"></span>
<span class="cm">/* Convenience macro to declare module API. */</span>
<span class="n">KR_MODULE_EXPORT</span><span class="p">(</span><span class="n">mymodule</span><span class="p">);</span>
</pre></div>
</div>
<p>Let’s define an observer thread for the module as well. It’s going to be stub for the sake of brevity,
but you can for example create a condition, and notify the thread from query processing by declaring
module layer (see the <a class="reference internal" href="lib.html#lib-layers"><span class="std std-ref">Writing layers</span></a>).</p>
<div class="highlight-c"><div class="highlight"><pre><span></span><span class="k">static</span> <span class="kt">void</span><span class="o">*</span> <span class="nf">observe</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">arg</span><span class="p">)</span>
<span class="p">{</span>
<span class="cm">/* ... do some observing ... */</span>
<span class="p">}</span>
<span class="kt">int</span> <span class="nf">mymodule_init</span><span class="p">(</span><span class="k">struct</span> <span class="n">kr_module</span> <span class="o">*</span><span class="n">module</span><span class="p">)</span>
<span class="p">{</span>
<span class="cm">/* Create a thread and start it in the background. */</span>
<span class="n">pthread_t</span> <span class="n">thr_id</span><span class="p">;</span>
<span class="kt">int</span> <span class="n">ret</span> <span class="o">=</span> <span class="n">pthread_create</span><span class="p">(</span><span class="o">&</span><span class="n">thr_id</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">,</span> <span class="o">&</span><span class="n">observe</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">ret</span> <span class="o">!=</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="n">kr_error</span><span class="p">(</span><span class="n">errno</span><span class="p">);</span>
<span class="p">}</span>
<span class="cm">/* Keep it in the thread */</span>
<span class="n">module</span><span class="o">-></span><span class="n">data</span> <span class="o">=</span> <span class="n">thr_id</span><span class="p">;</span>
<span class="k">return</span> <span class="n">kr_ok</span><span class="p">();</span>
<span class="p">}</span>
<span class="kt">int</span> <span class="nf">mymodule_deinit</span><span class="p">(</span><span class="k">struct</span> <span class="n">kr_module</span> <span class="o">*</span><span class="n">module</span><span class="p">)</span>
<span class="p">{</span>
<span class="cm">/* ... signalize cancellation ... */</span>
<span class="kt">void</span> <span class="o">*</span><span class="n">res</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span>
<span class="n">pthread_t</span> <span class="n">thr_id</span> <span class="o">=</span> <span class="p">(</span><span class="n">pthread_t</span><span class="p">)</span> <span class="n">module</span><span class="o">-></span><span class="n">data</span><span class="p">;</span>
<span class="kt">int</span> <span class="n">ret</span> <span class="o">=</span> <span class="n">pthread_join</span><span class="p">(</span><span class="n">thr_id</span><span class="p">,</span> <span class="n">res</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">ret</span> <span class="o">!=</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="n">kr_error</span><span class="p">(</span><span class="n">errno</span><span class="p">);</span>
<span class="p">}</span>
<span class="k">return</span> <span class="n">kr_ok</span><span class="p">();</span>
<span class="p">}</span>
</pre></div>
</div>
<p>This example shows how a module can run in the background, this enables you to, for example, observe
and publish data about query resolution.</p>
</div>
<div class="section" id="writing-a-module-in-go">
<h2><a class="toc-backref" href="#id7">Writing a module in Go</a><a class="headerlink" href="#writing-a-module-in-go" title="Permalink to this headline">¶</a></h2>
<p>The Go modules use <a class="reference external" href="http://golang.org/cmd/cgo/">CGO</a> to interface C resolver library, there are no native bindings yet. Second issue is that layers are declared as a structure of function pointers, which are <a class="reference external" href="http://blog.golang.org/gos-declaration-syntax">not present in Go</a>, the workaround is to declare them in <a class="reference external" href="http://golang.org/cmd/cgo/">CGO</a> header. Each module must be the <code class="docutils literal"><span class="pre">main</span></code> package, here’s a minimal example:</p>
<div class="highlight-go"><div class="highlight"><pre><span></span><span class="kn">package</span> <span class="nx">main</span>
<span class="cm">/*</span>
<span class="cm">#include "lib/module.h"</span>
<span class="cm">*/</span>
<span class="kn">import</span> <span class="s">"C"</span>
<span class="kn">import</span> <span class="s">"unsafe"</span>
<span class="cm">/* Mandatory functions */</span>
<span class="c1">//export mymodule_api</span>
<span class="kd">func</span> <span class="nx">mymodule_api</span><span class="p">()</span> <span class="nx">C</span><span class="p">.</span><span class="nx">uint32_t</span> <span class="p">{</span>
<span class="k">return</span> <span class="nx">C</span><span class="p">.</span><span class="nx">KR_MODULE_API</span>
<span class="p">}</span>
<span class="kd">func</span> <span class="nx">main</span><span class="p">()</span> <span class="p">{}</span>
</pre></div>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Do not forget to prefix function declarations with <code class="docutils literal"><span class="pre">//export</span> <span class="pre">symbol_name</span></code>, as only these will be exported in module.</p>
</div>
<p>In order to integrate with query processing, you have to declare a helper function with function pointers to the
the layer implementation. Since the code prefacing <code class="docutils literal"><span class="pre">import</span> <span class="pre">"C"</span></code> is expanded in headers, you need the <cite>static inline</cite> trick
to avoid multiple declarations. Here’s how the preface looks like:</p>
<div class="highlight-go"><div class="highlight"><pre><span></span><span class="cm">/*</span>
<span class="cm">#include "lib/layer.h"</span>
<span class="cm">#include "lib/module.h"</span>
<span class="cm">// Need a forward declaration of the function signature</span>
<span class="cm">int finish(kr_layer_t *);</span>
<span class="cm">// Workaround for layers composition</span>
<span class="cm">static inline const kr_layer_api_t *_layer(void)</span>
<span class="cm">{</span>
<span class="cm"> static const kr_layer_api_t api = {</span>
<span class="cm"> .finish = &finish</span>
<span class="cm"> };</span>
<span class="cm"> return &api;</span>
<span class="cm">}</span>
<span class="cm">*/</span>
<span class="kn">import</span> <span class="s">"C"</span>
<span class="kn">import</span> <span class="s">"unsafe"</span>
</pre></div>
</div>
<p>Now we can add the implementations for the <code class="docutils literal"><span class="pre">finish</span></code> layer and finalize the module:</p>
<div class="highlight-go"><div class="highlight"><pre><span></span><span class="c1">//export finish</span>
<span class="kd">func</span> <span class="nx">finish</span><span class="p">(</span><span class="nx">ctx</span> <span class="o">*</span><span class="nx">C</span><span class="p">.</span><span class="nx">kr_layer_t</span><span class="p">)</span> <span class="nx">C</span><span class="p">.</span><span class="kt">int</span> <span class="p">{</span>
<span class="c1">// Since the context is unsafe.Pointer, we need to cast it</span>
<span class="kd">var</span> <span class="nx">param</span> <span class="o">*</span><span class="nx">C</span><span class="p">.</span><span class="nx">struct_kr_request</span> <span class="p">=</span> <span class="p">(</span><span class="o">*</span><span class="nx">C</span><span class="p">.</span><span class="nx">struct_kr_request</span><span class="p">)(</span><span class="nx">ctx</span><span class="p">.</span><span class="nx">data</span><span class="p">)</span>
<span class="c1">// Now we can use the C API as well</span>
<span class="nx">fmt</span><span class="p">.</span><span class="nx">Printf</span><span class="p">(</span><span class="s">"[go] resolved %d queries\n"</span><span class="p">,</span> <span class="nx">C</span><span class="p">.</span><span class="nx">list_size</span><span class="p">(</span><span class="o">&</span><span class="nx">param</span><span class="p">.</span><span class="nx">rplan</span><span class="p">.</span><span class="nx">resolved</span><span class="p">))</span>
<span class="k">return</span> <span class="mi">0</span>
<span class="p">}</span>
<span class="c1">//export mymodule_layer</span>
<span class="kd">func</span> <span class="nx">mymodule_layer</span><span class="p">(</span><span class="nx">module</span> <span class="o">*</span><span class="nx">C</span><span class="p">.</span><span class="nx">struct_kr_module</span><span class="p">)</span> <span class="o">*</span><span class="nx">C</span><span class="p">.</span><span class="nx">kr_layer_api_t</span> <span class="p">{</span>
<span class="c1">// Wrapping the inline trampoline function</span>
<span class="k">return</span> <span class="nx">C</span><span class="p">.</span><span class="nx">_layer</span><span class="p">()</span>
<span class="p">}</span>
</pre></div>
</div>
<p>See the <a class="reference external" href="http://golang.org/cmd/cgo/">CGO</a> for more information about type conversions and interoperability between the C/Go.</p>
<div class="section" id="gotchas">
<h3>Gotchas<a class="headerlink" href="#gotchas" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">main()</span></code> function is mandatory in each module, otherwise it won’t compile.</li>
<li>Module layer function implementation must be done in C during <code class="docutils literal"><span class="pre">import</span> <span class="pre">"C"</span></code>, as Go doesn’t support pointers to functions.</li>
<li>The library doesn’t have a Go-ified bindings yet, so interacting with it requires CGO shims, namely structure traversal and type conversions (strings, numbers).</li>
<li>Other modules can be called through C call <code class="docutils literal"><span class="pre">C.kr_module_call(kr_context,</span> <span class="pre">module_name,</span> <span class="pre">module_propery,</span> <span class="pre">input)</span></code></li>
</ul>
</div>
</div>
<div class="section" id="configuring-modules">
<h2><a class="toc-backref" href="#id8">Configuring modules</a><a class="headerlink" href="#configuring-modules" title="Permalink to this headline">¶</a></h2>
<p>There is a callback <code class="docutils literal"><span class="pre">X_config()</span></code> that you can implement, see hints module.</p>
</div>
<div class="section" id="exposing-c-go-module-properties">
<span id="mod-properties"></span><h2><a class="toc-backref" href="#id9">Exposing C/Go module properties</a><a class="headerlink" href="#exposing-c-go-module-properties" title="Permalink to this headline">¶</a></h2>
<p>A module can offer NULL-terminated list of <em>properties</em>, each property is essentially a callable with free-form JSON input/output.
JSON was chosen as an interchangeable format that doesn’t require any schema beforehand, so you can do two things - query the module properties
from external applications or between modules (i.e. <cite>statistics</cite> module can query <cite>cache</cite> module for memory usage).
JSON was chosen not because it’s the most efficient protocol, but because it’s easy to read and write and interface to outside world.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The <code class="docutils literal"><span class="pre">void</span> <span class="pre">*env</span></code> is a generic module interface. Since we’re implementing daemon modules, the pointer can be cast to <code class="docutils literal"><span class="pre">struct</span> <span class="pre">engine*</span></code>.
This is guaranteed by the implemented API version (see <a class="reference internal" href="#writing-a-module-in-c">Writing a module in C</a>).</p>
</div>
<p>Here’s an example how a module can expose its property:</p>
<div class="highlight-c"><div class="highlight"><pre><span></span><span class="kt">char</span><span class="o">*</span> <span class="nf">get_size</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">env</span><span class="p">,</span> <span class="k">struct</span> <span class="n">kr_module</span> <span class="o">*</span><span class="n">m</span><span class="p">,</span>
<span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">args</span><span class="p">)</span>
<span class="p">{</span>
<span class="cm">/* Get cache from engine. */</span>
<span class="k">struct</span> <span class="n">engine</span> <span class="o">*</span><span class="n">engine</span> <span class="o">=</span> <span class="n">env</span><span class="p">;</span>
<span class="k">struct</span> <span class="n">kr_cache</span> <span class="o">*</span><span class="n">cache</span> <span class="o">=</span> <span class="o">&</span><span class="n">engine</span><span class="o">-></span><span class="n">resolver</span><span class="p">.</span><span class="n">cache</span><span class="p">;</span>
<span class="cm">/* Read item count */</span>
<span class="kt">int</span> <span class="n">count</span> <span class="o">=</span> <span class="p">(</span><span class="n">cache</span><span class="o">-></span><span class="n">api</span><span class="p">)</span><span class="o">-></span><span class="n">count</span><span class="p">(</span><span class="n">cache</span><span class="o">-></span><span class="n">db</span><span class="p">);</span>
<span class="kt">char</span> <span class="o">*</span><span class="n">result</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span>
<span class="n">asprintf</span><span class="p">(</span><span class="o">&</span><span class="n">result</span><span class="p">,</span> <span class="s">"{ </span><span class="se">\"</span><span class="s">result</span><span class="se">\"</span><span class="s">: %d }"</span><span class="p">,</span> <span class="n">count</span><span class="p">);</span>
<span class="k">return</span> <span class="n">result</span><span class="p">;</span>
<span class="p">}</span>
<span class="k">struct</span> <span class="n">kr_prop</span> <span class="o">*</span><span class="nf">cache_props</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span>
<span class="p">{</span>
<span class="k">static</span> <span class="k">struct</span> <span class="n">kr_prop</span> <span class="n">prop_list</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span>
<span class="cm">/* Callback, Name, Description */</span>
<span class="p">{</span><span class="o">&</span><span class="n">get_size</span><span class="p">,</span> <span class="s">"get_size"</span><span class="p">,</span> <span class="s">"Return number of records."</span><span class="p">},</span>
<span class="p">{</span><span class="nb">NULL</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">}</span>
<span class="p">};</span>
<span class="k">return</span> <span class="n">prop_list</span><span class="p">;</span>
<span class="p">}</span>
<span class="n">KR_MODULE_EXPORT</span><span class="p">(</span><span class="n">cache</span><span class="p">)</span>
</pre></div>
</div>
<p>Once you load the module, you can call the module property from the interactive console.
<em>Note</em> — the JSON output will be transparently converted to Lua tables.</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>$ kresd
...
<span class="o">[</span>system<span class="o">]</span> started in interactive mode, <span class="nb">type</span> <span class="s1">'help()'</span>
> modules.load<span class="o">(</span><span class="s1">'cached'</span><span class="o">)</span>
> cached.get_size<span class="o">()</span>
<span class="o">[</span>size<span class="o">]</span> <span class="o">=</span>> <span class="m">53</span>
</pre></div>
</div>
<p><em>Note</em> — this relies on function pointers, so the same <code class="docutils literal"><span class="pre">static</span> <span class="pre">inline</span></code> trick as for the <code class="docutils literal"><span class="pre">Layer()</span></code> is required for C/Go.</p>
<div class="section" id="special-properties">
<h3>Special properties<a class="headerlink" href="#special-properties" title="Permalink to this headline">¶</a></h3>
<p>If the module declares properties <code class="docutils literal"><span class="pre">get</span></code> or <code class="docutils literal"><span class="pre">set</span></code>, they can be used in the Lua interpreter as
regular tables.</p>
</div>
</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="#">Modules API reference</a><ul>
<li><a class="reference internal" href="#supported-languages">Supported languages</a></li>
<li><a class="reference internal" href="#the-anatomy-of-an-extension">The anatomy of an extension</a></li>
<li><a class="reference internal" href="#writing-a-module-in-lua">Writing a module in Lua</a></li>
<li><a class="reference internal" href="#writing-a-module-in-c">Writing a module in C</a></li>
<li><a class="reference internal" href="#writing-a-module-in-go">Writing a module in Go</a><ul>
<li><a class="reference internal" href="#gotchas">Gotchas</a></li>
</ul>
</li>
<li><a class="reference internal" href="#configuring-modules">Configuring modules</a></li>
<li><a class="reference internal" href="#exposing-c-go-module-properties">Exposing C/Go module properties</a><ul>
<li><a class="reference internal" href="#special-properties">Special properties</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="lib.html"
title="previous chapter">Knot DNS Resolver library</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/modules_api.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</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="lib.html" title="Knot DNS Resolver library"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Knot DNS Resolver 2.1.1 documentation</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2014-2018 CZ.NIC labs.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.6.7.
</div>
</body>
</html>
|