luciano/coffi
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge branch 'release/v0.6.409'

Browse source
This commit is contained in:
Joshua Suskalo 2023-03-31 10:30:09 -05:00
commit 272df03fba
No known key found for this signature in database
GPG key ID: 9B6BA586EFF1B9F0
14 changed files with 637 additions and 373 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
CHANGELOG.md
View file

@ -1,6 +1,23 @@
# Change Log
All notable changes to this project will be documented in this file. This change log follows the conventions of [keepachangelog.com](http://keepachangelog.com/).
## [0.6.409] - 2023-03-31
### Added
- Support for JDK 19
- New macros for defining vars with values from native code
- New function to allow getting the backing memory segment of a `coffi.ffi.StaticVariable`, to replace the `Addressable` implementation lost in the migration to JDK 18
### Fixed
- Bug where `static-variable`s with primitive types would not deserialize properly on `deref`
- Uses of `defvar` not compiling
- Bug where nil values would not be correctly coerced to null pointers when passed to inlined functions
- Bug where inline serde functions would fail on complex pointer types
- Bug where padding in structs may be increased when fields have alignments less than their size
- Bug where pointer alignment was incorrectly defined
### Changed
- References to `scope` as a term have been changed to `session` to match Panama messaging. Where this conflicts with function names, old versions have been deprecated and new names have been introduced.
## [0.5.357] - 2022-07-07
### Removed
- `:coffi.mem/long-long` primitive type
@ -100,6 +117,7 @@ All notable changes to this project will be documented in this file. This change
- Support for serializing and deserializing arbitrary Clojure functions
- Support for serializing and deserializing arbitrary Clojure data structures
[0.6.409]: https://github.com/IGJoshua/coffi/compare/v0.5.357...v0.6.409
[0.5.357]: https://github.com/IGJoshua/coffi/compare/v0.4.341...v0.5.357
[0.4.341]: https://github.com/IGJoshua/coffi/compare/v0.3.298...v0.4.341
[0.3.298]: https://github.com/IGJoshua/coffi/compare/v0.2.277...v0.3.298

152
README.md
View file

@ -3,7 +3,7 @@
Coffi is a foreign function interface library for Clojure, using the new
[Project Panama](https://openjdk.java.net/projects/panama/) that's a part of the
incubator in Java 18. This allows calling native code directly from Clojure
preview in Java 19. This allows calling native code directly from Clojure
without the need for either Java or native code specific to the library, as e.g.
the JNI does. Coffi focuses on ease of use, including functions and macros for
creating wrappers to allow the resulting native functions to act just like
@ -16,8 +16,8 @@ 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 "0.5.357"}
io.github.IGJoshua/coffi {:git/tag "v0.5.357" :git/sha "a9e3ed0"}
org.suskalo/coffi {:mvn/version "0.6.409"}
io.github.IGJoshua/coffi {:git/tag "v0.6.409" :git/sha "f974446"}
```
If you use this library as a git dependency, you will need to prepare the
@ -27,19 +27,19 @@ library.
$ clj -X:deps prep
```
Coffi requires usage of the module `jdk.incubator.foreign`, which means that the
JVM must enable the usage of this module. In order to use coffi, add the
following JVM arguments to your application.
Coffi requires usage of the package `java.lang.foreign`, and everything in this
package is considered to be a preview release, which are disabled by default. In
order to use coffi, add the following JVM arguments to your application.
```sh
--add-modules=jdk.incubator.foreign --enable-native-access=ALL-UNNAMED
--enable-preview --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--add-modules=jdk.incubator.foreign -J--enable-native-access=ALL-UNNAMED
clj -J--enable-preview -J--enable-native-access=ALL-UNNAMED
```
You can also specify them in an alias in your `deps.edn` file under the
@ -47,7 +47,7 @@ You can also specify them in an alias in your `deps.edn` file under the
using `-M`, `-A`, or `-X`.
``` clojure
{:aliases {:dev {:jvm-opts ["--add-modules=jdk.incubator.foreign" "--enable-native-access=ALL-UNNAMED"]}}}
{:aliases {:dev {:jvm-opts ["--enable-preview" "--enable-native-access=ALL-UNNAMED"]}}}
```
Other build tools should provide similar functionality if you check their
@ -132,14 +132,13 @@ Coffi defines a basic set of primitive types:
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 (with `long-long` mapping to the `long` function) when they are
passed as arguments to native functions. Additionally, the `c-string` type is
defined, although it is not primitive.
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:
deserialization). For an example C struct and function:
```c
typedef struct point {
@ -239,6 +238,23 @@ 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").
@ -265,18 +281,21 @@ 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`
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` can be
used to create a reference to the native value.
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
@ -297,6 +316,10 @@ 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.
### Complex Wrappers
Some functions require more complex code to map nicely to a Clojure function.
The `defcfn` macro provides facilities to wrap the native function with some
@ -331,29 +354,33 @@ This can be used to implement out variables often seen in native code.
(deserialize int-ptr [::mem/pointer ::mem/int])))
```
### Scopes
### Sessions
**Before JDK 19 Sessions were called Scopes. Coffi retains functions that are
named for creating scopes for backwards compatibility, but they will be removed
in version 1.0.**
In order to serialize any non-primitive type (such as the previous
`[::mem/pointer ::mem/int]`), off-heap memory needs to be allocated. When memory
is allocated inside the JVM, the memory is associated with a scope. Because none
was provided here, the scope is an implicit scope, and the memory will be freed
when the serialized object is garbage collected.
is allocated inside the JVM, the memory is associated with a session. Because
none was provided here, the session is an implicit session, and the memory will
be freed when the serialized object is garbage collected.
In many cases this is not desirable, because the memory is not freed in a
deterministic manner, causing garbage collection pauses to become longer, as
well as changing allocation performance. Instead of an implicit scope, there are
other kinds of scopes as well. A `stack-scope` is a thread-local scope. Stack
scopes are `Closeable`, which means they should usually be used in a `with-open`
form. When a `stack-scope` is closed, it immediately frees all the memory
associated with it. The previous example, `out-int`, can be implemented with a
stack scope.
well as changing allocation performance. Instead of an implicit session, there
are other kinds of sessions as well. A `stack-session` is a thread-local
session. Stack sessions are `Closeable`, which means they should usually be used
in a `with-open` form. When a `stack-session` is closed, it immediately frees
all the memory associated with it. The previous example, `out-int`, can be
implemented with a stack session.
```clojure
(defcfn out-int
"out_int" [::mem/pointer] ::mem/void
native-fn
[i]
(with-open [scope (mem/stack-scope)]
(let [int-ptr (mem/serialize i [::mem/pointer ::mem/int] scope)]
(with-open [session (mem/stack-session)]
(let [int-ptr (mem/serialize i [::mem/pointer ::mem/int] session)]
(native-fn int-ptr)
(mem/deserialize int-ptr [::mem/pointer ::mem/int]))))
```
@ -361,14 +388,15 @@ stack scope.
This will free the pointer immediately upon leaving the function.
When memory needs to be accessible from multiple threads, there's
`shared-scope`. When using a `shared-scope`, it should be accessed inside a
`with-acquired` block. When a `shared-scope` is `.close`d, it will release all
`shared-session`. When using a `shared-session`, it should be accessed inside a
`with-acquired` block. When a `shared-session` is `.close`d, it will release all
its associated memory when every `with-acquired` block associated with it is
exited.
In addition, two non-`Closeable` scopes are `global-scope`, which never frees
the resources associated with it, and `connected-scope`, which is a scope that
frees its resources on garbage collection, like an implicit scope.
In addition, two non-`Closeable` sessions are `global-session`, which never
frees the resources associated with it, and `connected-session`, which is a
session that frees its resources on garbage collection, like an implicit
session.
### Serialization and Deserialization
Custom serializers and deserializers may also be created. This is done using two
@ -398,8 +426,8 @@ serialize to primitives.
```clojure
(defmethod mem/serialize* ::vector
[obj _type scope]
(mem/address-of (mem/serialize obj [::mem/array ::mem/float 3] scope)))
[obj _type session]
(mem/address-of (mem/serialize obj [::mem/array ::mem/float 3] session)))
(defmethod mem/deserialize* ::vector
[addr _type]
@ -408,9 +436,9 @@ serialize to primitives.
```
The `slice-global` function allows you to take an address without an associated
scope and get a memory segment which can be deserialized.
session and get a memory segment which can be deserialized.
In cases like this where we don't know the scope of the pointer, we could use
In cases like this where we don't know the session of the pointer, we could use
`add-close-action!` to ensure it's freed. For example if a `free-vector!`
function that takes a pointer exists, we could use this:
@ -418,14 +446,14 @@ function that takes a pointer exists, we could use this:
(defcfn returns-vector
"returns_vector" [] ::mem/pointer
native-fn
[scope]
[session]
(let [ret-ptr (native-fn)]
(add-close-action! scope #(free-vector! ret-ptr))
(add-close-action! session #(free-vector! ret-ptr))
(deserialize ret-ptr ::vector)))
```
This function takes a scope and returns the deserialized vector, and it will
free the pointer when the scope closes.
This function takes a session and returns the deserialized vector, and it will
free the pointer when the session closes.
#### Tagged Union
For the tagged union type, we will represent the value as a vector of a keyword
@ -477,7 +505,7 @@ deserialize the value into and out of memory segments. This is accomplished with
(map first))))
(defmethod mem/serialize-into ::tagged-union
[obj [_tagged-union tags type-map] segment scope]
[obj [_tagged-union tags type-map] segment session]
(mem/serialize-into
{:tag (item-index tags (first obj))
:value (second obj)}
@ -485,7 +513,7 @@ deserialize the value into and out of memory segments. This is accomplished with
[[:tag ::mem/long]
[:value (get type-map (first obj))]]]
segment
scope))
session))
```
This serialization method is rather simple, it just turns the vector value into
@ -542,7 +570,7 @@ it could be represented for serialization purposes like so:
This union however would not include the tag when serialized.
If a union is deserialized, then all that coffi does is to allocate a new
segment of the appropriate size with an implicit scope so that it may later be
segment of the appropriate size with an implicit session so that it may later be
garbage collected, and copies the data from the source segment into it. It's up
to the user to call `deserialize-from` on that segment with the appropriate
type.
@ -567,12 +595,12 @@ With raw handles, the argument types are expected to exactly match the types
expected by the native function. For primitive types, those are primitives. For
addresses, that is `MemoryAddress`, and for composite types like structs and
unions, that is `MemorySegment`. Both `MemoryAddress` and `MemorySegment` come
from the `jdk.incubator.foreign` package.
from the `java.lang.foreign` package.
In addition, when a raw handle returns a composite type represented with a
`MemorySegment`, it requires an additional first argument, a `SegmentAllocator`,
which can be acquired with `scope-allocator` to get one associated with a
specific scope. The returned value will live until that scope is released.
which can be acquired with `session-allocator` to get one associated with a
specific session. The returned value will live until that session is released.
In addition, function types can be specified as being raw, in the following
manner:
@ -612,8 +640,8 @@ floats, the following code might be used.
(defn returns-float-array
[]
(with-open [scope (mem/stack-scope)]
(let [out-floats (mem/alloc mem/pointer-size scope)
(with-open [session (mem/stack-session)]
(let [out-floats (mem/alloc mem/pointer-size session)
num-floats (function-handle (mem/address-of out-floats))
floats-addr (mem/read-address out-floats)
floats-slice (mem/slice-global floats-addr (unchecked-multiply-int mem/float-size num-floats))]
@ -712,6 +740,8 @@ appealing, as they have a smaller API surface area and it's easier to wrap
functions.
### Benchmarks
**BENCHMARKS FOR COFFI AND DTYPE-NEXT ARE BASED ON AN OLD VERSION. NEW BENCHMARKS WILL BE CREATED WHEN PANAMA COMES OUT OF PREVIEW**
An additional consideration when thinking about alternatives is the performance
of each available option. It's an established fact that JNA (used by all three
alternative libraries on JDK <16) introduces more overhead when calling native
@ -954,8 +984,6 @@ coming from, but I'll admit that I haven't looked at their implementations very
closely.
#### dtype-next
**BENCHMARKS FOR DTYPE-NEXT ARE BASED ON AN OLD VERSION. NEW BENCHMARKS WILL BE COMING SHORTLY**
The library dtype-next replaced tech.jna in the toolkit of the group working on
machine learning and array-based programming, and it includes support for
composite data types including structs, as well as primitive functions and
@ -1089,7 +1117,10 @@ stands, coffi is the fastest FFI available to Clojure developers.
The project author is aware of these issues and plans to fix them in a future
release:
There are currently no known issues! Hooray!
- On M1 Macs occasional crashes are present when returning structs by value from
native code. At the moment this appears to be an upstream issue with Panama,
and will be reported once a minimal reproduction case with only Panama is
produced.
## Future Plans
These features are planned for future releases.
@ -1097,27 +1128,26 @@ These features are planned for future releases.
- Support for va_args type
- Header parsing tool for generating a data model?
- Generic type aliases
- Helpers for generating enums & bitflags
- Unsigned integer types
- Record-based struct types
- Helper macro for out arguments
- Improve error messages from defcfn macro
- Mapped memory
- Helper macros for custom serde implementations for composite data types
### Future JDKs
The purpose of coffi is to provide a wrapper for published versions of Project
Panama, starting with JDK 17. As new JDKs are released, coffi will be ported to
the newer versions of Panama. Version `0.4.341` is the last version compatible
with JDK 17. Bugfixes, and potential backports of newer coffi features may be
found on the `jdk17-lts` branch. Development of new features and fixes as well
as support for new Panama idioms and features will continue with focus only on
the latest JDK. If a particular feature is not specific to the newer JDK, PRs
backporting it to versions of coffi supporting Java 17 will likely be accepted.
with JDK 17. Version `0.5.357` is the last version compatible with JDK 18.
Bugfixes, and potential backports of newer coffi features may be found on the
`jdk17-lts` branch. Development of new features and fixes as well as support for
new Panama idioms and features will continue with focus only on the latest JDK.
If a particular feature is not specific to the newer JDK, PRs backporting it to
versions of coffi supporting Java 17 will likely be accepted.
### 1.0 Release
Because the feature that coffi wraps in the JDK is an incubator feature (and
likely in JDK 19 a [preview
feature](https://mail.openjdk.java.net/pipermail/panama-dev/2021-September/014946.html))
Because the feature that coffi wraps in the JDK is in preview as of JDK 19,
coffi itself will not be released in a 1.0.x version until the feature becomes a
core part of the JDK, likely before or during the next LTS release, Java 21, in
September 2023.

8
build.clj
View file

@ -17,7 +17,7 @@
[clojure.tools.build.api :as b]))
(def lib-coord 'org.suskalo/coffi)
(def version (format "0.5.%s" (b/git-count-revs nil)))
(def version (format "0.6.%s" (b/git-count-revs nil)))
(def resource-dirs ["resources/"])
@ -49,11 +49,11 @@
"Compiles java classes required for interop."
[opts]
(.mkdirs (io/file class-dir))
(b/process {:command-args ["javac" "--add-modules=jdk.incubator.foreign"
(b/process {:command-args ["javac" "--enable-preview"
"src/java/coffi/ffi/Loader.java"
"-d" class-dir
"-target" "18"
"-source" "18"]})
"-target" "19"
"-source" "19"]})
opts)
(defn- write-pom

14
deps.edn
View file

@ -1,5 +1,5 @@
{:paths ["src/clj" "target/classes" "resources"]
:deps {org.clojure/clojure {:mvn/version "1.10.3"}
:deps {org.clojure/clojure {:mvn/version "1.11.1"}
insn/insn {:mvn/version "0.2.1"}}
:deps/prep-lib {:alias :build
@ -12,26 +12,26 @@
nodisassemble/nodisassemble {:mvn/version "0.1.3"}}
;; NOTE(Joshua): If you want to use nodisassemble you should also add a
;; -javaagent for the resolved location
:jvm-opts ["--add-modules=jdk.incubator.foreign" "--enable-native-access=ALL-UNNAMED"]}
:jvm-opts ["--enable-native-access=ALL-UNNAMED" "--enable-preview"]}
:test {:extra-paths ["test/clj"]
:extra-deps {org.clojure/test.check {:mvn/version "1.1.0"}
io.github.cognitect-labs/test-runner
{:git/url "https://github.com/cognitect-labs/test-runner"
:sha "62ef1de18e076903374306060ac0e8a752e57c86"}}
:jvm-opts ["--add-modules=jdk.incubator.foreign" "--enable-native-access=ALL-UNNAMED"]
:jvm-opts ["--enable-native-access=ALL-UNNAMED" "--enable-preview"]
:exec-fn cognitect.test-runner.api/test}
:codox {:extra-deps {codox/codox {:mvn/version "0.10.7"}}
:exec-fn codox.main/generate-docs
:exec-args {:name "coffi"
:version "v0.5.357"
:description "A Foreign Function Interface in Clojure for JDK 18."
:version "v0.6.409"
:description "A Foreign Function Interface in Clojure for JDK 19."
:source-paths ["src/clj"]
:output-path "docs"
:source-uri "https://github.com/IGJoshua/coffi/blob/{git-commit}/{filepath}#L{line}"
:metadata {:doc/format :markdown}}
:jvm-opts ["--add-modules=jdk.incubator.foreign"
"--add-opens" "java.base/java.lang=ALL-UNNAMED"]}
:jvm-opts ["--add-opens" "java.base/java.lang=ALL-UNNAMED"
"--enable-preview"]}
:build {:replace-deps {org.clojure/clojure {:mvn/version "1.10.3"}
io.github.clojure/tools.build {:git/tag "v0.3.0" :git/sha "e418fc9"}}

21
docs/coffi.ffi.html
View file

@ -1,19 +1,20 @@
<!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">v0.5.357</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-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-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>
<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">v0.6.409</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></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/e98c5a56bb4699035ebf3b3b49a8e89f8edbe087/src/clj/coffi/ffi.clj#L421">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/e98c5a56bb4699035ebf3b3b49a8e89f8edbe087/src/clj/coffi/ffi.clj#L565">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 &amp; fn-tail)</code></div><div class="doc"><div class="markdown"><p>Defines a Clojure function which maps to a native function.</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/9d6051236550967a00151244e9e0c5630e2944b1/src/clj/coffi/ffi.clj#L429">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/9d6051236550967a00151244e9e0c5630e2944b1/src/clj/coffi/ffi.clj#L570">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 &amp; 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/e98c5a56bb4699035ebf3b3b49a8e89f8edbe087/src/clj/coffi/ffi.clj#L701">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">NativeSymbol</a> of a symbol from the loaded libraries.</p></div></div><div class="src-link"><a href="https://github.com/IGJoshua/coffi/blob/e98c5a56bb4699035ebf3b3b49a8e89f8edbe087/src/clj/coffi/ffi.clj#L37">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/e98c5a56bb4699035ebf3b3b49a8e89f8edbe087/src/clj/coffi/ffi.clj#L587">view source</a></div></div><div class="public anchor" id="var-fswap.21"><h3>fswap!</h3><div class="usage"><code>(fswap! static-var f &amp; 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/e98c5a56bb4699035ebf3b3b49a8e89f8edbe087/src/clj/coffi/ffi.clj#L596">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/e98c5a56bb4699035ebf3b3b49a8e89f8edbe087/src/clj/coffi/ffi.clj#L32">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/e98c5a56bb4699035ebf3b3b49a8e89f8edbe087/src/clj/coffi/ffi.clj#L27">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>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/9d6051236550967a00151244e9e0c5630e2944b1/src/clj/coffi/ffi.clj#L745">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/9d6051236550967a00151244e9e0c5630e2944b1/src/clj/coffi/ffi.clj#L581">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/9d6051236550967a00151244e9e0c5630e2944b1/src/clj/coffi/ffi.clj#L648">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/9d6051236550967a00151244e9e0c5630e2944b1/src/clj/coffi/ffi.clj#L189">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/9d6051236550967a00151244e9e0c5630e2944b1/src/clj/coffi/ffi.clj#L39">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/9d6051236550967a00151244e9e0c5630e2944b1/src/clj/coffi/ffi.clj#L611">view source</a></div></div><div class="public anchor" id="var-fswap.21"><h3>fswap!</h3><div class="usage"><code>(fswap! static-var f &amp; 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/9d6051236550967a00151244e9e0c5630e2944b1/src/clj/coffi/ffi.clj#L620">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/9d6051236550967a00151244e9e0c5630e2944b1/src/clj/coffi/ffi.clj#L34">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/9d6051236550967a00151244e9e0c5630e2944b1/src/clj/coffi/ffi.clj#L29">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/e98c5a56bb4699035ebf3b3b49a8e89f8edbe087/src/clj/coffi/ffi.clj#L198">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/e98c5a56bb4699035ebf3b3b49a8e89f8edbe087/src/clj/coffi/ffi.clj#L409">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/e98c5a56bb4699035ebf3b3b49a8e89f8edbe087/src/clj/coffi/ffi.clj#L390">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>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/9d6051236550967a00151244e9e0c5630e2944b1/src/clj/coffi/ffi.clj#L197">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/9d6051236550967a00151244e9e0c5630e2944b1/src/clj/coffi/ffi.clj#L417">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/9d6051236550967a00151244e9e0c5630e2944b1/src/clj/coffi/ffi.clj#L398">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/e98c5a56bb4699035ebf3b3b49a8e89f8edbe087/src/clj/coffi/ffi.clj#L214">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/e98c5a56bb4699035ebf3b3b49a8e89f8edbe087/src/clj/coffi/ffi.clj#L663">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/e98c5a56bb4699035ebf3b3b49a8e89f8edbe087/src/clj/coffi/ffi.clj#L622">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, and the address of the value can be queried with <a href="coffi.mem.html#var-address-of">address-of</a>.</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/e98c5a56bb4699035ebf3b3b49a8e89f8edbe087/src/clj/coffi/ffi.clj#L604">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/e98c5a56bb4699035ebf3b3b49a8e89f8edbe087/src/clj/coffi/ffi.clj#L435">view source</a></div></div></div></body></html>
<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/9d6051236550967a00151244e9e0c5630e2944b1/src/clj/coffi/ffi.clj#L213">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/9d6051236550967a00151244e9e0c5630e2944b1/src/clj/coffi/ffi.clj#L707">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/9d6051236550967a00151244e9e0c5630e2944b1/src/clj/coffi/ffi.clj#L666">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/9d6051236550967a00151244e9e0c5630e2944b1/src/clj/coffi/ffi.clj#L636">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/9d6051236550967a00151244e9e0c5630e2944b1/src/clj/coffi/ffi.clj#L628">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/9d6051236550967a00151244e9e0c5630e2944b1/src/clj/coffi/ffi.clj#L443">view source</a></div></div></div></body></html>

4
docs/coffi.layout.html
View file

@ -1,4 +1,4 @@
<!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">v0.5.357</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></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/e98c5a56bb4699035ebf3b3b49a8e89f8edbe087/src/clj/coffi/layout.clj#L6">view source</a></div></div></div></body></html>
<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">v0.6.409</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></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/9d6051236550967a00151244e9e0c5630e2944b1/src/clj/coffi/layout.clj#L6">view source</a></div></div></div></body></html>

80
docs/coffi.mem.html
View file

File diff suppressed because one or more lines are too long

2
docs/index.html
View file

File diff suppressed because one or more lines are too long

140
src/clj/coffi/ffi.clj
View file

@ -13,15 +13,17 @@
MethodHandle
MethodHandles
MethodType)
(jdk.incubator.foreign
(java.lang.foreign
Addressable
CLinker
Linker
FunctionDescriptor
MemoryAddress
MemoryLayout
NativeSymbol
MemorySegment
SegmentAllocator)))
(set! *warn-on-reflection* true)
;;; FFI Code loading and function access
(defn load-system-library
@ -35,7 +37,7 @@
(Loader/loadLibrary (.getAbsolutePath (io/file path))))
(defn find-symbol
"Gets the [[NativeSymbol]] of a symbol from the loaded libraries."
"Gets the [[MemorySegment]] of a symbol from the loaded libraries."
[sym]
(Loader/findSymbol (name sym)))
@ -52,9 +54,9 @@
args-arr)))))
(defn- downcall-handle
"Gets the [[MethodHandle]] for the function at the `address`."
"Gets the [[MethodHandle]] for the function at the `sym`."
[sym function-descriptor]
(.downcallHandle (CLinker/systemCLinker) sym function-descriptor))
(.downcallHandle (Linker/nativeLinker) sym function-descriptor))
(def ^:private load-instructions
"Mapping from primitive types to the instruction used to load them onto the stack."
@ -62,7 +64,6 @@
::mem/short :sload
::mem/int :iload
::mem/long :lload
::mem/long-long :lload
::mem/char :cload
::mem/float :fload
::mem/double :dload
@ -74,7 +75,6 @@
::mem/short Short
::mem/int Integer
::mem/long Long
::mem/long-long Long
::mem/char Character
::mem/float Float
::mem/double Double})
@ -110,7 +110,6 @@
::mem/short "shortValue"
::mem/int "intValue"
::mem/long "longValue"
::mem/long-long "longValue"
::mem/char "charValue"
::mem/float "floatValue"
::mem/double "doubleValue"})
@ -187,11 +186,11 @@
[handle args ret]
(insn/new-instance (downcall-class args ret) ^MethodHandle handle))
(defn- ensure-symbol
"Gets the address if the argument is [[Addressable]], otherwise
(defn ensure-symbol
"Returns the argument if it is a [[MemorySegment]], otherwise
calls [[find-symbol]] on it."
^NativeSymbol [symbol-or-addr]
(if (instance? NativeSymbol symbol-or-addr)
^MemorySegment [symbol-or-addr]
(if (instance? MemorySegment symbol-or-addr)
symbol-or-addr
(find-symbol symbol-or-addr)))
@ -235,7 +234,6 @@
::mem/short `short
::mem/int `int
::mem/long `long
::mem/long-long `long
::mem/char `char
::mem/float `float
::mem/double `double})
@ -246,14 +244,23 @@
The return type and any arguments that are primitives will not
be (de)serialized except to be cast. If all arguments and return are
primitive, the `downcall` is returned directly. In cases where arguments must
be serialized, a new [[mem/stack-scope]] is generated."
be serialized, a new [[mem/stack-session]] is generated."
[downcall arg-types ret-type]
(let [;; Complexity of types
const-args? (or (vector? arg-types) (nil? arg-types))
simple-args? (when const-args?
(every? mem/primitive? arg-types))
(and (every? mem/primitive? arg-types)
;; NOTE(Joshua): Pointer types with serdes (e.g. [::mem/pointer ::mem/int])
;; still require a session, making them not qualify as "simple".
(every? keyword? (filter (comp #{::mem/pointer} mem/primitive-type) arg-types))))
const-ret? (s/valid? ::mem/type ret-type)
primitive-ret? (and const-ret? (or (mem/primitive? ret-type)
primitive-ret? (and const-ret?
(or (and (mem/primitive? ret-type)
;; NOTE(Joshua): Pointer types with serdes require deserializing the
;; return value, but don't require passing a session to the downcall,
;; making them cause the return to not be primitive, but it may still
;; be "simple".
(or (keyword? ret-type) (not (#{::mem/pointer} (mem/primitive-type ret-type)))))
(#{::mem/void} ret-type)))
simple-ret? (and const-ret? (mem/primitive-type ret-type))
no-serde? (and const-args? (empty? arg-types)
@ -266,7 +273,7 @@
~ret-type
downcall#)
(let [;; All our symbols
scope (gensym "scope")
session (gensym "session")
downcall-sym (gensym "downcall")
args-sym (when-not const-args?
(gensym "args"))
@ -285,21 +292,22 @@
(some->>
(cond
(not (s/valid? ::mem/type type))
`(mem/serialize ~sym ~type-sym ~scope)
`(mem/serialize ~sym ~type-sym ~session)
(and (mem/primitive? type)
(not (#{::mem/pointer} (mem/primitive-type type))))
(list (primitive-cast-sym (mem/primitive-type type)) sym)
;; cast null pointers to something understood by panama
(#{::mem/pointer} type)
nil
`(or ~sym (MemoryAddress/NULL))
(mem/primitive-type type)
`(mem/serialize* ~sym ~type-sym ~scope)
`(mem/serialize* ~sym ~type-sym ~session)
:else
`(let [alloc# (mem/alloc-instance ~type-sym)]
(mem/serialize-into ~sym ~type-sym alloc# ~scope)
(mem/serialize-into ~sym ~type-sym alloc# ~session)
alloc#))
(list sym)))
@ -326,7 +334,7 @@
:else
`(let [~args-sym (map (fn [obj# type#]
(mem/serialize obj# type# ~scope))
(mem/serialize obj# type# ~session))
~args-sym ~args-types-sym)]
~expr)))
@ -335,7 +343,7 @@
;; taking restargs, and so the downcall must be applied
(-> `(~@(when (symbol? args) [`apply])
~downcall-sym
~@(when allocator? [`(mem/scope-allocator ~scope)])
~@(when allocator? [`(mem/session-allocator ~session)])
~@(if (symbol? args)
[args]
args))
@ -358,12 +366,12 @@
:else
(deserialize-segment expr)))
wrap-scope (fn [expr]
`(with-open [~scope (mem/stack-scope)]
wrap-session (fn [expr]
`(with-open [~session (mem/stack-session)]
~expr))
wrap-fn (fn [call needs-scope?]
wrap-fn (fn [call needs-session?]
`(fn [~@(if const-args? arg-syms ['& args-sym])]
~(cond-> call needs-scope? wrap-scope)))]
~(cond-> call needs-session? wrap-session)))]
`(let [;; NOTE(Joshua): To ensure all arguments are evaluated once and
;; in-order, they must be bound here
~downcall-sym ~downcall
@ -395,15 +403,15 @@
[downcall arg-types ret-type]
(if (mem/primitive-type ret-type)
(fn native-fn [& args]
(with-open [scope (mem/stack-scope)]
(with-open [session (mem/stack-session)]
(mem/deserialize*
(apply downcall (map #(mem/serialize %1 %2 scope) args arg-types))
(apply downcall (map #(mem/serialize %1 %2 session) args arg-types))
ret-type)))
(fn native-fn [& args]
(with-open [scope (mem/stack-scope)]
(with-open [session (mem/stack-session)]
(mem/deserialize-from
(apply downcall (mem/scope-allocator scope)
(map #(mem/serialize %1 %2 scope) args arg-types))
(apply downcall (mem/session-allocator session)
(map #(mem/serialize %1 %2 session) args arg-types))
ret-type)))))
(defn make-serde-varargs-wrapper
@ -510,10 +518,7 @@
([args] (method-type args ::mem/void))
([args ret]
(MethodType/methodType
^Class (let [r (mem/java-layout ret)]
(if (= r MemoryAddress)
Addressable
r))
^Class (coerce-addressable (mem/java-layout ret))
^"[Ljava.lang.Class;" (into-array Class (map mem/java-layout args)))))
(defn- upcall-handle
@ -531,30 +536,30 @@
(defn- upcall-serde-wrapper
"Creates a function that wraps `f` which deserializes the arguments and
serializes the return type in the [[global-scope]]."
serializes the return type in the [[global-session]]."
[f arg-types ret-type]
(fn [& args]
(mem/serialize
(apply f (map mem/deserialize args arg-types))
ret-type
(mem/global-scope))))
(mem/global-session))))
(defmethod mem/serialize* ::fn
[f [_fn arg-types ret-type & {:keys [raw-fn?]}] scope]
[f [_fn arg-types ret-type & {:keys [raw-fn?]}] session]
(.upcallStub
(CLinker/systemCLinker)
(Linker/nativeLinker)
(cond-> f
(not raw-fn?) (upcall-serde-wrapper arg-types ret-type)
:always (upcall-handle arg-types ret-type))
(function-descriptor arg-types ret-type)
scope))
session))
(defmethod mem/deserialize* ::fn
[addr [_fn arg-types ret-type & {:keys [raw-fn?]}]]
(when-not (mem/null? addr)
(vary-meta
(-> addr
(as-> addr (NativeSymbol/ofAddress "coffi_upcall_symbol" addr (mem/connected-scope)))
(MemorySegment/ofAddress mem/pointer-size (mem/connected-session))
(downcall-handle (function-descriptor arg-types ret-type))
(downcall-fn arg-types ret-type)
(cond-> (not raw-fn?) (make-serde-wrapper arg-types ret-type)))
@ -567,10 +572,29 @@
[symbol-or-addr type]
(mem/deserialize (.address (ensure-symbol symbol-or-addr)) [::mem/pointer type]))
(s/def ::defconst-args
(s/cat :var-name simple-symbol?
:docstring (s/? string?)
:symbol-or-addr any?
:type ::mem/type))
(defmacro defconst
"Defines a var named by `symbol` to be the value of the given `type` from `symbol-or-addr`."
{:arglists '([symbol docstring? symbol-or-addr type])}
[& args]
(let [args (s/conform ::defconst-args args)]
`(let [symbol# (ensure-symbol ~(:symbol-or-addr args))]
(def ~(:var-name args)
~@(when-let [doc (:docstring args)]
(list doc))
(const symbol# ~(:type args))))))
(s/fdef defconst
:args ::defconst-args)
(deftype StaticVariable [seg type meta]
IDeref
(deref [_]
(mem/deserialize seg type))
(mem/deserialize-from seg type))
IObj
(withMeta [_ meta-map]
@ -590,7 +614,7 @@
(mem/serialize-into
newval (.-type static-var)
(.-seg static-var)
(mem/global-scope))
(mem/global-session))
newval)
(defn fswap!
@ -601,19 +625,39 @@
[static-var f & args]
(freset! static-var (apply f @static-var args)))
(defn static-variable-segment
"Gets the backing [[MemorySegment]] from `static-var`.
This is primarily useful when you need to pass the static variable's address
to a native function which takes an [[Addressable]]."
^MemorySegment [static-var]
(.-seg ^StaticVariable static-var))
(defn static-variable
"Constructs a reference to a mutable value stored in `symbol-or-addr`.
The returned value can be dereferenced, and has metadata, and the address of
the value can be queried with [[address-of]].
The returned value can be dereferenced, and has metadata.
See [[freset!]], [[fswap!]]."
[symbol-or-addr type]
(StaticVariable. (mem/as-segment (.address (ensure-symbol symbol-or-addr))
(mem/size-of type)
(mem/global-scope))
(mem/global-session))
type (atom nil)))
(defmacro defvar
"Defines a var named by `symbol` to be a reference to the native memory from `symbol-or-addr`."
{:arglists '([symbol docstring? symbol-or-addr type])}
[& args]
(let [args (s/conform ::defconst-args args)]
`(let [symbol# (ensure-symbol ~(:symbol-or-addr args))]
(def ~(:var-name args)
~@(when-let [doc (:docstring args)]
(list doc))
(static-variable symbol# ~(:type args))))))
(s/fdef defvar
:args ::defconst-args)
(s/def :coffi.ffi.symbolspec/symbol string?)
(s/def :coffi.ffi.symbolspec/type keyword?)
(s/def ::symbolspec

7
src/clj/coffi/layout.clj
View file

@ -16,11 +16,12 @@
(if (seq fields)
(let [[[_ type :as field] & fields] fields
size (mem/size-of type)
r (rem offset (mem/align-of type))]
align (mem/align-of type)
r (rem offset align)]
(recur (cond-> (+ offset size)
(pos? r) (+ (- size r)))
(pos? r) (+ (- align r)))
(cond-> aligned-fields
(pos? r) (conj [::padding [::mem/padding (- size r)]])
(pos? r) (conj [::padding [::mem/padding (- align r)]])
:always (conj field))
fields))
(let [strongest-alignment (mem/align-of struct-spec)

547
src/clj/coffi/mem.clj
View file

File diff suppressed because it is too large Load diff

6
src/java/coffi/ffi/Loader.java
View file

@ -1,6 +1,6 @@
package coffi.ffi;
import jdk.incubator.foreign.*;
import java.lang.foreign.*;
/**
* Loading libraries with the {@link System#load} and {@link System#loadLibrary}
@ -36,8 +36,8 @@ public class Loader {
*
* @param symbol The name of the symbol to load from a library.
*/
public static NativeSymbol findSymbol(String symbol) {
return CLinker.systemCLinker().lookup(symbol)
public static MemorySegment findSymbol(String symbol) {
return Linker.nativeLinker().defaultLookup().lookup(symbol)
.orElseGet(() -> SymbolLookup.loaderLookup().lookup(symbol).orElse(null));
}
}

2
test/c/ffi_test.c
View file

@ -26,7 +26,7 @@ CString upcall_test(StringFactory fun) {
return fun();
}
static int counter = 0;
int counter = 0;
static char* responses[] = { "Hello, world!", "Goodbye friend.", "co'oi prenu" };

5
test/clj/coffi/ffi_test.clj
View file

@ -44,3 +44,8 @@
{:a \x
:x 3.14
:y 42.0})))
(t/deftest static-variables-are-mutable
(ffi/freset! (ffi/static-variable "counter" ::mem/int) 1)
(t/is (= ((ffi/cfn "get_string1" [] ::mem/c-string))
"Goodbye friend.")))