Add Getting Started article
This commit is contained in:
Joshua Suskalo
parent
d0bfd20117
commit
4b490bf24f
8 changed files with 560 additions and 99 deletions
|
|
@ -11,6 +11,10 @@ doesn't remove the ability to write systems which minimize the cost of
|
|||
marshaling data and optimize for performance, to make use of the low-level
|
||||
access the FF&M API gives us.
|
||||
|
||||
- [Getting Started](igjoshua.github.io/coffi/01-Getting-Started.html)
|
||||
- [API Documentation](igjoshua.github.io/coffi/)
|
||||
- [Recent Changes](CHANGELOG.md)
|
||||
|
||||
## Installation
|
||||
This library is available on Clojars, or as a git dependency. Add one of the
|
||||
following entries to the `:deps` key of your `deps.edn`:
|
||||
|
|
@ -37,7 +41,7 @@ the following JVM arguments to your application.
|
|||
```
|
||||
|
||||
You can specify JVM arguments in a particular invocation of the Clojure CLI with
|
||||
the -J flag like so:
|
||||
the `-J` flag like so:
|
||||
|
||||
``` sh
|
||||
clj -J--enable-native-access=ALL-UNNAMED
|
||||
|
|
|
|||
1
deps.edn
1
deps.edn
|
|
@ -29,6 +29,7 @@
|
|||
:version "v1.0.486"
|
||||
:description "A Foreign Function Interface in Clojure for JDK 22+."
|
||||
:source-paths ["src/clj"]
|
||||
:doc-paths ["docs/articles"]
|
||||
:output-path "docs"
|
||||
:source-uri "https://github.com/IGJoshua/coffi/blob/{git-commit}/{filepath}#L{line}"
|
||||
:metadata {:doc/format :markdown}}}
|
||||
|
|
|
|||
147
docs/01-Getting-Started.html
Normal file
147
docs/01-Getting-Started.html
Normal file
|
|
@ -0,0 +1,147 @@
|
|||
<!DOCTYPE html PUBLIC ""
|
||||
"">
|
||||
<html><head><meta charset="UTF-8" /><title>Getting Started</title><link rel="stylesheet" type="text/css" href="css/default.css" /><link rel="stylesheet" type="text/css" href="css/highlight.css" /><script type="text/javascript" src="js/highlight.min.js"></script><script type="text/javascript" src="js/jquery.min.js"></script><script type="text/javascript" src="js/page_effects.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body><div id="header"><h2>Generated by <a href="https://github.com/weavejester/codox">Codox</a></h2><h1><a href="index.html"><span class="project-title"><span class="project-name">coffi</span> <span class="project-version">v1.0.486</span></span></a></h1></div><div class="sidebar primary"><h3 class="no-link"><span class="inner">Project</span></h3><ul class="index-link"><li class="depth-1 "><a href="index.html"><div class="inner">Index</div></a></li></ul><h3 class="no-link"><span class="inner">Topics</span></h3><ul><li class="depth-1 current"><a href="01-Getting-Started.html"><div class="inner"><span>Getting Started</span></div></a></li></ul><h3 class="no-link"><span class="inner">Namespaces</span></h3><ul><li class="depth-1"><div class="no-link"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>coffi</span></div></div></li><li class="depth-2 branch"><a href="coffi.ffi.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>ffi</span></div></a></li><li class="depth-2 branch"><a href="coffi.layout.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>layout</span></div></a></li><li class="depth-2"><a href="coffi.mem.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>mem</span></div></a></li></ul></div><div class="document" id="content"><div class="doc"><div class="markdown"><h1><a href="#getting-started" id="getting-started"></a>Getting Started</h1>
|
||||
<h2><a href="#installation" id="installation"></a>Installation</h2>
|
||||
<p>This library is available on Clojars. Add one of the following entries to the <code>:deps</code> key of your <code>deps.edn</code>:</p>
|
||||
<pre><code class="language-clojure">org.suskalo/coffi {:mvn/version "x.y.z"}
|
||||
io.github.IGJoshua/coffi {:git/tag "x.y.z" :git/sha "abcdef0"}
|
||||
</code></pre>
|
||||
<p>See GitHub for the <a href="https://github.com/IGJoshua/coffi/releases">latest releases</a>.</p>
|
||||
<p>If you use this library as a git dependency, you will need to prepare the library.</p>
|
||||
<pre><code class="language-sh">$ clj -X:deps prep
|
||||
</code></pre>
|
||||
<p>Coffi requires usage of the package <code>java.lang.foreign</code>, and most of the operations are considered unsafe by the JDK, and are therefore unavailable to your code without passing some command line flags. In order to use coffi, add the following JVM arguments to your application.</p>
|
||||
<pre><code class="language-sh">--enable-native-access=ALL-UNNAMED
|
||||
</code></pre>
|
||||
<p>You can specify JVM arguments in a particular invocation of the Clojure CLI with the -J flag like so:</p>
|
||||
<pre><code class="language-sh">clj -J--enable-native-access=ALL-UNNAMED
|
||||
</code></pre>
|
||||
<p>You can also specify them in an alias in your <code>deps.edn</code> file under the <code>:jvm-opts</code> key (see the next example) and then invoking the CLI with that alias using <code>-M</code>, <code>-A</code>, or <code>-X</code>.</p>
|
||||
<pre><code class="language-clojure">{:aliases {:dev {:jvm-opts ["--enable-native-access=ALL-UNNAMED"]}}}
|
||||
</code></pre>
|
||||
<p>Other build tools should provide similar functionality if you check their documentation.</p>
|
||||
<p>When creating an executable jar file, you can avoid the need to pass this argument by adding the manifest attribute <code>Enable-Native-Access: ALL-UNNAMED</code> to your jar.</p>
|
||||
<h2><a href="#basic-usage" id="basic-usage"></a>Basic Usage</h2>
|
||||
<p>There are two major components to coffi and interacting with native code: manipulating off-heap memory, and loading native code for use with Clojure.</p>
|
||||
<p>In the simplest cases, the native functions you call will work exclusively with built-in types, for example the function <code>strlen</code> from libc.</p>
|
||||
<pre><code class="language-clojure">(require '[coffi.mem :as mem :refer [defalias]])
|
||||
(require '[coffi.ffi :as ffi :refer [defcfn]])
|
||||
|
||||
(defcfn strlen
|
||||
"Given a string, measures its length in bytes."
|
||||
strlen [::mem/c-string] ::mem/long)
|
||||
|
||||
(strlen "hello")
|
||||
;; => 5
|
||||
</code></pre>
|
||||
<p>The first argument to <code>defcfn</code> is the name of the Clojure var that will hold the native function reference, followed by an optional docstring and attribute map, then the C function identifier, including the name of the native symbol, a vector of argument types, and the return type.</p>
|
||||
<p>If you wish to use a native function as an anonymous function, it can be done with the <code>cfn</code> function.</p>
|
||||
<pre><code class="language-clojure">((ffi/cfn "strlen" [::mem/c-string] ::mem/long) "hello")
|
||||
;; => 5
|
||||
</code></pre>
|
||||
<p>If you want to use functions from libraries other than libc, then you’ll need to load them. Two functions are provided for this, <code>load-system-library</code>, and <code>load-library</code>. <code>load-system-library</code> takes a string which represents the name of a library that should be loaded via system lookup.</p>
|
||||
<pre><code class="language-clojure">(ffi/load-system-library "z")
|
||||
</code></pre>
|
||||
<p>This will load libz from the appropriate place on the user’s load path.</p>
|
||||
<p>Alternatively, <code>load-library</code> takes a file path to a dynamically loaded library.</p>
|
||||
<pre><code class="language-clojure">(ffi/load-library "lib/libz.so")
|
||||
</code></pre>
|
||||
<p>This will load libz from the lib subdirectory of the current working directory. As you can see this requires the entire filename, including platform-specific file extensions.</p>
|
||||
<p>If a library is attempted to be loaded but doesn’t exist or otherwise can’t be loaded, an exception is thrown. This can be convenient as any namespace with a <code>load-library</code> call at the top level cannot be required without the library being able to be loaded.</p>
|
||||
<h3><a href="#primitive-types" id="primitive-types"></a>Primitive Types</h3>
|
||||
<p>Coffi defines a basic set of primitive types: - byte - short - int - long - char - float - double - pointer</p>
|
||||
<p>Each of these types maps to their C counterpart. Values of any of these primitive types except for <code>pointer</code> will be cast with their corresponding Clojure function when they are passed as arguments to native functions. Additionally, the <code>c-string</code> type is defined, although it is not primitive.</p>
|
||||
<h3><a href="#composite-types" id="composite-types"></a>Composite Types</h3>
|
||||
<p>In addition, some composite types are also defined in coffi, including struct and union types (unions will be discussed with serialization and deserialization). For an example C struct and function:</p>
|
||||
<pre><code class="language-c">typedef struct point {
|
||||
float x;
|
||||
float y;
|
||||
} Point;
|
||||
|
||||
Point zero(void) {
|
||||
Point res = {};
|
||||
|
||||
res.x = 0.0;
|
||||
res.y = 0.0;
|
||||
|
||||
return res;
|
||||
}
|
||||
</code></pre>
|
||||
<p>The corresponding coffi definition is like so:</p>
|
||||
<pre><code class="language-clojure">(defcfn zero-point
|
||||
"zero" [] [::mem/struct [[:x ::mem/float] [:y ::mem/float]]])
|
||||
|
||||
(zero-point)
|
||||
;; => {:x 0.0,
|
||||
;; :y 0.0}
|
||||
</code></pre>
|
||||
<p>Writing out struct definitions like this every time would get tedious, so the macro <code>defalias</code> is used to define a struct alias.</p>
|
||||
<pre><code class="language-clojure">(defalias ::point
|
||||
[::mem/struct
|
||||
[[:x ::mem/float]
|
||||
[:y ::mem/float]]])
|
||||
|
||||
(defcfn zero-point
|
||||
"zero" [] ::point)
|
||||
</code></pre>
|
||||
<p>Struct definitions do not include any padding by default. Functions for transforming struct types to include padding conforming to various standards can be found in <code>coffi.layout</code>.</p>
|
||||
<pre><code class="language-clojure">(require '[coffi.layout :as layout])
|
||||
|
||||
(defalias ::needs-padding
|
||||
(layout/with-c-layout
|
||||
[::mem/struct
|
||||
[[:a ::mem/char]
|
||||
[:x ::mem/float]]]))
|
||||
|
||||
(mem/size-of ::needs-padding)
|
||||
;; => 8
|
||||
|
||||
(mem/align-of ::needs-padding)
|
||||
;; => 4
|
||||
</code></pre>
|
||||
<p>Values deserialized with types produced from layout functions may include an extra <code>:coffi.layout/padding</code> key with a nil value.</p>
|
||||
<p>A limitation of the <code>defcfn</code> macro in its current form is that types provided to it must be provided in a literal form, not as an expression that evaluates to a type. This means that if you wish to use a layout function on a struct you must define an alias for it before the type can be used as a type in <code>defcfn</code>.</p>
|
||||
<p>In cases where a pointer to some data is required to pass as an argument to a native function, but doesn’t need to be read back in, the <code>pointer</code> primitive type can take a type argument.</p>
|
||||
<pre><code class="language-clojure">[::mem/pointer ::mem/int]
|
||||
</code></pre>
|
||||
<p>Arrays are also supported via a type argument. Keep in mind that they are the array itself, and not a pointer to the array like you might see in certain cases in C.</p>
|
||||
<pre><code class="language-clojure">[::mem/array ::mem/int 3]
|
||||
</code></pre>
|
||||
<h3><a href="#callbacks" id="callbacks"></a>Callbacks</h3>
|
||||
<p>In addition to these composite types, there is also support for Clojure functions.</p>
|
||||
<pre><code class="language-clojure">[::ffi/fn [::mem/c-string] ::mem/int]
|
||||
</code></pre>
|
||||
<p>Be aware though that if an exception is thrown out of a callback that is called from C, the JVM will crash. The resulting crash log should include the exception type and message in the registers section, but it’s important to be aware of all the same. Ideally you should test your callbacks before actually passing them to native code.</p>
|
||||
<p>When writing a wrapper library for a C library, it may be a good choice to wrap all passed Clojure functions in an additional function which catches all throwables, potentially notifies the user in some manner (e.g. logging), and returns a default value. This is on the wrapper library’s developer to decide when and where this is appropriate, as in some cases no reasonable default return value can be determined and it is most sensible to simply crash the JVM. This is the reason that coffi defaults to this behavior, as in the author’s opinion it is better to fail hard and fast rather than to attempt to produce a default and cause unexpected behavior later.</p>
|
||||
<p>Another important thing to keep in mind is the expected lifetime of the function that you pass to native code. For example it is perfectly fine to pass an anonymous function to a native function if the callback will never be called again once the native function returns. If however it saves the callback for later use the JVM may collect it prematurely, causing a crash when the callback is later called by native code.</p>
|
||||
<h3><a href="#variadic-functions" id="variadic-functions"></a>Variadic Functions</h3>
|
||||
<p>Some native functions can take any number of arguments, and in these cases coffi provides <code>vacfn-factory</code> (for “varargs C function factory”).</p>
|
||||
<pre><code class="language-clojure">(def printf-factory (ffi/vacfn-factory "printf" [::mem/c-string] ::mem/int))
|
||||
</code></pre>
|
||||
<p>This returns a function of the types of the rest of the arguments which itself returns a native function wrapper.</p>
|
||||
<pre><code class="language-clojure">(def print-int (printf-factory ::mem/int))
|
||||
|
||||
(print-int "Some integer: %d\n" 5)
|
||||
;; Some integer: 5
|
||||
</code></pre>
|
||||
<p>At the moment there is no equivalent to <code>defcfn</code> for varargs functions.</p>
|
||||
<p>Some native functions that are variadic use the type <code>va_list</code> to make it easier for other languages to call them in their FFI. At the time of writing, coffi does not support va-list, however it is a planned feature.</p>
|
||||
<h3><a href="#global-variables" id="global-variables"></a>Global Variables</h3>
|
||||
<p>Some libraries include global variables or constants accessible through symbols. To start with, constant values stored in symbols can be fetched with <code>const</code>, or the parallel macro <code>defconst</code></p>
|
||||
<pre><code class="language-clojure">(def some-const (ffi/const "some_const" ::mem/int))
|
||||
(ffi/defconst some-const "some_const" ::mem/int)
|
||||
</code></pre>
|
||||
<p>This value is fetched once when you call <code>const</code> and is turned into a Clojure value. If you need to refer to a global variable, then <code>static-variable</code> (or parallel <code>defvar</code>) can be used to create a reference to the native value.</p>
|
||||
<pre><code class="language-clojure">(def some-var (ffi/static-variable "some_var" ::mem/int))
|
||||
(ffi/defvar some-var "some_var" ::mem/int)
|
||||
</code></pre>
|
||||
<p>This variable is an <code>IDeref</code>. Each time you dereference it, the value will be deserialized from the native memory and returned. Additional functions are provided for mutating the variable.</p>
|
||||
<pre><code class="language-clojure">(ffi/freset! some-var 5)
|
||||
;; => 5
|
||||
@some-var
|
||||
;; => 5
|
||||
</code></pre>
|
||||
<p>Be aware however that there is no synchronization on these types. The value being read is not read atomically, so you may see an inconsistent state if the value is being mutated on another thread.</p>
|
||||
<p>A parallel function <code>fswap!</code> is also provided, but it does not provide any atomic semantics either.</p>
|
||||
<p>The memory that backs the static variable can be fetched with the function <code>static-variable-segment</code>, which can be used to pass a pointer to the static variable to native functions that require it.</p>
|
||||
</div></div></div></body></html>
|
||||
309
docs/articles/01-Getting-Started.md
Normal file
309
docs/articles/01-Getting-Started.md
Normal file
|
|
@ -0,0 +1,309 @@
|
|||
# Getting Started
|
||||
|
||||
## Installation
|
||||
This library is available on Clojars. Add one of the following entries to the
|
||||
`:deps` key of your `deps.edn`:
|
||||
|
||||
```clojure
|
||||
org.suskalo/coffi {:mvn/version "x.y.z"}
|
||||
io.github.IGJoshua/coffi {:git/tag "x.y.z" :git/sha "abcdef0"}
|
||||
```
|
||||
|
||||
See GitHub for the [latest releases](https://github.com/IGJoshua/coffi/releases).
|
||||
|
||||
If you use this library as a git dependency, you will need to prepare the
|
||||
library.
|
||||
|
||||
```sh
|
||||
$ clj -X:deps prep
|
||||
```
|
||||
|
||||
Coffi requires usage of the package `java.lang.foreign`, and most of the
|
||||
operations are considered unsafe by the JDK, and are therefore unavailable to
|
||||
your code without passing some command line flags. In order to use coffi, add
|
||||
the following JVM arguments to your application.
|
||||
|
||||
```sh
|
||||
--enable-native-access=ALL-UNNAMED
|
||||
```
|
||||
|
||||
You can specify JVM arguments in a particular invocation of the Clojure CLI with
|
||||
the -J flag like so:
|
||||
|
||||
``` sh
|
||||
clj -J--enable-native-access=ALL-UNNAMED
|
||||
```
|
||||
|
||||
You can also specify them in an alias in your `deps.edn` file under the
|
||||
`:jvm-opts` key (see the next example) and then invoking the CLI with that alias
|
||||
using `-M`, `-A`, or `-X`.
|
||||
|
||||
``` clojure
|
||||
{:aliases {:dev {:jvm-opts ["--enable-native-access=ALL-UNNAMED"]}}}
|
||||
```
|
||||
|
||||
Other build tools should provide similar functionality if you check their
|
||||
documentation.
|
||||
|
||||
When creating an executable jar file, you can avoid the need to pass this
|
||||
argument by adding the manifest attribute `Enable-Native-Access: ALL-UNNAMED` to
|
||||
your jar.
|
||||
|
||||
## Basic Usage
|
||||
There are two major components to coffi and interacting with native code:
|
||||
manipulating off-heap memory, and loading native code for use with Clojure.
|
||||
|
||||
In the simplest cases, the native functions you call will work exclusively with
|
||||
built-in types, for example the function `strlen` from libc.
|
||||
|
||||
```clojure
|
||||
(require '[coffi.mem :as mem :refer [defalias]])
|
||||
(require '[coffi.ffi :as ffi :refer [defcfn]])
|
||||
|
||||
(defcfn strlen
|
||||
"Given a string, measures its length in bytes."
|
||||
strlen [::mem/c-string] ::mem/long)
|
||||
|
||||
(strlen "hello")
|
||||
;; => 5
|
||||
```
|
||||
|
||||
The first argument to `defcfn` is the name of the Clojure var that will hold the
|
||||
native function reference, followed by an optional docstring and attribute map,
|
||||
then the C function identifier, including the name of the native symbol, a
|
||||
vector of argument types, and the return type.
|
||||
|
||||
If you wish to use a native function as an anonymous function, it can be done
|
||||
with the `cfn` function.
|
||||
|
||||
```clojure
|
||||
((ffi/cfn "strlen" [::mem/c-string] ::mem/long) "hello")
|
||||
;; => 5
|
||||
```
|
||||
|
||||
If you want to use functions from libraries other than libc, then you'll need to
|
||||
load them. Two functions are provided for this, `load-system-library`, and
|
||||
`load-library`. `load-system-library` takes a string which represents the name
|
||||
of a library that should be loaded via system lookup.
|
||||
|
||||
```clojure
|
||||
(ffi/load-system-library "z")
|
||||
```
|
||||
|
||||
This will load libz from the appropriate place on the user's load path.
|
||||
|
||||
Alternatively, `load-library` takes a file path to a dynamically loaded library.
|
||||
|
||||
```clojure
|
||||
(ffi/load-library "lib/libz.so")
|
||||
```
|
||||
|
||||
This will load libz from the lib subdirectory of the current working directory.
|
||||
As you can see this requires the entire filename, including platform-specific
|
||||
file extensions.
|
||||
|
||||
If a library is attempted to be loaded but doesn't exist or otherwise can't be
|
||||
loaded, an exception is thrown. This can be convenient as any namespace with a
|
||||
`load-library` call at the top level cannot be required without the library
|
||||
being able to be loaded.
|
||||
|
||||
### Primitive Types
|
||||
Coffi defines a basic set of primitive types:
|
||||
- byte
|
||||
- short
|
||||
- int
|
||||
- long
|
||||
- char
|
||||
- float
|
||||
- double
|
||||
- pointer
|
||||
|
||||
Each of these types maps to their C counterpart. Values of any of these
|
||||
primitive types except for `pointer` will be cast with their corresponding
|
||||
Clojure function when they are passed as arguments to native functions.
|
||||
Additionally, the `c-string` type is defined, although it is not primitive.
|
||||
|
||||
### Composite Types
|
||||
In addition, some composite types are also defined in coffi, including struct
|
||||
and union types (unions will be discussed with serialization and
|
||||
deserialization). For an example C struct and function:
|
||||
|
||||
```c
|
||||
typedef struct point {
|
||||
float x;
|
||||
float y;
|
||||
} Point;
|
||||
|
||||
Point zero(void) {
|
||||
Point res = {};
|
||||
|
||||
res.x = 0.0;
|
||||
res.y = 0.0;
|
||||
|
||||
return res;
|
||||
}
|
||||
```
|
||||
|
||||
The corresponding coffi definition is like so:
|
||||
|
||||
```clojure
|
||||
(defcfn zero-point
|
||||
"zero" [] [::mem/struct [[:x ::mem/float] [:y ::mem/float]]])
|
||||
|
||||
(zero-point)
|
||||
;; => {:x 0.0,
|
||||
;; :y 0.0}
|
||||
```
|
||||
|
||||
Writing out struct definitions like this every time would get tedious, so the
|
||||
macro `defalias` is used to define a struct alias.
|
||||
|
||||
```clojure
|
||||
(defalias ::point
|
||||
[::mem/struct
|
||||
[[:x ::mem/float]
|
||||
[:y ::mem/float]]])
|
||||
|
||||
(defcfn zero-point
|
||||
"zero" [] ::point)
|
||||
```
|
||||
|
||||
Struct definitions do not include any padding by default. Functions for
|
||||
transforming struct types to include padding conforming to various standards can
|
||||
be found in `coffi.layout`.
|
||||
|
||||
``` clojure
|
||||
(require '[coffi.layout :as layout])
|
||||
|
||||
(defalias ::needs-padding
|
||||
(layout/with-c-layout
|
||||
[::mem/struct
|
||||
[[:a ::mem/char]
|
||||
[:x ::mem/float]]]))
|
||||
|
||||
(mem/size-of ::needs-padding)
|
||||
;; => 8
|
||||
|
||||
(mem/align-of ::needs-padding)
|
||||
;; => 4
|
||||
```
|
||||
|
||||
Values deserialized with types produced from layout functions may include an
|
||||
extra `:coffi.layout/padding` key with a nil value.
|
||||
|
||||
A limitation of the `defcfn` macro in its current form is that types provided to
|
||||
it must be provided in a literal form, not as an expression that evaluates to a
|
||||
type. This means that if you wish to use a layout function on a struct you must
|
||||
define an alias for it before the type can be used as a type in `defcfn`.
|
||||
|
||||
In cases where a pointer to some data is required to pass as an argument to a
|
||||
native function, but doesn't need to be read back in, the `pointer` primitive
|
||||
type can take a type argument.
|
||||
|
||||
```clojure
|
||||
[::mem/pointer ::mem/int]
|
||||
```
|
||||
|
||||
Arrays are also supported via a type argument. Keep in mind that they are the
|
||||
array itself, and not a pointer to the array like you might see in certain cases
|
||||
in C.
|
||||
|
||||
```clojure
|
||||
[::mem/array ::mem/int 3]
|
||||
```
|
||||
|
||||
### Callbacks
|
||||
In addition to these composite types, there is also support for Clojure
|
||||
functions.
|
||||
|
||||
```clojure
|
||||
[::ffi/fn [::mem/c-string] ::mem/int]
|
||||
```
|
||||
|
||||
Be aware though that if an exception is thrown out of a callback that is called
|
||||
from C, the JVM will crash. The resulting crash log should include the exception
|
||||
type and message in the registers section, but it's important to be aware of all
|
||||
the same. Ideally you should test your callbacks before actually passing them to
|
||||
native code.
|
||||
|
||||
When writing a wrapper library for a C library, it may be a good choice to wrap
|
||||
all passed Clojure functions in an additional function which catches all
|
||||
throwables, potentially notifies the user in some manner (e.g. logging), and
|
||||
returns a default value. This is on the wrapper library's developer to decide
|
||||
when and where this is appropriate, as in some cases no reasonable default
|
||||
return value can be determined and it is most sensible to simply crash the JVM.
|
||||
This is the reason that coffi defaults to this behavior, as in the author's
|
||||
opinion it is better to fail hard and fast rather than to attempt to produce a
|
||||
default and cause unexpected behavior later.
|
||||
|
||||
Another important thing to keep in mind is the expected lifetime of the function
|
||||
that you pass to native code. For example it is perfectly fine to pass an
|
||||
anonymous function to a native function if the callback will never be called
|
||||
again once the native function returns. If however it saves the callback for
|
||||
later use the JVM may collect it prematurely, causing a crash when the callback
|
||||
is later called by native code.
|
||||
|
||||
### Variadic Functions
|
||||
Some native functions can take any number of arguments, and in these cases coffi
|
||||
provides `vacfn-factory` (for "varargs C function factory").
|
||||
|
||||
```clojure
|
||||
(def printf-factory (ffi/vacfn-factory "printf" [::mem/c-string] ::mem/int))
|
||||
```
|
||||
|
||||
This returns a function of the types of the rest of the arguments which itself
|
||||
returns a native function wrapper.
|
||||
|
||||
```clojure
|
||||
(def print-int (printf-factory ::mem/int))
|
||||
|
||||
(print-int "Some integer: %d\n" 5)
|
||||
;; Some integer: 5
|
||||
```
|
||||
|
||||
At the moment there is no equivalent to `defcfn` for varargs functions.
|
||||
|
||||
Some native functions that are variadic use the type `va_list` to make it easier
|
||||
for other languages to call them in their FFI. At the time of writing, coffi
|
||||
does not support va-list, however it is a planned feature.
|
||||
|
||||
### Global Variables
|
||||
Some libraries include global variables or constants accessible through symbols.
|
||||
To start with, constant values stored in symbols can be fetched with `const`, or
|
||||
the parallel macro `defconst`
|
||||
|
||||
```clojure
|
||||
(def some-const (ffi/const "some_const" ::mem/int))
|
||||
(ffi/defconst some-const "some_const" ::mem/int)
|
||||
```
|
||||
|
||||
This value is fetched once when you call `const` and is turned into a Clojure
|
||||
value. If you need to refer to a global variable, then `static-variable` (or
|
||||
parallel `defvar`) can be used to create a reference to the native value.
|
||||
|
||||
```clojure
|
||||
(def some-var (ffi/static-variable "some_var" ::mem/int))
|
||||
(ffi/defvar some-var "some_var" ::mem/int)
|
||||
```
|
||||
|
||||
This variable is an `IDeref`. Each time you dereference it, the value will be
|
||||
deserialized from the native memory and returned. Additional functions are
|
||||
provided for mutating the variable.
|
||||
|
||||
```clojure
|
||||
(ffi/freset! some-var 5)
|
||||
;; => 5
|
||||
@some-var
|
||||
;; => 5
|
||||
```
|
||||
|
||||
Be aware however that there is no synchronization on these types. The value
|
||||
being read is not read atomically, so you may see an inconsistent state if the
|
||||
value is being mutated on another thread.
|
||||
|
||||
A parallel function `fswap!` is also provided, but it does not provide any
|
||||
atomic semantics either.
|
||||
|
||||
The memory that backs the static variable can be fetched with the function
|
||||
`static-variable-segment`, which can be used to pass a pointer to the static
|
||||
variable to native functions that require it.
|
||||
|
|
@ -1,41 +1,41 @@
|
|||
<!DOCTYPE html PUBLIC ""
|
||||
"">
|
||||
<html><head><meta charset="UTF-8" /><title>coffi.ffi documentation</title><link rel="stylesheet" type="text/css" href="css/default.css" /><link rel="stylesheet" type="text/css" href="css/highlight.css" /><script type="text/javascript" src="js/highlight.min.js"></script><script type="text/javascript" src="js/jquery.min.js"></script><script type="text/javascript" src="js/page_effects.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body><div id="header"><h2>Generated by <a href="https://github.com/weavejester/codox">Codox</a></h2><h1><a href="index.html"><span class="project-title"><span class="project-name">coffi</span> <span class="project-version">v1.0.486</span></span></a></h1></div><div class="sidebar primary"><h3 class="no-link"><span class="inner">Project</span></h3><ul class="index-link"><li class="depth-1 "><a href="index.html"><div class="inner">Index</div></a></li></ul><h3 class="no-link"><span class="inner">Namespaces</span></h3><ul><li class="depth-1"><div class="no-link"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>coffi</span></div></div></li><li class="depth-2 branch current"><a href="coffi.ffi.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>ffi</span></div></a></li><li class="depth-2 branch"><a href="coffi.layout.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>layout</span></div></a></li><li class="depth-2"><a href="coffi.mem.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>mem</span></div></a></li></ul></div><div class="sidebar secondary"><h3><a href="#top"><span class="inner">Public Vars</span></a></h3><ul><li class="depth-1"><a href="coffi.ffi.html#var-cfn"><div class="inner"><span>cfn</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-const"><div class="inner"><span>const</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-defcfn"><div class="inner"><span>defcfn</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-defconst"><div class="inner"><span>defconst</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-defvar"><div class="inner"><span>defvar</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-ensure-symbol"><div class="inner"><span>ensure-symbol</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-find-symbol"><div class="inner"><span>find-symbol</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-freset.21"><div class="inner"><span>freset!</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-fswap.21"><div class="inner"><span>fswap!</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-load-library"><div class="inner"><span>load-library</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-load-system-library"><div class="inner"><span>load-system-library</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-make-downcall"><div class="inner"><span>make-downcall</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-make-serde-varargs-wrapper"><div class="inner"><span>make-serde-varargs-wrapper</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-make-serde-wrapper"><div class="inner"><span>make-serde-wrapper</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-make-varargs-factory"><div class="inner"><span>make-varargs-factory</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-reify-libspec"><div class="inner"><span>reify-libspec</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-reify-symbolspec"><div class="inner"><span>reify-symbolspec</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-static-variable"><div class="inner"><span>static-variable</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-static-variable-segment"><div class="inner"><span>static-variable-segment</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-vacfn-factory"><div class="inner"><span>vacfn-factory</span></div></a></li></ul></div><div class="namespace-docs" id="content"><h1 class="anchor" id="top">coffi.ffi</h1><div class="doc"><div class="markdown"><p>Functions for creating handles to native functions and loading native libraries.</p>
|
||||
<html><head><meta charset="UTF-8" /><title>coffi.ffi documentation</title><link rel="stylesheet" type="text/css" href="css/default.css" /><link rel="stylesheet" type="text/css" href="css/highlight.css" /><script type="text/javascript" src="js/highlight.min.js"></script><script type="text/javascript" src="js/jquery.min.js"></script><script type="text/javascript" src="js/page_effects.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body><div id="header"><h2>Generated by <a href="https://github.com/weavejester/codox">Codox</a></h2><h1><a href="index.html"><span class="project-title"><span class="project-name">coffi</span> <span class="project-version">v1.0.486</span></span></a></h1></div><div class="sidebar primary"><h3 class="no-link"><span class="inner">Project</span></h3><ul class="index-link"><li class="depth-1 "><a href="index.html"><div class="inner">Index</div></a></li></ul><h3 class="no-link"><span class="inner">Topics</span></h3><ul><li class="depth-1 "><a href="01-Getting-Started.html"><div class="inner"><span>Getting Started</span></div></a></li></ul><h3 class="no-link"><span class="inner">Namespaces</span></h3><ul><li class="depth-1"><div class="no-link"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>coffi</span></div></div></li><li class="depth-2 branch current"><a href="coffi.ffi.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>ffi</span></div></a></li><li class="depth-2 branch"><a href="coffi.layout.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>layout</span></div></a></li><li class="depth-2"><a href="coffi.mem.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>mem</span></div></a></li></ul></div><div class="sidebar secondary"><h3><a href="#top"><span class="inner">Public Vars</span></a></h3><ul><li class="depth-1"><a href="coffi.ffi.html#var-cfn"><div class="inner"><span>cfn</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-const"><div class="inner"><span>const</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-defcfn"><div class="inner"><span>defcfn</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-defconst"><div class="inner"><span>defconst</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-defvar"><div class="inner"><span>defvar</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-ensure-symbol"><div class="inner"><span>ensure-symbol</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-find-symbol"><div class="inner"><span>find-symbol</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-freset.21"><div class="inner"><span>freset!</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-fswap.21"><div class="inner"><span>fswap!</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-load-library"><div class="inner"><span>load-library</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-load-system-library"><div class="inner"><span>load-system-library</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-make-downcall"><div class="inner"><span>make-downcall</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-make-serde-varargs-wrapper"><div class="inner"><span>make-serde-varargs-wrapper</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-make-serde-wrapper"><div class="inner"><span>make-serde-wrapper</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-make-varargs-factory"><div class="inner"><span>make-varargs-factory</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-reify-libspec"><div class="inner"><span>reify-libspec</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-reify-symbolspec"><div class="inner"><span>reify-symbolspec</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-static-variable"><div class="inner"><span>static-variable</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-static-variable-segment"><div class="inner"><span>static-variable-segment</span></div></a></li><li class="depth-1"><a href="coffi.ffi.html#var-vacfn-factory"><div class="inner"><span>vacfn-factory</span></div></a></li></ul></div><div class="namespace-docs" id="content"><h1 class="anchor" id="top">coffi.ffi</h1><div class="doc"><div class="markdown"><p>Functions for creating handles to native functions and loading native libraries.</p>
|
||||
</div></div><div class="public anchor" id="var-cfn"><h3>cfn</h3><div class="usage"><code>(cfn symbol args ret)</code></div><div class="doc"><div class="markdown"><p>Constructs a Clojure function to call the native function referenced by <code>symbol</code>.</p>
|
||||
<p>The function returned will serialize any passed arguments into the <code>args</code> types, and deserialize the return to the <code>ret</code> type.</p>
|
||||
<p>If your <code>args</code> and <code>ret</code> are constants, then it is more efficient to call <a href="coffi.ffi.html#var-make-downcall">make-downcall</a> followed by <a href="coffi.ffi.html#var-make-serde-wrapper">make-serde-wrapper</a> because the latter has an inline definition which will result in less overhead from serdes.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/a377c97c93a311a43100a5e05567680e6ae3c2de/src/clj/coffi/ffi.clj#L438">view source</a></div></div><div class="public anchor" id="var-const"><h3>const</h3><div class="usage"><code>(const symbol-or-addr type)</code></div><div class="doc"><div class="markdown"><p>Gets the value of a constant stored in <code>symbol-or-addr</code>.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/a377c97c93a311a43100a5e05567680e6ae3c2de/src/clj/coffi/ffi.clj#L606">view source</a></div></div><div class="public anchor" id="var-defcfn"><h3>defcfn</h3><h4 class="type">macro</h4><div class="usage"><code>(defcfn name docstring? attr-map? symbol arg-types ret-type)</code><code>(defcfn name docstring? attr-map? symbol arg-types ret-type native-fn & fn-tail)</code></div><div class="doc"><div class="markdown"><p>Defines a Clojure function which maps to a native function.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/be58ac5d8037811e7d5bbb55045042a2b5a32c18/src/clj/coffi/ffi.clj#L438">view source</a></div></div><div class="public anchor" id="var-const"><h3>const</h3><div class="usage"><code>(const symbol-or-addr type)</code></div><div class="doc"><div class="markdown"><p>Gets the value of a constant stored in <code>symbol-or-addr</code>.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/be58ac5d8037811e7d5bbb55045042a2b5a32c18/src/clj/coffi/ffi.clj#L606">view source</a></div></div><div class="public anchor" id="var-defcfn"><h3>defcfn</h3><h4 class="type">macro</h4><div class="usage"><code>(defcfn name docstring? attr-map? symbol arg-types ret-type)</code><code>(defcfn name docstring? attr-map? symbol arg-types ret-type native-fn & fn-tail)</code></div><div class="doc"><div class="markdown"><p>Defines a Clojure function which maps to a native function.</p>
|
||||
<p><code>name</code> is the symbol naming the resulting var. <code>symbol</code> is a symbol or string naming the library symbol to link against. <code>arg-types</code> is a vector of qualified keywords representing the argument types. <code>ret-type</code> is a single qualified keyword representing the return type. <code>fn-tail</code> is the body of the function (potentially with multiple arities) which wraps the native one. Inside the function, <code>native-fn</code> is bound to a function that will serialize its arguments, call the native function, and deserialize its return type. If any body is present, you must call this function in order to call the native code.</p>
|
||||
<p>If no <code>fn-tail</code> is provided, then the resulting function will simply serialize the arguments according to <code>arg-types</code>, call the native function, and deserialize the return value.</p>
|
||||
<p>The number of args in the <code>fn-tail</code> need not match the number of <code>arg-types</code> for the native function. It need only call the native wrapper function with the correct arguments.</p>
|
||||
<p>See <a href="coffi.mem.html#var-serialize">serialize</a>, <a href="coffi.mem.html#var-deserialize">deserialize</a>, <a href="coffi.ffi.html#var-make-downcall">make-downcall</a>.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/a377c97c93a311a43100a5e05567680e6ae3c2de/src/clj/coffi/ffi.clj#L780">view source</a></div></div><div class="public anchor" id="var-defconst"><h3>defconst</h3><h4 class="type">macro</h4><div class="usage"><code>(defconst symbol docstring? symbol-or-addr type)</code></div><div class="doc"><div class="markdown"><p>Defines a var named by <code>symbol</code> to be the value of the given <code>type</code> from <code>symbol-or-addr</code>.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/a377c97c93a311a43100a5e05567680e6ae3c2de/src/clj/coffi/ffi.clj#L617">view source</a></div></div><div class="public anchor" id="var-defvar"><h3>defvar</h3><h4 class="type">macro</h4><div class="usage"><code>(defvar symbol docstring? symbol-or-addr type)</code></div><div class="doc"><div class="markdown"><p>Defines a var named by <code>symbol</code> to be a reference to the native memory from <code>symbol-or-addr</code>.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/a377c97c93a311a43100a5e05567680e6ae3c2de/src/clj/coffi/ffi.clj#L683">view source</a></div></div><div class="public anchor" id="var-ensure-symbol"><h3>ensure-symbol</h3><div class="usage"><code>(ensure-symbol symbol-or-addr)</code></div><div class="doc"><div class="markdown"><p>Returns the argument if it is a <a href="null">MemorySegment</a>, otherwise calls <a href="coffi.ffi.html#var-find-symbol">find-symbol</a> on it.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/a377c97c93a311a43100a5e05567680e6ae3c2de/src/clj/coffi/ffi.clj#L198">view source</a></div></div><div class="public anchor" id="var-find-symbol"><h3>find-symbol</h3><div class="usage"><code>(find-symbol sym)</code></div><div class="doc"><div class="markdown"><p>Gets the <a href="null">MemorySegment</a> of a symbol from the loaded libraries.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/a377c97c93a311a43100a5e05567680e6ae3c2de/src/clj/coffi/ffi.clj#L38">view source</a></div></div><div class="public anchor" id="var-freset.21"><h3>freset!</h3><div class="usage"><code>(freset! static-var newval)</code></div><div class="doc"><div class="markdown"><p>Sets the value of <code>static-var</code> to <code>newval</code>, running it through <a href="coffi.mem.html#var-serialize">serialize</a>.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/a377c97c93a311a43100a5e05567680e6ae3c2de/src/clj/coffi/ffi.clj#L647">view source</a></div></div><div class="public anchor" id="var-fswap.21"><h3>fswap!</h3><div class="usage"><code>(fswap! static-var f & args)</code></div><div class="doc"><div class="markdown"><p>Non-atomically runs the function <code>f</code> over the value stored in <code>static-var</code>.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/be58ac5d8037811e7d5bbb55045042a2b5a32c18/src/clj/coffi/ffi.clj#L780">view source</a></div></div><div class="public anchor" id="var-defconst"><h3>defconst</h3><h4 class="type">macro</h4><div class="usage"><code>(defconst symbol docstring? symbol-or-addr type)</code></div><div class="doc"><div class="markdown"><p>Defines a var named by <code>symbol</code> to be the value of the given <code>type</code> from <code>symbol-or-addr</code>.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/be58ac5d8037811e7d5bbb55045042a2b5a32c18/src/clj/coffi/ffi.clj#L617">view source</a></div></div><div class="public anchor" id="var-defvar"><h3>defvar</h3><h4 class="type">macro</h4><div class="usage"><code>(defvar symbol docstring? symbol-or-addr type)</code></div><div class="doc"><div class="markdown"><p>Defines a var named by <code>symbol</code> to be a reference to the native memory from <code>symbol-or-addr</code>.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/be58ac5d8037811e7d5bbb55045042a2b5a32c18/src/clj/coffi/ffi.clj#L683">view source</a></div></div><div class="public anchor" id="var-ensure-symbol"><h3>ensure-symbol</h3><div class="usage"><code>(ensure-symbol symbol-or-addr)</code></div><div class="doc"><div class="markdown"><p>Returns the argument if it is a <a href="null">MemorySegment</a>, otherwise calls <a href="coffi.ffi.html#var-find-symbol">find-symbol</a> on it.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/be58ac5d8037811e7d5bbb55045042a2b5a32c18/src/clj/coffi/ffi.clj#L198">view source</a></div></div><div class="public anchor" id="var-find-symbol"><h3>find-symbol</h3><div class="usage"><code>(find-symbol sym)</code></div><div class="doc"><div class="markdown"><p>Gets the <a href="null">MemorySegment</a> of a symbol from the loaded libraries.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/be58ac5d8037811e7d5bbb55045042a2b5a32c18/src/clj/coffi/ffi.clj#L38">view source</a></div></div><div class="public anchor" id="var-freset.21"><h3>freset!</h3><div class="usage"><code>(freset! static-var newval)</code></div><div class="doc"><div class="markdown"><p>Sets the value of <code>static-var</code> to <code>newval</code>, running it through <a href="coffi.mem.html#var-serialize">serialize</a>.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/be58ac5d8037811e7d5bbb55045042a2b5a32c18/src/clj/coffi/ffi.clj#L647">view source</a></div></div><div class="public anchor" id="var-fswap.21"><h3>fswap!</h3><div class="usage"><code>(fswap! static-var f & args)</code></div><div class="doc"><div class="markdown"><p>Non-atomically runs the function <code>f</code> over the value stored in <code>static-var</code>.</p>
|
||||
<p>The value is deserialized before passing it to <code>f</code>, and serialized before putting the value into <code>static-var</code>.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/a377c97c93a311a43100a5e05567680e6ae3c2de/src/clj/coffi/ffi.clj#L656">view source</a></div></div><div class="public anchor" id="var-load-library"><h3>load-library</h3><div class="usage"><code>(load-library path)</code></div><div class="doc"><div class="markdown"><p>Loads the library at <code>path</code>.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/a377c97c93a311a43100a5e05567680e6ae3c2de/src/clj/coffi/ffi.clj#L33">view source</a></div></div><div class="public anchor" id="var-load-system-library"><h3>load-system-library</h3><div class="usage"><code>(load-system-library libname)</code></div><div class="doc"><div class="markdown"><p>Loads the library named <code>libname</code> from the system’s load path.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/a377c97c93a311a43100a5e05567680e6ae3c2de/src/clj/coffi/ffi.clj#L28">view source</a></div></div><div class="public anchor" id="var-make-downcall"><h3>make-downcall</h3><div class="usage"><code>(make-downcall symbol-or-addr args ret)</code></div><div class="doc"><div class="markdown"><p>Constructs a downcall function reference to <code>symbol-or-addr</code> with the given <code>args</code> and <code>ret</code> types.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/be58ac5d8037811e7d5bbb55045042a2b5a32c18/src/clj/coffi/ffi.clj#L656">view source</a></div></div><div class="public anchor" id="var-load-library"><h3>load-library</h3><div class="usage"><code>(load-library path)</code></div><div class="doc"><div class="markdown"><p>Loads the library at <code>path</code>.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/be58ac5d8037811e7d5bbb55045042a2b5a32c18/src/clj/coffi/ffi.clj#L33">view source</a></div></div><div class="public anchor" id="var-load-system-library"><h3>load-system-library</h3><div class="usage"><code>(load-system-library libname)</code></div><div class="doc"><div class="markdown"><p>Loads the library named <code>libname</code> from the system’s load path.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/be58ac5d8037811e7d5bbb55045042a2b5a32c18/src/clj/coffi/ffi.clj#L28">view source</a></div></div><div class="public anchor" id="var-make-downcall"><h3>make-downcall</h3><div class="usage"><code>(make-downcall symbol-or-addr args ret)</code></div><div class="doc"><div class="markdown"><p>Constructs a downcall function reference to <code>symbol-or-addr</code> with the given <code>args</code> and <code>ret</code> types.</p>
|
||||
<p>The function returned takes only arguments whose types match exactly the <a href="coffi.mem.html#var-java-layout">java-layout</a> for that type, and returns an argument with exactly the <a href="coffi.mem.html#var-java-layout">java-layout</a> of the <code>ret</code> type. This function will perform no serialization or deserialization of arguments or the return type.</p>
|
||||
<p>If the <code>ret</code> type is non-primitive, then the returned function will take a first argument of a <a href="null">SegmentAllocator</a>.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/a377c97c93a311a43100a5e05567680e6ae3c2de/src/clj/coffi/ffi.clj#L206">view source</a></div></div><div class="public anchor" id="var-make-serde-varargs-wrapper"><h3>make-serde-varargs-wrapper</h3><div class="usage"><code>(make-serde-varargs-wrapper varargs-factory required-args ret-type)</code></div><div class="doc"><div class="markdown"><p>Constructs a wrapper function for the <code>varargs-factory</code> which produces functions that serialize the arguments and deserialize the return value.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/a377c97c93a311a43100a5e05567680e6ae3c2de/src/clj/coffi/ffi.clj#L426">view source</a></div></div><div class="public anchor" id="var-make-serde-wrapper"><h3>make-serde-wrapper</h3><div class="usage"><code>(make-serde-wrapper downcall arg-types ret-type)</code></div><div class="doc"><div class="markdown"><p>Constructs a wrapper function for the <code>downcall</code> which serializes the arguments and deserializes the return value.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/a377c97c93a311a43100a5e05567680e6ae3c2de/src/clj/coffi/ffi.clj#L407">view source</a></div></div><div class="public anchor" id="var-make-varargs-factory"><h3>make-varargs-factory</h3><div class="usage"><code>(make-varargs-factory symbol required-args ret)</code></div><div class="doc"><div class="markdown"><p>Returns a function for constructing downcalls with additional types for arguments.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/be58ac5d8037811e7d5bbb55045042a2b5a32c18/src/clj/coffi/ffi.clj#L206">view source</a></div></div><div class="public anchor" id="var-make-serde-varargs-wrapper"><h3>make-serde-varargs-wrapper</h3><div class="usage"><code>(make-serde-varargs-wrapper varargs-factory required-args ret-type)</code></div><div class="doc"><div class="markdown"><p>Constructs a wrapper function for the <code>varargs-factory</code> which produces functions that serialize the arguments and deserialize the return value.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/be58ac5d8037811e7d5bbb55045042a2b5a32c18/src/clj/coffi/ffi.clj#L426">view source</a></div></div><div class="public anchor" id="var-make-serde-wrapper"><h3>make-serde-wrapper</h3><div class="usage"><code>(make-serde-wrapper downcall arg-types ret-type)</code></div><div class="doc"><div class="markdown"><p>Constructs a wrapper function for the <code>downcall</code> which serializes the arguments and deserializes the return value.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/be58ac5d8037811e7d5bbb55045042a2b5a32c18/src/clj/coffi/ffi.clj#L407">view source</a></div></div><div class="public anchor" id="var-make-varargs-factory"><h3>make-varargs-factory</h3><div class="usage"><code>(make-varargs-factory symbol required-args ret)</code></div><div class="doc"><div class="markdown"><p>Returns a function for constructing downcalls with additional types for arguments.</p>
|
||||
<p>The <code>required-args</code> are the types of the first arguments passed to the downcall handle, and the values passed to the returned function are only the varargs types.</p>
|
||||
<p>The returned function is memoized, so that only one downcall function will be generated per combination of argument types.</p>
|
||||
<p>See <a href="coffi.ffi.html#var-make-downcall">make-downcall</a>.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/a377c97c93a311a43100a5e05567680e6ae3c2de/src/clj/coffi/ffi.clj#L222">view source</a></div></div><div class="public anchor" id="var-reify-libspec"><h3>reify-libspec</h3><div class="usage"><code>(reify-libspec libspec)</code></div><div class="doc"><div class="markdown"><p>Loads all the symbols specified in the <code>libspec</code>.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/be58ac5d8037811e7d5bbb55045042a2b5a32c18/src/clj/coffi/ffi.clj#L222">view source</a></div></div><div class="public anchor" id="var-reify-libspec"><h3>reify-libspec</h3><div class="usage"><code>(reify-libspec libspec)</code></div><div class="doc"><div class="markdown"><p>Loads all the symbols specified in the <code>libspec</code>.</p>
|
||||
<p>The value of each key of the passed map is transformed as by <a href="coffi.ffi.html#var-reify-symbolspec">reify-symbolspec</a>.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/a377c97c93a311a43100a5e05567680e6ae3c2de/src/clj/coffi/ffi.clj#L742">view source</a></div></div><div class="public anchor" id="var-reify-symbolspec"><h3>reify-symbolspec</h3><h4 class="type">multimethod</h4><div class="usage"></div><div class="doc"><div class="markdown"><p>Takes a spec for a symbol reference and returns a live value for that type.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/a377c97c93a311a43100a5e05567680e6ae3c2de/src/clj/coffi/ffi.clj#L701">view source</a></div></div><div class="public anchor" id="var-static-variable"><h3>static-variable</h3><div class="usage"><code>(static-variable symbol-or-addr type)</code></div><div class="doc"><div class="markdown"><p>Constructs a reference to a mutable value stored in <code>symbol-or-addr</code>.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/be58ac5d8037811e7d5bbb55045042a2b5a32c18/src/clj/coffi/ffi.clj#L742">view source</a></div></div><div class="public anchor" id="var-reify-symbolspec"><h3>reify-symbolspec</h3><h4 class="type">multimethod</h4><div class="usage"></div><div class="doc"><div class="markdown"><p>Takes a spec for a symbol reference and returns a live value for that type.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/be58ac5d8037811e7d5bbb55045042a2b5a32c18/src/clj/coffi/ffi.clj#L701">view source</a></div></div><div class="public anchor" id="var-static-variable"><h3>static-variable</h3><div class="usage"><code>(static-variable symbol-or-addr type)</code></div><div class="doc"><div class="markdown"><p>Constructs a reference to a mutable value stored in <code>symbol-or-addr</code>.</p>
|
||||
<p>The returned value can be dereferenced, and has metadata.</p>
|
||||
<p>See <a href="coffi.ffi.html#var-freset.21">freset!</a>, <a href="coffi.ffi.html#var-fswap.21">fswap!</a>.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/a377c97c93a311a43100a5e05567680e6ae3c2de/src/clj/coffi/ffi.clj#L672">view source</a></div></div><div class="public anchor" id="var-static-variable-segment"><h3>static-variable-segment</h3><div class="usage"><code>(static-variable-segment static-var)</code></div><div class="doc"><div class="markdown"><p>Gets the backing <a href="null">MemorySegment</a> from <code>static-var</code>.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/be58ac5d8037811e7d5bbb55045042a2b5a32c18/src/clj/coffi/ffi.clj#L672">view source</a></div></div><div class="public anchor" id="var-static-variable-segment"><h3>static-variable-segment</h3><div class="usage"><code>(static-variable-segment static-var)</code></div><div class="doc"><div class="markdown"><p>Gets the backing <a href="null">MemorySegment</a> from <code>static-var</code>.</p>
|
||||
<p>This is primarily useful when you need to pass the static variable’s address to a native function which takes an <a href="null">Addressable</a>.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/a377c97c93a311a43100a5e05567680e6ae3c2de/src/clj/coffi/ffi.clj#L664">view source</a></div></div><div class="public anchor" id="var-vacfn-factory"><h3>vacfn-factory</h3><div class="usage"><code>(vacfn-factory symbol required-args ret)</code></div><div class="doc"><div class="markdown"><p>Constructs a varargs factory to call the native function referenced by <code>symbol</code>.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/be58ac5d8037811e7d5bbb55045042a2b5a32c18/src/clj/coffi/ffi.clj#L664">view source</a></div></div><div class="public anchor" id="var-vacfn-factory"><h3>vacfn-factory</h3><div class="usage"><code>(vacfn-factory symbol required-args ret)</code></div><div class="doc"><div class="markdown"><p>Constructs a varargs factory to call the native function referenced by <code>symbol</code>.</p>
|
||||
<p>The function returned takes any number of type arguments and returns a specialized Clojure function for calling the native function with those arguments.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/a377c97c93a311a43100a5e05567680e6ae3c2de/src/clj/coffi/ffi.clj#L453">view source</a></div></div></div></body></html>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/be58ac5d8037811e7d5bbb55045042a2b5a32c18/src/clj/coffi/ffi.clj#L453">view source</a></div></div></div></body></html>
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
<!DOCTYPE html PUBLIC ""
|
||||
"">
|
||||
<html><head><meta charset="UTF-8" /><title>coffi.layout documentation</title><link rel="stylesheet" type="text/css" href="css/default.css" /><link rel="stylesheet" type="text/css" href="css/highlight.css" /><script type="text/javascript" src="js/highlight.min.js"></script><script type="text/javascript" src="js/jquery.min.js"></script><script type="text/javascript" src="js/page_effects.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body><div id="header"><h2>Generated by <a href="https://github.com/weavejester/codox">Codox</a></h2><h1><a href="index.html"><span class="project-title"><span class="project-name">coffi</span> <span class="project-version">v1.0.486</span></span></a></h1></div><div class="sidebar primary"><h3 class="no-link"><span class="inner">Project</span></h3><ul class="index-link"><li class="depth-1 "><a href="index.html"><div class="inner">Index</div></a></li></ul><h3 class="no-link"><span class="inner">Namespaces</span></h3><ul><li class="depth-1"><div class="no-link"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>coffi</span></div></div></li><li class="depth-2 branch"><a href="coffi.ffi.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>ffi</span></div></a></li><li class="depth-2 branch current"><a href="coffi.layout.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>layout</span></div></a></li><li class="depth-2"><a href="coffi.mem.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>mem</span></div></a></li></ul></div><div class="sidebar secondary"><h3><a href="#top"><span class="inner">Public Vars</span></a></h3><ul><li class="depth-1"><a href="coffi.layout.html#var-with-c-layout"><div class="inner"><span>with-c-layout</span></div></a></li></ul></div><div class="namespace-docs" id="content"><h1 class="anchor" id="top">coffi.layout</h1><div class="doc"><div class="markdown"><p>Functions for adjusting the layout of structs.</p>
|
||||
<html><head><meta charset="UTF-8" /><title>coffi.layout documentation</title><link rel="stylesheet" type="text/css" href="css/default.css" /><link rel="stylesheet" type="text/css" href="css/highlight.css" /><script type="text/javascript" src="js/highlight.min.js"></script><script type="text/javascript" src="js/jquery.min.js"></script><script type="text/javascript" src="js/page_effects.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body><div id="header"><h2>Generated by <a href="https://github.com/weavejester/codox">Codox</a></h2><h1><a href="index.html"><span class="project-title"><span class="project-name">coffi</span> <span class="project-version">v1.0.486</span></span></a></h1></div><div class="sidebar primary"><h3 class="no-link"><span class="inner">Project</span></h3><ul class="index-link"><li class="depth-1 "><a href="index.html"><div class="inner">Index</div></a></li></ul><h3 class="no-link"><span class="inner">Topics</span></h3><ul><li class="depth-1 "><a href="01-Getting-Started.html"><div class="inner"><span>Getting Started</span></div></a></li></ul><h3 class="no-link"><span class="inner">Namespaces</span></h3><ul><li class="depth-1"><div class="no-link"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>coffi</span></div></div></li><li class="depth-2 branch"><a href="coffi.ffi.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>ffi</span></div></a></li><li class="depth-2 branch current"><a href="coffi.layout.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>layout</span></div></a></li><li class="depth-2"><a href="coffi.mem.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>mem</span></div></a></li></ul></div><div class="sidebar secondary"><h3><a href="#top"><span class="inner">Public Vars</span></a></h3><ul><li class="depth-1"><a href="coffi.layout.html#var-with-c-layout"><div class="inner"><span>with-c-layout</span></div></a></li></ul></div><div class="namespace-docs" id="content"><h1 class="anchor" id="top">coffi.layout</h1><div class="doc"><div class="markdown"><p>Functions for adjusting the layout of structs.</p>
|
||||
</div></div><div class="public anchor" id="var-with-c-layout"><h3>with-c-layout</h3><div class="usage"><code>(with-c-layout struct-spec)</code></div><div class="doc"><div class="markdown"><p>Forces a struct specification to C layout rules.</p>
|
||||
<p>This will add padding fields between fields to match C alignment requirements.</p>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/a377c97c93a311a43100a5e05567680e6ae3c2de/src/clj/coffi/layout.clj#L6">view source</a></div></div></div></body></html>
|
||||
</div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/be58ac5d8037811e7d5bbb55045042a2b5a32c18/src/clj/coffi/layout.clj#L6">view source</a></div></div></div></body></html>
|
||||
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
Loading…
Reference in a new issue