koffi 1.3.2 → 1.3.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CMakeLists.txt +27 -3
- package/ChangeLog.md +46 -14
- package/build/qemu/1.3.5/koffi_darwin_arm64.tar.gz +0 -0
- package/build/qemu/1.3.5/koffi_darwin_x64.tar.gz +0 -0
- package/build/qemu/1.3.5/koffi_freebsd_arm64.tar.gz +0 -0
- package/build/qemu/1.3.5/koffi_freebsd_ia32.tar.gz +0 -0
- package/build/qemu/1.3.5/koffi_freebsd_x64.tar.gz +0 -0
- package/build/qemu/1.3.5/koffi_linux_arm32hf.tar.gz +0 -0
- package/build/qemu/1.3.5/koffi_linux_arm64.tar.gz +0 -0
- package/build/qemu/1.3.5/koffi_linux_ia32.tar.gz +0 -0
- package/build/qemu/1.3.5/koffi_linux_riscv64hf64.tar.gz +0 -0
- package/build/qemu/1.3.5/koffi_linux_x64.tar.gz +0 -0
- package/build/qemu/1.3.5/koffi_openbsd_ia32.tar.gz +0 -0
- package/build/qemu/1.3.5/koffi_openbsd_x64.tar.gz +0 -0
- package/build/qemu/1.3.5/koffi_win32_arm64.tar.gz +0 -0
- package/build/qemu/1.3.5/koffi_win32_ia32.tar.gz +0 -0
- package/build/qemu/1.3.5/koffi_win32_x64.tar.gz +0 -0
- package/doc/_static/perf_linux_20220623.png +0 -0
- package/doc/_static/perf_linux_20220623_2.png +0 -0
- package/doc/_static/perf_windows_20220623.png +0 -0
- package/doc/_static/perf_windows_20220623_2.png +0 -0
- package/doc/benchmarks.md +40 -36
- package/doc/benchmarks.xlsx +0 -0
- package/doc/changes.md +2 -0
- package/doc/conf.py +10 -3
- package/doc/contribute.md +16 -0
- package/doc/dist/doctrees/benchmarks.doctree +0 -0
- package/doc/dist/doctrees/changes.doctree +0 -0
- package/doc/dist/doctrees/contribute.doctree +0 -0
- package/doc/dist/doctrees/environment.pickle +0 -0
- package/doc/dist/doctrees/functions.doctree +0 -0
- package/doc/dist/doctrees/index.doctree +0 -0
- package/doc/dist/doctrees/memory.doctree +0 -0
- package/doc/dist/doctrees/platforms.doctree +0 -0
- package/doc/dist/doctrees/start.doctree +0 -0
- package/doc/dist/doctrees/types.doctree +0 -0
- package/doc/dist/html/_sources/benchmarks.md.txt +40 -36
- package/doc/dist/html/_sources/changes.md.txt +2 -0
- package/doc/dist/html/_sources/contribute.md.txt +16 -0
- package/doc/dist/html/_sources/functions.md.txt +18 -14
- package/doc/dist/html/_sources/index.rst.txt +2 -1
- package/doc/dist/html/_sources/memory.md.txt +6 -3
- package/doc/dist/html/_sources/platforms.md.txt +2 -0
- package/doc/dist/html/_sources/start.md.txt +3 -3
- package/doc/dist/html/_sources/types.md.txt +10 -8
- package/doc/dist/html/_static/perf_linux_20220623.png +0 -0
- package/doc/dist/html/_static/perf_linux_20220623_2.png +0 -0
- package/doc/dist/html/_static/perf_windows_20220623.png +0 -0
- package/doc/dist/html/_static/perf_windows_20220623_2.png +0 -0
- package/doc/dist/html/_static/pygments.css +54 -54
- package/doc/dist/html/benchmarks.html +52 -20
- package/doc/dist/html/changes.html +391 -0
- package/doc/dist/html/contribute.html +24 -2
- package/doc/dist/html/functions.html +83 -84
- package/doc/dist/html/genindex.html +1 -0
- package/doc/dist/html/index.html +18 -3
- package/doc/dist/html/memory.html +11 -5
- package/doc/dist/html/objects.inv +0 -0
- package/doc/dist/html/platforms.html +3 -1
- package/doc/dist/html/search.html +1 -0
- package/doc/dist/html/searchindex.js +1 -1
- package/doc/dist/html/start.html +48 -47
- package/doc/dist/html/types.html +161 -159
- package/doc/functions.md +18 -14
- package/doc/index.rst +2 -1
- package/doc/memory.md +6 -3
- package/doc/platforms.md +2 -0
- package/doc/start.md +3 -3
- package/doc/types.md +10 -8
- package/package.json +2 -2
- package/qemu/qemu.js +1 -0
- package/qemu/registry/machines.json +6 -11
- package/src/abi_arm32.cc +9 -9
- package/src/abi_arm64.cc +9 -9
- package/src/abi_riscv64.cc +9 -9
- package/src/abi_x64_sysv.cc +9 -9
- package/src/abi_x64_win.cc +9 -9
- package/src/abi_x86.cc +9 -9
- package/src/call.cc +8 -7
- package/src/call.hh +6 -0
- package/src/ffi.cc +73 -22
- package/src/ffi.hh +11 -4
- package/src/parser.cc +1 -1
- package/src/util.hh +21 -1
- package/test/async.js +1 -1
- package/test/misc.c +20 -0
- package/test/sync.js +13 -3
- package/vendor/libcc/libcc.hh +1 -1
- package/build/qemu/1.3.2/koffi_darwin_arm64.tar.gz +0 -0
- package/build/qemu/1.3.2/koffi_darwin_x64.tar.gz +0 -0
- package/build/qemu/1.3.2/koffi_freebsd_arm64.tar.gz +0 -0
- package/build/qemu/1.3.2/koffi_freebsd_ia32.tar.gz +0 -0
- package/build/qemu/1.3.2/koffi_freebsd_x64.tar.gz +0 -0
- package/build/qemu/1.3.2/koffi_linux_arm32hf.tar.gz +0 -0
- package/build/qemu/1.3.2/koffi_linux_arm64.tar.gz +0 -0
- package/build/qemu/1.3.2/koffi_linux_ia32.tar.gz +0 -0
- package/build/qemu/1.3.2/koffi_linux_riscv64hf64.tar.gz +0 -0
- package/build/qemu/1.3.2/koffi_linux_x64.tar.gz +0 -0
- package/build/qemu/1.3.2/koffi_openbsd_ia32.tar.gz +0 -0
- package/build/qemu/1.3.2/koffi_openbsd_x64.tar.gz +0 -0
- package/build/qemu/1.3.2/koffi_win32_arm64.tar.gz +0 -0
- package/build/qemu/1.3.2/koffi_win32_ia32.tar.gz +0 -0
- package/build/qemu/1.3.2/koffi_win32_x64.tar.gz +0 -0
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
<head><meta charset="utf-8"/>
|
|
4
4
|
<meta name="viewport" content="width=device-width,initial-scale=1"/>
|
|
5
5
|
<meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
|
|
6
|
-
<link rel="index" title="Index" href="genindex" /><link rel="search" title="Search" href="search" /><link rel="prev" title="Benchmarks" href="benchmarks" />
|
|
6
|
+
<link rel="index" title="Index" href="genindex" /><link rel="search" title="Search" href="search" /><link rel="next" title="Changelog" href="changes" /><link rel="prev" title="Benchmarks" href="benchmarks" />
|
|
7
7
|
|
|
8
8
|
<meta name="generator" content="sphinx-5.0.1, furo 2022.06.04.1"/>
|
|
9
9
|
<title>Contributing - Koffi</title>
|
|
@@ -169,6 +169,7 @@
|
|
|
169
169
|
<li class="toctree-l1"><a class="reference internal" href="memory">Memory usage</a></li>
|
|
170
170
|
<li class="toctree-l1"><a class="reference internal" href="benchmarks">Benchmarks</a></li>
|
|
171
171
|
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Contributing</a></li>
|
|
172
|
+
<li class="toctree-l1"><a class="reference internal" href="changes">Changelog</a></li>
|
|
172
173
|
</ul>
|
|
173
174
|
|
|
174
175
|
</div>
|
|
@@ -212,6 +213,12 @@
|
|
|
212
213
|
<section id="build-from-source">
|
|
213
214
|
<h2>Build from source<a class="headerlink" href="#build-from-source" title="Permalink to this heading">#</a></h2>
|
|
214
215
|
<p>We provide prebuilt binaries, packaged in the NPM archive, so in most cases it should be as simple as <code class="docutils literal notranslate"><span class="pre">npm</span> <span class="pre">install</span> <span class="pre">koffi</span></code>. If you want to hack Koffi or use a specific platform, follow the instructions below.</p>
|
|
216
|
+
<p>Start by cloning the repository with <a class="reference external" href="https://git-scm.com/">Git</a>:</p>
|
|
217
|
+
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>git clone https://github.com/Koromix/luigi
|
|
218
|
+
<span class="nb">cd</span> luigi/koffi
|
|
219
|
+
</pre></div>
|
|
220
|
+
</div>
|
|
221
|
+
<p>As said before, this is a monorepository containg multiple projects, hence the name.</p>
|
|
215
222
|
<section id="windows">
|
|
216
223
|
<h3>Windows<a class="headerlink" href="#windows" title="Permalink to this heading">#</a></h3>
|
|
217
224
|
<p>First, make sure the following dependencies are met:</p>
|
|
@@ -299,8 +306,14 @@ node qemu.js stop
|
|
|
299
306
|
<li><p>Add support for unions</p></li>
|
|
300
307
|
<li><p>Provide better ways to automatically deal with caller/heap-allocated memory (strings, etc.)</p></li>
|
|
301
308
|
<li><p>Port Koffi to PowerPC (POWER9+) ABI</p></li>
|
|
309
|
+
<li><p>Fix assembly unwind and CFI directives for better debugging experience</p></li>
|
|
302
310
|
</ul>
|
|
303
311
|
</section>
|
|
312
|
+
<section id="code-style">
|
|
313
|
+
<h2>Code style<a class="headerlink" href="#code-style" title="Permalink to this heading">#</a></h2>
|
|
314
|
+
<p>Koffi is programmed in a mix of C++ and assembly code (architecture-specific code). It uses <a class="reference external" href="https://github.com/nodejs/node-addon-api">node-addon-api</a> (C++ N-API wrapper) to interact with Node.js.</p>
|
|
315
|
+
<p>My personal preference goes to a rather C-like C++ style, with careful use of templates (mainly for containers) and little object-oriented programming. I strongly prefer tagged unions and code locality over inheritance and virtual methods. Exceptions are disabled.</p>
|
|
316
|
+
</section>
|
|
304
317
|
</section>
|
|
305
318
|
|
|
306
319
|
</article>
|
|
@@ -308,7 +321,15 @@ node qemu.js stop
|
|
|
308
321
|
<footer>
|
|
309
322
|
|
|
310
323
|
<div class="related-pages">
|
|
311
|
-
|
|
324
|
+
<a class="next-page" href="changes">
|
|
325
|
+
<div class="page-info">
|
|
326
|
+
<div class="context">
|
|
327
|
+
<span>Next</span>
|
|
328
|
+
</div>
|
|
329
|
+
<div class="title">Changelog</div>
|
|
330
|
+
</div>
|
|
331
|
+
<svg><use href="#svg-arrow-right"></use></svg>
|
|
332
|
+
</a>
|
|
312
333
|
<a class="prev-page" href="benchmarks">
|
|
313
334
|
<svg><use href="#svg-arrow-right"></use></svg>
|
|
314
335
|
<div class="page-info">
|
|
@@ -361,6 +382,7 @@ node qemu.js stop
|
|
|
361
382
|
</li>
|
|
362
383
|
<li><a class="reference internal" href="#running-tests">Running tests</a></li>
|
|
363
384
|
<li><a class="reference internal" href="#todo-list">Todo list</a></li>
|
|
385
|
+
<li><a class="reference internal" href="#code-style">Code style</a></li>
|
|
364
386
|
</ul>
|
|
365
387
|
</li>
|
|
366
388
|
</ul>
|
|
@@ -169,6 +169,7 @@
|
|
|
169
169
|
<li class="toctree-l1"><a class="reference internal" href="memory">Memory usage</a></li>
|
|
170
170
|
<li class="toctree-l1"><a class="reference internal" href="benchmarks">Benchmarks</a></li>
|
|
171
171
|
<li class="toctree-l1"><a class="reference internal" href="contribute">Contributing</a></li>
|
|
172
|
+
<li class="toctree-l1"><a class="reference internal" href="changes">Changelog</a></li>
|
|
172
173
|
</ul>
|
|
173
174
|
|
|
174
175
|
</div>
|
|
@@ -206,38 +207,39 @@
|
|
|
206
207
|
<h1>Function calls<a class="headerlink" href="#function-calls" title="Permalink to this heading">#</a></h1>
|
|
207
208
|
<section id="function-definitions">
|
|
208
209
|
<h2>Function definitions<a class="headerlink" href="#function-definitions" title="Permalink to this heading">#</a></h2>
|
|
209
|
-
<p>To declare functions, start by loading the shared library with <code class="docutils literal notranslate"><span class="pre">koffi.load()</span></code>.</p>
|
|
210
|
-
<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span>
|
|
211
|
-
<span class="linenos">2</span><span class="kd">const</span>
|
|
210
|
+
<p>To declare functions, start by loading the shared library with <code class="docutils literal notranslate"><span class="pre">koffi.load(filename)</span></code>.</p>
|
|
211
|
+
<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span><span class="w"> </span><span class="nx">koffi</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">require</span><span class="p">(</span><span class="s1">'koffi'</span><span class="p">);</span><span class="w"></span>
|
|
212
|
+
<span class="linenos">2</span><span class="kd">const</span><span class="w"> </span><span class="nx">lib</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">koffi</span><span class="p">.</span><span class="nx">load</span><span class="p">(</span><span class="s1">'/path/to/shared/library'</span><span class="p">);</span><span class="w"> </span><span class="c1">// File extension depends on platforms: .so, .dll, .dylib, etc.</span><span class="w"></span>
|
|
212
213
|
</pre></div>
|
|
213
214
|
</div>
|
|
214
|
-
<p>You can use the returned object to load C functions from the library.
|
|
215
|
+
<p>You can use the returned object to load C functions from the library. To do so, you can use two syntaxes:</p>
|
|
215
216
|
<ul class="simple">
|
|
216
|
-
<li><p>
|
|
217
|
+
<li><p>The classic syntax, inspired by node-ffi</p></li>
|
|
217
218
|
<li><p>C-like prototypes</p></li>
|
|
218
219
|
</ul>
|
|
219
220
|
<section id="classic-syntax">
|
|
220
221
|
<h3>Classic syntax<a class="headerlink" href="#classic-syntax" title="Permalink to this heading">#</a></h3>
|
|
221
222
|
<p>To declare a function, you need to specify its non-mangled name, its return type, and its parameters. Use an ellipsis as the last parameter for variadic functions.</p>
|
|
222
|
-
<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span>
|
|
223
|
-
<span class="linenos">2</span><span class="kd">const</span>
|
|
223
|
+
<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span><span class="w"> </span><span class="nx">printf</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">'printf'</span><span class="p">,</span><span class="w"> </span><span class="s1">'int'</span><span class="p">,</span><span class="w"> </span><span class="p">[</span><span class="s1">'string'</span><span class="p">,</span><span class="w"> </span><span class="s1">'...'</span><span class="p">]);</span><span class="w"></span>
|
|
224
|
+
<span class="linenos">2</span><span class="kd">const</span><span class="w"> </span><span class="nx">atoi</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">'atoi'</span><span class="p">,</span><span class="w"> </span><span class="s1">'int'</span><span class="p">,</span><span class="w"> </span><span class="p">[</span><span class="s1">'string'</span><span class="p">]);</span><span class="w"></span>
|
|
224
225
|
</pre></div>
|
|
225
226
|
</div>
|
|
226
227
|
<p>Koffi automatically tries mangled names for non-standard x86 calling conventions. See the section <a class="reference internal" href="#synchronous-calls"><span class="std std-doc">on standard calls</span></a> for more information on this subject.</p>
|
|
227
228
|
</section>
|
|
228
229
|
<section id="c-like-prototypes">
|
|
229
230
|
<h3>C-like prototypes<a class="headerlink" href="#c-like-prototypes" title="Permalink to this heading">#</a></h3>
|
|
230
|
-
<p>
|
|
231
|
-
<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span>
|
|
232
|
-
<span class="linenos">2</span><span class="kd">const</span>
|
|
231
|
+
<p>If you prefer, you can declare functions using simple C-like prototype strings, as shown below:</p>
|
|
232
|
+
<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span><span class="w"> </span><span class="nx">printf</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">'int printf(const char *fmt, ...)'</span><span class="p">);</span><span class="w"></span>
|
|
233
|
+
<span class="linenos">2</span><span class="kd">const</span><span class="w"> </span><span class="nx">atoi</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">'int atoi(string)'</span><span class="p">);</span><span class="w"> </span><span class="c1">// The parameter name is not used by Koffi, and optional</span><span class="w"></span>
|
|
233
234
|
</pre></div>
|
|
234
235
|
</div>
|
|
236
|
+
<p>You can use <code class="docutils literal notranslate"><span class="pre">()</span></code> or <code class="docutils literal notranslate"><span class="pre">(void)</span></code> for functions that take no argument.</p>
|
|
235
237
|
</section>
|
|
236
238
|
</section>
|
|
237
239
|
<section id="synchronous-calls">
|
|
238
240
|
<h2>Synchronous calls<a class="headerlink" href="#synchronous-calls" title="Permalink to this heading">#</a></h2>
|
|
239
241
|
<p>By default, calling a C function happens synchronously.</p>
|
|
240
|
-
<p>Most architectures only support one procedure call standard per process. The 32-bit x86 platform is an exception to this, and Koffi
|
|
242
|
+
<p>Most architectures only support one procedure call standard per process. The 32-bit x86 platform is an exception to this, and Koffi supports several x86 conventions:</p>
|
|
241
243
|
<div class="table-wrapper colwidths-auto docutils container">
|
|
242
244
|
<table class="docutils align-default">
|
|
243
245
|
<thead>
|
|
@@ -272,32 +274,35 @@
|
|
|
272
274
|
</table>
|
|
273
275
|
</div>
|
|
274
276
|
<p>You can safely use these on non-x86 platforms, they are simply ignored.</p>
|
|
275
|
-
<p>Below you can find a small example showing how to use a non-default calling convention:</p>
|
|
276
|
-
<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span>
|
|
277
|
-
<span class="linenos">2</span><span class="kd">const</span>
|
|
277
|
+
<p>Below you can find a small example showing how to use a non-default calling convention, with the two syntaxes:</p>
|
|
278
|
+
<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span><span class="w"> </span><span class="nx">koffi</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">require</span><span class="p">(</span><span class="s1">'koffi'</span><span class="p">);</span><span class="w"></span>
|
|
279
|
+
<span class="linenos">2</span><span class="kd">const</span><span class="w"> </span><span class="nx">lib</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">koffi</span><span class="p">.</span><span class="nx">load</span><span class="p">(</span><span class="s1">'user32.dll'</span><span class="p">);</span><span class="w"></span>
|
|
278
280
|
<span class="linenos">3</span>
|
|
279
|
-
<span class="linenos">4</span><span class="c1">// The following two declarations are equivalent, and use Stdcall</span>
|
|
280
|
-
<span class="linenos">5</span><span class="kd">const</span>
|
|
281
|
-
<span class="linenos">6</span><span class="kd">const</span>
|
|
281
|
+
<span class="linenos">4</span><span class="c1">// The following two declarations are equivalent, and use Stdcall</span><span class="w"></span>
|
|
282
|
+
<span class="linenos">5</span><span class="kd">const</span><span class="w"> </span><span class="nx">MessageBoxA_1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">lib</span><span class="p">.</span><span class="nx">stdcall</span><span class="p">(</span><span class="s1">'MessageBoxA'</span><span class="p">,</span><span class="w"> </span><span class="s1">'int'</span><span class="p">,</span><span class="w"> </span><span class="p">[</span><span class="s1">'void *'</span><span class="p">,</span><span class="w"> </span><span class="s1">'string'</span><span class="p">,</span><span class="w"> </span><span class="s1">'string'</span><span class="p">,</span><span class="w"> </span><span class="s1">'uint'</span><span class="p">]);</span><span class="w"></span>
|
|
283
|
+
<span class="linenos">6</span><span class="kd">const</span><span class="w"> </span><span class="nx">MessageBoxA_2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">'int __stdcall MessageBoxA(void *hwnd, string text, string caption, uint type)'</span><span class="p">);</span><span class="w"></span>
|
|
282
284
|
</pre></div>
|
|
283
285
|
</div>
|
|
284
286
|
</section>
|
|
285
287
|
<section id="asynchronous-calls">
|
|
286
288
|
<h2>Asynchronous calls<a class="headerlink" href="#asynchronous-calls" title="Permalink to this heading">#</a></h2>
|
|
287
289
|
<p>You can issue asynchronous calls by calling the function through its async member. In this case, you need to provide a callback function as the last argument, with <code class="docutils literal notranslate"><span class="pre">(err,</span> <span class="pre">res)</span></code> parameters.</p>
|
|
288
|
-
<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="kd">const</span>
|
|
289
|
-
<span class="linenos"> 2</span><span class="kd">const</span>
|
|
290
|
+
<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="kd">const</span><span class="w"> </span><span class="nx">koffi</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">require</span><span class="p">(</span><span class="s1">'koffi'</span><span class="p">);</span><span class="w"></span>
|
|
291
|
+
<span class="linenos"> 2</span><span class="kd">const</span><span class="w"> </span><span class="nx">lib</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">koffi</span><span class="p">.</span><span class="nx">load</span><span class="p">(</span><span class="s1">'libc.so.6'</span><span class="p">);</span><span class="w"></span>
|
|
290
292
|
<span class="linenos"> 3</span>
|
|
291
|
-
<span class="linenos"> 4</span><span class="kd">const</span>
|
|
293
|
+
<span class="linenos"> 4</span><span class="kd">const</span><span class="w"> </span><span class="nx">atoi</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">'int atoi(const char *str)'</span><span class="p">);</span><span class="w"></span>
|
|
292
294
|
<span class="linenos"> 5</span>
|
|
293
|
-
<span class="linenos"> 6</span><span class="nx">atoi</span><span class="p">.</span><span class="k">async</span><span class="p">(</span><span class="s1">'1257'</span><span class="p">,</span>
|
|
294
|
-
<span class="linenos"> 7</span>
|
|
295
|
-
<span class="linenos"> 8</span><span class="p">})</span>
|
|
296
|
-
<span class="linenos"> 9</span><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s1">'Hello World!'</span><span class="p">);</span>
|
|
295
|
+
<span class="linenos"> 6</span><span class="nx">atoi</span><span class="p">.</span><span class="k">async</span><span class="p">(</span><span class="s1">'1257'</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="nx">err</span><span class="p">,</span><span class="w"> </span><span class="nx">res</span><span class="p">)</span><span class="w"> </span><span class="p">=></span><span class="w"> </span><span class="p">{</span><span class="w"></span>
|
|
296
|
+
<span class="linenos"> 7</span><span class="w"> </span><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s1">'Result:'</span><span class="p">,</span><span class="w"> </span><span class="nx">res</span><span class="p">);</span><span class="w"></span>
|
|
297
|
+
<span class="linenos"> 8</span><span class="p">})</span><span class="w"></span>
|
|
298
|
+
<span class="linenos"> 9</span><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s1">'Hello World!'</span><span class="p">);</span><span class="w"></span>
|
|
297
299
|
<span class="linenos">10</span>
|
|
298
|
-
<span class="linenos">11</span><span class="c1">// This program will print
|
|
300
|
+
<span class="linenos">11</span><span class="c1">// This program will print:</span><span class="w"></span>
|
|
301
|
+
<span class="linenos">12</span><span class="c1">// Hello World!</span><span class="w"></span>
|
|
302
|
+
<span class="linenos">13</span><span class="c1">// Result: 1257</span><span class="w"></span>
|
|
299
303
|
</pre></div>
|
|
300
304
|
</div>
|
|
305
|
+
<p>These calls are executed by worker threads. It is <strong>your responsibility to deal with data sharing issues</strong> in the native code that may be caused by multi-threading.</p>
|
|
301
306
|
<p>You can easily convert this callback-style async function to a promise-based version with <code class="docutils literal notranslate"><span class="pre">util.promisify()</span></code> from the Node.js standard library.</p>
|
|
302
307
|
<p>Variadic functions cannot be called asynchronously.</p>
|
|
303
308
|
</section>
|
|
@@ -305,10 +310,10 @@
|
|
|
305
310
|
<h2>Variadic functions<a class="headerlink" href="#variadic-functions" title="Permalink to this heading">#</a></h2>
|
|
306
311
|
<p>Variadic functions are declared with an ellipsis as the last argument.</p>
|
|
307
312
|
<p>In order to call a variadic function, you must provide two Javascript arguments for each additional C parameter, the first one is the expected type and the second one is the value.</p>
|
|
308
|
-
<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span>
|
|
313
|
+
<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span><span class="w"> </span><span class="nx">printf</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">'printf'</span><span class="p">,</span><span class="w"> </span><span class="s1">'int'</span><span class="p">,</span><span class="w"> </span><span class="p">[</span><span class="s1">'string'</span><span class="p">,</span><span class="w"> </span><span class="s1">'...'</span><span class="p">]);</span><span class="w"></span>
|
|
309
314
|
<span class="linenos">2</span>
|
|
310
|
-
<span class="linenos">3</span><span class="c1">// The variadic arguments are: 6 (int), 8.5 (double), 'THE END' (const char *)</span>
|
|
311
|
-
<span class="linenos">4</span><span class="nx">printf</span><span class="p">(</span><span class="s1">'Integer %d, double %g, string %s'</span><span class="p">,</span>
|
|
315
|
+
<span class="linenos">3</span><span class="c1">// The variadic arguments are: 6 (int), 8.5 (double), 'THE END' (const char *)</span><span class="w"></span>
|
|
316
|
+
<span class="linenos">4</span><span class="nx">printf</span><span class="p">(</span><span class="s1">'Integer %d, double %g, string %s'</span><span class="p">,</span><span class="w"> </span><span class="s1">'int'</span><span class="p">,</span><span class="w"> </span><span class="mf">6</span><span class="p">,</span><span class="w"> </span><span class="s1">'double'</span><span class="p">,</span><span class="w"> </span><span class="mf">8.5</span><span class="p">,</span><span class="w"> </span><span class="s1">'string'</span><span class="p">,</span><span class="w"> </span><span class="s1">'THE END'</span><span class="p">);</span><span class="w"></span>
|
|
312
317
|
</pre></div>
|
|
313
318
|
</div>
|
|
314
319
|
<p>On x86 platforms, only the Cdecl convention can be used for variadic functions.</p>
|
|
@@ -316,7 +321,7 @@
|
|
|
316
321
|
<section id="output-parameters">
|
|
317
322
|
<h2>Output parameters<a class="headerlink" href="#output-parameters" title="Permalink to this heading">#</a></h2>
|
|
318
323
|
<p>By default, Koffi will only forward arguments from Javascript to C. However, many C functions use pointer arguments for output values, or input/output values.</p>
|
|
319
|
-
<p>For
|
|
324
|
+
<p>For simplicity, and because Javascript only has value semantics for primitive types, Koffi can marshal out (or in/out) two types of parameters:</p>
|
|
320
325
|
<ul class="simple">
|
|
321
326
|
<li><p><a class="reference internal" href="types#struct-types"><span class="std std-doc">Structs</span></a> (to/from JS objects)</p></li>
|
|
322
327
|
<li><p><a class="reference internal" href="types#opaque-handles"><span class="std std-doc">Opaque handles</span></a></p></li>
|
|
@@ -334,65 +339,63 @@
|
|
|
334
339
|
<section id="struct-example">
|
|
335
340
|
<h3>Struct example<a class="headerlink" href="#struct-example" title="Permalink to this heading">#</a></h3>
|
|
336
341
|
<p>This example calls the POSIX function <code class="docutils literal notranslate"><span class="pre">gettimeofday()</span></code>, and uses the prototype-like syntax.</p>
|
|
337
|
-
<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="kd">const</span>
|
|
338
|
-
<span class="linenos"> 2</span><span class="kd">const</span>
|
|
342
|
+
<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="kd">const</span><span class="w"> </span><span class="nx">koffi</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">require</span><span class="p">(</span><span class="s1">'koffi'</span><span class="p">);</span><span class="w"></span>
|
|
343
|
+
<span class="linenos"> 2</span><span class="kd">const</span><span class="w"> </span><span class="nx">lib</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">koffi</span><span class="p">.</span><span class="nx">load</span><span class="p">(</span><span class="s1">'libc.so.6'</span><span class="p">);</span><span class="w"></span>
|
|
339
344
|
<span class="linenos"> 3</span>
|
|
340
|
-
<span class="linenos"> 4</span><span class="kd">const</span>
|
|
341
|
-
<span class="linenos"> 5</span>
|
|
342
|
-
<span class="linenos"> 6</span>
|
|
343
|
-
<span class="linenos"> 7</span><span class="p">});</span>
|
|
344
|
-
<span class="linenos"> 8</span><span class="kd">const</span>
|
|
345
|
-
<span class="linenos"> 9</span>
|
|
346
|
-
<span class="linenos">10</span>
|
|
347
|
-
<span class="linenos">11</span><span class="p">});</span>
|
|
345
|
+
<span class="linenos"> 4</span><span class="kd">const</span><span class="w"> </span><span class="nx">timeval</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">koffi</span><span class="p">.</span><span class="nx">struct</span><span class="p">(</span><span class="s1">'timeval'</span><span class="p">,</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
|
|
346
|
+
<span class="linenos"> 5</span><span class="w"> </span><span class="nx">tv_sec</span><span class="o">:</span><span class="w"> </span><span class="s1">'unsigned int'</span><span class="p">,</span><span class="w"></span>
|
|
347
|
+
<span class="linenos"> 6</span><span class="w"> </span><span class="nx">tv_usec</span><span class="o">:</span><span class="w"> </span><span class="s1">'unsigned int'</span><span class="w"></span>
|
|
348
|
+
<span class="linenos"> 7</span><span class="p">});</span><span class="w"></span>
|
|
349
|
+
<span class="linenos"> 8</span><span class="kd">const</span><span class="w"> </span><span class="nx">timezone</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">koffi</span><span class="p">.</span><span class="nx">struct</span><span class="p">(</span><span class="s1">'timezone'</span><span class="p">,</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
|
|
350
|
+
<span class="linenos"> 9</span><span class="w"> </span><span class="nx">tz_minuteswest</span><span class="o">:</span><span class="w"> </span><span class="s1">'int'</span><span class="p">,</span><span class="w"></span>
|
|
351
|
+
<span class="linenos">10</span><span class="w"> </span><span class="nx">tz_dsttime</span><span class="o">:</span><span class="w"> </span><span class="s1">'int'</span><span class="w"></span>
|
|
352
|
+
<span class="linenos">11</span><span class="p">});</span><span class="w"></span>
|
|
348
353
|
<span class="linenos">12</span>
|
|
349
|
-
<span class="linenos">13</span><span class="c1">// The _Out_ qualifiers instruct Koffi to marshal out the values</span>
|
|
350
|
-
<span class="linenos">14</span><span class="kd">const</span>
|
|
354
|
+
<span class="linenos">13</span><span class="c1">// The _Out_ qualifiers instruct Koffi to marshal out the values</span><span class="w"></span>
|
|
355
|
+
<span class="linenos">14</span><span class="kd">const</span><span class="w"> </span><span class="nx">gettimeofday</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">'int gettimeofday(_Out_ timeval *tv, _Out_ timezone *tz)'</span><span class="p">);</span><span class="w"></span>
|
|
351
356
|
<span class="linenos">15</span>
|
|
352
|
-
<span class="linenos">16</span><span class="kd">let</span>
|
|
353
|
-
<span class="linenos">17</span><span class="nx">gettimeofday</span><span class="p">(</span><span class="nx">tv</span><span class="p">,</span>
|
|
357
|
+
<span class="linenos">16</span><span class="kd">let</span><span class="w"> </span><span class="nx">tv</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{};</span><span class="w"></span>
|
|
358
|
+
<span class="linenos">17</span><span class="nx">gettimeofday</span><span class="p">(</span><span class="nx">tv</span><span class="p">,</span><span class="w"> </span><span class="kc">null</span><span class="p">);</span><span class="w"></span>
|
|
354
359
|
<span class="linenos">18</span>
|
|
355
|
-
<span class="linenos">19</span><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="nx">tv</span><span class="p">);</span>
|
|
360
|
+
<span class="linenos">19</span><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="nx">tv</span><span class="p">);</span><span class="w"></span>
|
|
356
361
|
</pre></div>
|
|
357
362
|
</div>
|
|
358
363
|
</section>
|
|
359
364
|
<section id="opaque-handle-example">
|
|
360
365
|
<h3>Opaque handle example<a class="headerlink" href="#opaque-handle-example" title="Permalink to this heading">#</a></h3>
|
|
361
366
|
<p>This example opens an in-memory SQLite database, and uses the node-ffi-style function declaration syntax.</p>
|
|
362
|
-
<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="kd">const</span>
|
|
363
|
-
<span class="linenos"> 2</span><span class="kd">const</span>
|
|
367
|
+
<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="kd">const</span><span class="w"> </span><span class="nx">koffi</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">require</span><span class="p">(</span><span class="s1">'koffi'</span><span class="p">);</span><span class="w"></span>
|
|
368
|
+
<span class="linenos"> 2</span><span class="kd">const</span><span class="w"> </span><span class="nx">lib</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">koffi</span><span class="p">.</span><span class="nx">load</span><span class="p">(</span><span class="s1">'sqlite.so'</span><span class="p">);</span><span class="w"></span>
|
|
364
369
|
<span class="linenos"> 3</span>
|
|
365
|
-
<span class="linenos"> 4</span><span class="kd">const</span>
|
|
370
|
+
<span class="linenos"> 4</span><span class="kd">const</span><span class="w"> </span><span class="nx">sqlite3_db</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">koffi</span><span class="p">.</span><span class="nx">handle</span><span class="p">(</span><span class="s1">'sqlite3_db'</span><span class="p">);</span><span class="w"></span>
|
|
366
371
|
<span class="linenos"> 5</span>
|
|
367
|
-
<span class="linenos"> 6</span><span class="c1">// Use koffi.out() on a pointer to copy out (from C to JS) after the call</span>
|
|
368
|
-
<span class="linenos"> 7</span><span class="kd">const</span>
|
|
372
|
+
<span class="linenos"> 6</span><span class="c1">// Use koffi.out() on a pointer to copy out (from C to JS) after the call</span><span class="w"></span>
|
|
373
|
+
<span class="linenos"> 7</span><span class="kd">const</span><span class="w"> </span><span class="nx">sqlite3_open_v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">'sqlite3_open_v2'</span><span class="p">,</span><span class="w"> </span><span class="s1">'int'</span><span class="p">,</span><span class="w"> </span><span class="p">[</span><span class="s1">'string'</span><span class="p">,</span><span class="w"> </span><span class="nx">koffi</span><span class="p">.</span><span class="nx">out</span><span class="p">(</span><span class="nx">koffi</span><span class="p">.</span><span class="nx">pointer</span><span class="p">(</span><span class="nx">sqlite3_db</span><span class="p">)),</span><span class="w"> </span><span class="s1">'int'</span><span class="p">,</span><span class="w"> </span><span class="s1">'string'</span><span class="p">]);</span><span class="w"></span>
|
|
369
374
|
<span class="linenos"> 8</span>
|
|
370
|
-
<span class="linenos"> 9</span><span class="kd">const</span>
|
|
371
|
-
<span class="linenos">10</span><span class="kd">const</span>
|
|
375
|
+
<span class="linenos"> 9</span><span class="kd">const</span><span class="w"> </span><span class="nx">SQLITE_OPEN_READWRITE</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mh">0x2</span><span class="p">;</span><span class="w"></span>
|
|
376
|
+
<span class="linenos">10</span><span class="kd">const</span><span class="w"> </span><span class="nx">SQLITE_OPEN_CREATE</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mh">0x4</span><span class="p">;</span><span class="w"></span>
|
|
372
377
|
<span class="linenos">11</span>
|
|
373
|
-
<span class="linenos">12</span><span class="kd">let</span>
|
|
374
|
-
<span class="linenos">13</span><span class="k">if</span>
|
|
375
|
-
<span class="linenos">14</span>
|
|
376
|
-
<span class="linenos">15</span><span class="nx">sqlite3_close_v2</span><span class="p">(</span><span class="nx">db</span><span class="p">);</span>
|
|
378
|
+
<span class="linenos">12</span><span class="kd">let</span><span class="w"> </span><span class="nx">db</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{};</span><span class="w"></span>
|
|
379
|
+
<span class="linenos">13</span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nx">sqlite3_open_v2</span><span class="p">(</span><span class="s1">':memory:'</span><span class="p">,</span><span class="w"> </span><span class="nx">db</span><span class="p">,</span><span class="w"> </span><span class="nx">SQLITE_OPEN_READWRITE</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="nx">SQLITE_OPEN_CREATE</span><span class="p">,</span><span class="w"> </span><span class="kc">null</span><span class="p">)</span><span class="w"> </span><span class="o">!=</span><span class="w"> </span><span class="mf">0</span><span class="p">)</span><span class="w"></span>
|
|
380
|
+
<span class="linenos">14</span><span class="w"> </span><span class="k">throw</span><span class="w"> </span><span class="ow">new</span><span class="w"> </span><span class="ne">Error</span><span class="p">(</span><span class="s1">'Failed to open database'</span><span class="p">);</span><span class="w"></span>
|
|
381
|
+
<span class="linenos">15</span><span class="nx">sqlite3_close_v2</span><span class="p">(</span><span class="nx">db</span><span class="p">);</span><span class="w"></span>
|
|
377
382
|
</pre></div>
|
|
378
383
|
</div>
|
|
379
384
|
</section>
|
|
380
385
|
</section>
|
|
381
386
|
<section id="javascript-callbacks">
|
|
382
387
|
<h2>Javascript callbacks<a class="headerlink" href="#javascript-callbacks" title="Permalink to this heading">#</a></h2>
|
|
383
|
-
<section id="using-callbacks">
|
|
384
|
-
<h3>Using callbacks<a class="headerlink" href="#using-callbacks" title="Permalink to this heading">#</a></h3>
|
|
385
388
|
<p>In order to pass a JS function to a C function expecting a callback, you must first create a callback type with the expected return type and parameters. The syntax is similar to the one used to load functions from a shared library.</p>
|
|
386
|
-
<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span>
|
|
389
|
+
<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span><span class="w"> </span><span class="nx">koffi</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">require</span><span class="p">(</span><span class="s1">'koffi'</span><span class="p">);</span><span class="w"></span>
|
|
387
390
|
<span class="linenos">2</span>
|
|
388
|
-
<span class="linenos">3</span><span class="c1">// With the classic syntax, this callback expects an integer and returns nothing</span>
|
|
389
|
-
<span class="linenos">4</span><span class="kd">const</span>
|
|
391
|
+
<span class="linenos">3</span><span class="c1">// With the classic syntax, this callback expects an integer and returns nothing</span><span class="w"></span>
|
|
392
|
+
<span class="linenos">4</span><span class="kd">const</span><span class="w"> </span><span class="nx">ExampleCallback</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">koffi</span><span class="p">.</span><span class="nx">callback</span><span class="p">(</span><span class="s1">'ExampleCallback'</span><span class="p">,</span><span class="w"> </span><span class="s1">'void'</span><span class="p">,</span><span class="w"> </span><span class="p">[</span><span class="s1">'int'</span><span class="p">]);</span><span class="w"></span>
|
|
390
393
|
<span class="linenos">5</span>
|
|
391
|
-
<span class="linenos">6</span><span class="c1">// With the prototype parser, this callback expects a double and float, and returns the sum as a double</span>
|
|
392
|
-
<span class="linenos">7</span><span class="kd">const</span>
|
|
394
|
+
<span class="linenos">6</span><span class="c1">// With the prototype parser, this callback expects a double and float, and returns the sum as a double</span><span class="w"></span>
|
|
395
|
+
<span class="linenos">7</span><span class="kd">const</span><span class="w"> </span><span class="nx">AddDoubleFloat</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">koffi</span><span class="p">.</span><span class="nx">callback</span><span class="p">(</span><span class="s1">'double AddDoubleFloat(double d, float f)'</span><span class="p">);</span><span class="w"></span>
|
|
393
396
|
</pre></div>
|
|
394
397
|
</div>
|
|
395
|
-
<p>Once your callback type is declared, you can use
|
|
398
|
+
<p>Once your callback type is declared, you can use it in struct definitions, or as function parameter and/or return type.</p>
|
|
396
399
|
<p>Here is a small example with the C part and the JS part.</p>
|
|
397
400
|
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="cp">#include</span><span class="w"> </span><span class="cpf"><string.h></span><span class="cp"></span>
|
|
398
401
|
<span class="linenos">2</span>
|
|
@@ -404,32 +407,31 @@
|
|
|
404
407
|
<span class="linenos">8</span><span class="p">}</span><span class="w"></span>
|
|
405
408
|
</pre></div>
|
|
406
409
|
</div>
|
|
407
|
-
<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="kd">const</span>
|
|
410
|
+
<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="kd">const</span><span class="w"> </span><span class="nx">koffi</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">require</span><span class="p">(</span><span class="s1">'koffi'</span><span class="p">);</span><span class="w"></span>
|
|
408
411
|
<span class="linenos"> 2</span>
|
|
409
|
-
<span class="linenos"> 3</span><span class="kd">const</span>
|
|
412
|
+
<span class="linenos"> 3</span><span class="kd">const</span><span class="w"> </span><span class="nx">TransferCallback</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">koffi</span><span class="p">.</span><span class="nx">callback</span><span class="p">(</span><span class="s1">'int TransferCallback(const char *str, int age)'</span><span class="p">);</span><span class="w"></span>
|
|
410
413
|
<span class="linenos"> 4</span>
|
|
411
|
-
<span class="linenos"> 5</span><span class="kd">const</span>
|
|
414
|
+
<span class="linenos"> 5</span><span class="kd">const</span><span class="w"> </span><span class="nx">TransferToJS</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">'int TransferToJS(const char *str, int age, TransferCallback cb)'</span><span class="p">);</span><span class="w"></span>
|
|
412
415
|
<span class="linenos"> 6</span>
|
|
413
|
-
<span class="linenos"> 7</span><span class="kd">let</span>
|
|
414
|
-
<span class="linenos"> 8</span>
|
|
415
|
-
<span class="linenos"> 9</span>
|
|
416
|
-
<span class="linenos">10</span>
|
|
417
|
-
<span class="linenos">11</span><span class="p">});</span>
|
|
418
|
-
<span class="linenos">12</span><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="nx">ret</span><span class="p">);</span>
|
|
416
|
+
<span class="linenos"> 7</span><span class="kd">let</span><span class="w"> </span><span class="nx">ret</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">TransferToJS</span><span class="p">(</span><span class="s1">'Niels'</span><span class="p">,</span><span class="w"> </span><span class="mf">27</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="nx">str</span><span class="p">,</span><span class="w"> </span><span class="nx">age</span><span class="p">)</span><span class="w"> </span><span class="p">=></span><span class="w"> </span><span class="p">{</span><span class="w"></span>
|
|
417
|
+
<span class="linenos"> 8</span><span class="w"> </span><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="nx">str</span><span class="p">);</span><span class="w"></span>
|
|
418
|
+
<span class="linenos"> 9</span><span class="w"> </span><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s1">'Your age is:'</span><span class="p">,</span><span class="w"> </span><span class="nx">age</span><span class="p">);</span><span class="w"></span>
|
|
419
|
+
<span class="linenos">10</span><span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="mf">42</span><span class="p">;</span><span class="w"></span>
|
|
420
|
+
<span class="linenos">11</span><span class="p">});</span><span class="w"></span>
|
|
421
|
+
<span class="linenos">12</span><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="nx">ret</span><span class="p">);</span><span class="w"></span>
|
|
419
422
|
<span class="linenos">13</span>
|
|
420
|
-
<span class="linenos">14</span><span class="c1">// This example prints:</span>
|
|
421
|
-
<span class="linenos">15</span><span class="c1">// Hello Niels!</span>
|
|
422
|
-
<span class="linenos">16</span><span class="c1">// Your age is: 27</span>
|
|
423
|
-
<span class="linenos">17</span><span class="c1">// 42</span>
|
|
423
|
+
<span class="linenos">14</span><span class="c1">// This example prints:</span><span class="w"></span>
|
|
424
|
+
<span class="linenos">15</span><span class="c1">// Hello Niels!</span><span class="w"></span>
|
|
425
|
+
<span class="linenos">16</span><span class="c1">// Your age is: 27</span><span class="w"></span>
|
|
426
|
+
<span class="linenos">17</span><span class="c1">// 42</span><span class="w"></span>
|
|
424
427
|
</pre></div>
|
|
425
428
|
</div>
|
|
426
429
|
<p>On x86 platforms, only Cdecl and Stdcall callbacks are supported.</p>
|
|
427
430
|
</section>
|
|
428
431
|
<section id="thread-safety">
|
|
429
|
-
<
|
|
430
|
-
<p>
|
|
431
|
-
<p>
|
|
432
|
-
</section>
|
|
432
|
+
<h2>Thread safety<a class="headerlink" href="#thread-safety" title="Permalink to this heading">#</a></h2>
|
|
433
|
+
<p>Asynchronous functions run on worker threads. You need to deal with thread safety issues if you share data between threads.</p>
|
|
434
|
+
<p>Callbacks must be called from the main thread, or more precisely from the same thread as the V8 intepreter. Calling a callback from another thread is undefined behavior, and will likely lead to a crash or a big mess. You’ve been warned!</p>
|
|
433
435
|
</section>
|
|
434
436
|
</section>
|
|
435
437
|
|
|
@@ -504,13 +506,10 @@
|
|
|
504
506
|
<li><a class="reference internal" href="#opaque-handle-example">Opaque handle example</a></li>
|
|
505
507
|
</ul>
|
|
506
508
|
</li>
|
|
507
|
-
<li><a class="reference internal" href="#javascript-callbacks">Javascript callbacks</a
|
|
508
|
-
<li><a class="reference internal" href="#using-callbacks">Using callbacks</a></li>
|
|
509
|
+
<li><a class="reference internal" href="#javascript-callbacks">Javascript callbacks</a></li>
|
|
509
510
|
<li><a class="reference internal" href="#thread-safety">Thread safety</a></li>
|
|
510
511
|
</ul>
|
|
511
512
|
</li>
|
|
512
|
-
</ul>
|
|
513
|
-
</li>
|
|
514
513
|
</ul>
|
|
515
514
|
|
|
516
515
|
</div>
|
|
@@ -167,6 +167,7 @@
|
|
|
167
167
|
<li class="toctree-l1"><a class="reference internal" href="memory">Memory usage</a></li>
|
|
168
168
|
<li class="toctree-l1"><a class="reference internal" href="benchmarks">Benchmarks</a></li>
|
|
169
169
|
<li class="toctree-l1"><a class="reference internal" href="contribute">Contributing</a></li>
|
|
170
|
+
<li class="toctree-l1"><a class="reference internal" href="changes">Changelog</a></li>
|
|
170
171
|
</ul>
|
|
171
172
|
|
|
172
173
|
</div>
|