<p>See GitHub for the <ahref="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><codeclass="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>
<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>
<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>
<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><codeclass="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>
<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>
<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>
<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>
<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><codeclass="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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<p>Some functions require more complex code to map nicely to a Clojure function. The <code>defcfn</code> macro provides facilities to wrap the native function with some Clojure code to make this easier.</p>
<p>The symbol <code>native-fn</code> can be any unqualified symbol, and names the native function being wrapped. It must be called in the function body below if you want to call the native code.</p>
<p>This <code>serialize</code> function has a paired <code>deserialize</code>, and allows marshaling Clojure data back and forth to native data structures.</p>
<p>This can be used to implement out variables often seen in native code.</p>
