Merge branch 'release/v1.0.450'
This commit is contained in:
Joshua Suskalo
commit
0847cb1008
20 changed files with 602 additions and 468 deletions
1
.envrc
Normal file
1
.envrc
Normal file
|
|
@ -0,0 +1 @@
|
|||
use flake
|
||||
1
.gitignore
vendored
1
.gitignore
vendored
|
|
@ -14,3 +14,4 @@
|
|||
/.socket-repl-port
|
||||
.hgignore
|
||||
.hg/
|
||||
/.direnv
|
||||
|
|
|
|||
17
CHANGELOG.md
17
CHANGELOG.md
|
|
@ -1,6 +1,22 @@
|
|||
# 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/).
|
||||
|
||||
## [1.0.450] - 2024-10-02
|
||||
### Added
|
||||
- Support for JDK 22
|
||||
- `reinterpret` function which changes the size associated with a segment, optionally associating it with an arena and cleanup action
|
||||
|
||||
### Changed
|
||||
- Arglists and docstrings of functions to refer to arenas rather than the outdated terms scope or session
|
||||
- Change the arguments to `as-segment` to take longs to account for the removal of an Address type
|
||||
|
||||
### Removed
|
||||
- Deprecated functions referring to sessions and scopes
|
||||
- Deprecated functions `slice-into` and `with-offset`, replaced by the function `slice`
|
||||
|
||||
### Fixed
|
||||
- Prep step when using coffi as a dependency wouldn't re-run if it failed during execution, e.g. when using the incorrect java version
|
||||
|
||||
## [0.6.409] - 2023-03-31
|
||||
### Added
|
||||
- Support for JDK 19
|
||||
|
|
@ -117,6 +133,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
|
||||
|
||||
[Unreleased]: https://github.com/IGJoshua/coffi/compare/v0.6.409...develop
|
||||
[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
|
||||
|
|
|
|||
173
README.md
173
README.md
|
|
@ -1,23 +1,23 @@
|
|||
# coffi
|
||||
[](https://clojars.org/org.suskalo/coffi)
|
||||
|
||||
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
|
||||
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
|
||||
Clojure ones, however this 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 Panama gives us.
|
||||
Coffi is a foreign function interface library for Clojure, using the [Foreign
|
||||
Function & Memory API](https://openjdk.org/jeps/454) in JDK 22 and later. 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 Clojure ones, however this
|
||||
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 Panama gives us.
|
||||
|
||||
## 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 "0.6.409"}
|
||||
io.github.IGJoshua/coffi {:git/tag "v0.6.409" :git/sha "f974446"}
|
||||
org.suskalo/coffi {:mvn/version "1.0.450"}
|
||||
io.github.IGJoshua/coffi {:git/tag "v1.0.450" :git/sha "2676a7a"}
|
||||
```
|
||||
|
||||
If you use this library as a git dependency, you will need to prepare the
|
||||
|
|
@ -27,19 +27,20 @@ library.
|
|||
$ clj -X:deps prep
|
||||
```
|
||||
|
||||
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.
|
||||
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-preview --enable-native-access=ALL-UNNAMED
|
||||
--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-preview -J--enable-native-access=ALL-UNNAMED
|
||||
clj -J--enable-native-access=ALL-UNNAMED
|
||||
```
|
||||
|
||||
You can also specify them in an alias in your `deps.edn` file under the
|
||||
|
|
@ -47,15 +48,20 @@ 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 ["--enable-preview" "--enable-native-access=ALL-UNNAMED"]}}}
|
||||
{: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.
|
||||
|
||||
Coffi also includes support for the linter clj-kondo. If you use clj-kondo and
|
||||
this library's macros are not linting correctly, you may need to install the
|
||||
config bundled with the library. You can do so with the following shell command:
|
||||
config bundled with the library. You can do so with the following shell command,
|
||||
run from your project directory:
|
||||
|
||||
```sh
|
||||
$ clj-kondo --copy-configs --dependencies --lint "$(clojure -Spath)"
|
||||
|
|
@ -193,7 +199,7 @@ be found in `coffi.layout`.
|
|||
[[:a ::mem/char]
|
||||
[:x ::mem/float]]]))
|
||||
|
||||
(mem/size-of ::needs-padding))
|
||||
(mem/size-of ::needs-padding)
|
||||
;; => 8
|
||||
|
||||
(mem/align-of ::needs-padding)
|
||||
|
|
@ -331,7 +337,7 @@ Clojure code to make this easier.
|
|||
native-fn
|
||||
[ints]
|
||||
(let [arr-len (count ints)
|
||||
int-array (serialize ints [::mem/array ::mem/int arr-len])]
|
||||
int-array (mem/serialize ints [::mem/array ::mem/int arr-len])]
|
||||
(native-fn (mem/address-of int-array) arr-len)))
|
||||
```
|
||||
|
||||
|
|
@ -349,38 +355,34 @@ This can be used to implement out variables often seen in native code.
|
|||
"out_int" [::mem/pointer] ::mem/void
|
||||
native-fn
|
||||
[i]
|
||||
(let [int-ptr (serialize i [::mem/pointer ::mem/int])]
|
||||
(let [int-ptr (mem/serialize i [::mem/pointer ::mem/int])]
|
||||
(native-fn int-ptr)
|
||||
(deserialize int-ptr [::mem/pointer ::mem/int])))
|
||||
(mem/deserialize int-ptr [::mem/pointer ::mem/int])))
|
||||
```
|
||||
|
||||
### 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.**
|
||||
|
||||
### Arenas
|
||||
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 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.
|
||||
is allocated inside the JVM, the memory is associated with an arena. Because
|
||||
none was provided here, the arena is an implicit arena, 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 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.
|
||||
well as changing allocation performance. Instead of an implicit arena, there
|
||||
are other kinds of arenas as well. A `confined-arena` is a thread-local arena.
|
||||
Confined arenas are `Closeable`, which means they should usually be used in a
|
||||
`with-open` form. When a `confined-arena` is closed, it immediately frees all
|
||||
the memory associated with it. The previous example, `out-int`, can be
|
||||
implemented with a confined arena.
|
||||
|
||||
```clojure
|
||||
(defcfn out-int
|
||||
"out_int" [::mem/pointer] ::mem/void
|
||||
native-fn
|
||||
[i]
|
||||
(with-open [session (mem/stack-session)]
|
||||
(let [int-ptr (mem/serialize i [::mem/pointer ::mem/int] session)]
|
||||
(with-open [arena (mem/confined-arena)]
|
||||
(let [int-ptr (mem/serialize i [::mem/pointer ::mem/int] arena)]
|
||||
(native-fn int-ptr)
|
||||
(mem/deserialize int-ptr [::mem/pointer ::mem/int]))))
|
||||
```
|
||||
|
|
@ -388,15 +390,15 @@ implemented with a stack session.
|
|||
This will free the pointer immediately upon leaving the function.
|
||||
|
||||
When memory needs to be accessible from multiple threads, there's
|
||||
`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.
|
||||
`shared-arena`. When a `shared-arena` is `.close`d, it will release all its
|
||||
associated memory immediately, and so this should only be done once all other
|
||||
threads are done accessing memory associated with it.
|
||||
|
||||
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.
|
||||
In addition, two non-`Closeable` arenas are `global-arena`, which never frees
|
||||
the resources associated with it, and `auto-arena`, which is an arena that frees
|
||||
its resources once all of them are unreachable during a garbage collection
|
||||
cycle, like an implicit arena, but potentially for multiple allocations rather
|
||||
than just one.
|
||||
|
||||
### Serialization and Deserialization
|
||||
Custom serializers and deserializers may also be created. This is done using two
|
||||
|
|
@ -426,34 +428,35 @@ serialize to primitives.
|
|||
|
||||
```clojure
|
||||
(defmethod mem/serialize* ::vector
|
||||
[obj _type session]
|
||||
(mem/address-of (mem/serialize obj [::mem/array ::mem/float 3] session)))
|
||||
[obj _type arena]
|
||||
(mem/serialize obj [::mem/array ::mem/float 3] arena))
|
||||
|
||||
(defmethod mem/deserialize* ::vector
|
||||
[addr _type]
|
||||
(mem/deserialize (mem/slice-global addr (mem/size-of [::mem/array ::mem/float 3]))
|
||||
[segment _type]
|
||||
(mem/deserialize (mem/reinterpret segment (mem/size-of [::mem/array ::mem/float 3]))
|
||||
[::mem/array ::mem/float 3]))
|
||||
```
|
||||
|
||||
The `slice-global` function allows you to take an address without an associated
|
||||
session and get a memory segment which can be deserialized.
|
||||
The `reinterpret` function allows you to take a segment and decorate it with a
|
||||
new size, and possibly associate it with an arena or add cleanup functions on
|
||||
it.
|
||||
|
||||
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:
|
||||
In cases like this where we don't know the arena of the pointer, we could use
|
||||
`reinterpret` to ensure it's freed. For example if a `free-vector!` function
|
||||
that takes a pointer exists, we could use this:
|
||||
|
||||
```clojure
|
||||
(defcfn returns-vector
|
||||
"returns_vector" [] ::mem/pointer
|
||||
native-fn
|
||||
[session]
|
||||
[arena]
|
||||
(let [ret-ptr (native-fn)]
|
||||
(add-close-action! session #(free-vector! ret-ptr))
|
||||
(deserialize ret-ptr ::vector)))
|
||||
(-> (reinterpret ret-ptr (mem/size-of ::vector) arena free-vector!)
|
||||
(deserialize ::vector))))
|
||||
```
|
||||
|
||||
This function takes a session and returns the deserialized vector, and it will
|
||||
free the pointer when the session closes.
|
||||
This function takes an arena and returns the deserialized vector, and it will
|
||||
free the pointer when the arena closes.
|
||||
|
||||
#### Tagged Union
|
||||
For the tagged union type, we will represent the value as a vector of a keyword
|
||||
|
|
@ -505,7 +508,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 session]
|
||||
[obj [_tagged-union tags type-map] segment arena]
|
||||
(mem/serialize-into
|
||||
{:tag (item-index tags (first obj))
|
||||
:value (second obj)}
|
||||
|
|
@ -513,7 +516,7 @@ deserialize the value into and out of memory segments. This is accomplished with
|
|||
[[:tag ::mem/long]
|
||||
[:value (get type-map (first obj))]]]
|
||||
segment
|
||||
session))
|
||||
arena))
|
||||
```
|
||||
|
||||
This serialization method is rather simple, it just turns the vector value into
|
||||
|
|
@ -570,7 +573,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 session so that it may later be
|
||||
segment of the appropriate size with an implicit arena 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.
|
||||
|
|
@ -593,14 +596,14 @@ create raw function handles.
|
|||
|
||||
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 `java.lang.foreign` package.
|
||||
pointers, that is `MemorySegment`, and for composite types like structs and
|
||||
unions, that is also `MemorySegment`. `MemorySegment` comes 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 `session-allocator` to get one associated with a
|
||||
specific session. The returned value will live until that session is released.
|
||||
which can be acquired with `arena-allocator` to get one associated with a
|
||||
specific arena. The returned value will live until that arena is released.
|
||||
|
||||
In addition, function types can be specified as being raw, in the following
|
||||
manner:
|
||||
|
|
@ -635,14 +638,18 @@ As an example, when wrapping a function that returns an array of big-endian
|
|||
floats, the following code might be used.
|
||||
|
||||
``` clojure
|
||||
;; int returns_float_array(float **arr)
|
||||
(def ^:private returns-float-array* (ffi/make-downcall "returns_float_array" [::mem/pointer] ::mem/int))
|
||||
;; void releases_float_array(float *arr)
|
||||
(def ^:private release-floats* (ffi/make-downcall "releases_float_array" [::mem/pointer] ::mem/void))
|
||||
|
||||
(defn returns-float-array
|
||||
[]
|
||||
(with-open [session (mem/stack-session)]
|
||||
(let [out-floats (mem/alloc mem/pointer-size session)
|
||||
num-floats (function-handle (mem/address-of out-floats))
|
||||
(with-open [arena (mem/confined-arena)]
|
||||
;; float *out_floats;
|
||||
;; int num_floats = returns_float_array(&out_floats);
|
||||
(let [out-floats (mem/alloc mem/pointer-size arena)
|
||||
num-floats (returns-float-array* (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))]
|
||||
;; Using a try/finally to perform an operation when the stack frame exits,
|
||||
|
|
@ -657,7 +664,7 @@ floats, the following code might be used.
|
|||
mem/big-endian))
|
||||
(unchecked-inc-int index))))
|
||||
(finally
|
||||
(release-floats floats-addr))))))
|
||||
(release-floats* floats-addr))))))
|
||||
```
|
||||
|
||||
The above code manually performs all memory operations rather than relying on
|
||||
|
|
@ -711,6 +718,8 @@ the multimethod `reify-symbolspec`, although it's recommended that for any
|
|||
library authors who do so, namespaced keywords be used to name types.
|
||||
|
||||
## Alternatives
|
||||
**ALTERNATIVES INFORMATION IS OUT OF DATE. THE LINKS ARE FINE, BUT DESCRIPTIONS WILL BE UPDATED AT A LATER DATE.**
|
||||
|
||||
This library is not the only Clojure library providing access to native code. In
|
||||
addition the following libraries exist:
|
||||
|
||||
|
|
@ -740,7 +749,7 @@ 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**
|
||||
**BENCHMARKS FOR COFFI AND DTYPE-NEXT ARE BASED ON AN OLD VERSION. NEW BENCHMARKS WILL BE CREATED SOON.**
|
||||
|
||||
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
|
||||
|
|
@ -1132,24 +1141,6 @@ These features are planned for future releases.
|
|||
- 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. Version `0.5.357` is the last version compatible with JDK 18.
|
||||
Version `0.6.409` is the latest version compatible with JDK 19. 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 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.
|
||||
|
||||
## License
|
||||
|
||||
Copyright © 2023 Joshua Suskalo
|
||||
|
|
|
|||
12
build.clj
12
build.clj
|
|
@ -17,7 +17,8 @@
|
|||
[clojure.tools.build.api :as b]))
|
||||
|
||||
(def lib-coord 'org.suskalo/coffi)
|
||||
(def version (format "0.6.%s" (b/git-count-revs nil)))
|
||||
;;(def version (format "0.6.%s" (b/git-count-revs nil)))
|
||||
(def version "1.0.450")
|
||||
|
||||
(def resource-dirs ["resources/"])
|
||||
|
||||
|
|
@ -49,11 +50,14 @@
|
|||
"Compiles java classes required for interop."
|
||||
[opts]
|
||||
(.mkdirs (io/file class-dir))
|
||||
(b/process {:command-args ["javac" "--enable-preview"
|
||||
(let [compilation-result
|
||||
(b/process {:command-args ["javac"
|
||||
"src/java/coffi/ffi/Loader.java"
|
||||
"-d" class-dir
|
||||
"-target" "19"
|
||||
"-source" "19"]})
|
||||
"-target" "22"
|
||||
"-source" "22"]})]
|
||||
(when-not (zero? (:exit compilation-result))
|
||||
(b/delete {:path class-dir})))
|
||||
opts)
|
||||
|
||||
(defn- write-pom
|
||||
|
|
|
|||
17
deps.edn
17
deps.edn
|
|
@ -1,6 +1,6 @@
|
|||
{:paths ["src/clj" "target/classes" "resources"]
|
||||
:deps {org.clojure/clojure {:mvn/version "1.11.1"}
|
||||
insn/insn {:mvn/version "0.2.1"}}
|
||||
insn/insn {:mvn/version "0.5.4"}}
|
||||
|
||||
:deps/prep-lib {:alias :build
|
||||
:fn build/compile-java
|
||||
|
|
@ -12,26 +12,25 @@
|
|||
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 ["--enable-native-access=ALL-UNNAMED" "--enable-preview"]}
|
||||
:jvm-opts ["--enable-native-access=ALL-UNNAMED"]}
|
||||
: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 ["--enable-native-access=ALL-UNNAMED" "--enable-preview"]
|
||||
:jvm-opts ["--enable-native-access=ALL-UNNAMED"]
|
||||
:exec-fn cognitect.test-runner.api/test}
|
||||
|
||||
:codox {:extra-deps {codox/codox {:mvn/version "0.10.7"}}
|
||||
:codox {:extra-deps {codox/codox {:mvn/version "0.10.8"}}
|
||||
:replace-deps {insn/insn {:mvn/version "0.2.1"}}
|
||||
:exec-fn codox.main/generate-docs
|
||||
:exec-args {:name "coffi"
|
||||
:version "v0.6.409"
|
||||
:description "A Foreign Function Interface in Clojure for JDK 19."
|
||||
:version "v1.0.450"
|
||||
:description "A Foreign Function Interface in Clojure for JDK 22+."
|
||||
: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-opens" "java.base/java.lang=ALL-UNNAMED"
|
||||
"--enable-preview"]}
|
||||
:metadata {:doc/format :markdown}}}
|
||||
|
||||
:build {:replace-deps {org.clojure/clojure {:mvn/version "1.10.3"}
|
||||
io.github.clojure/tools.build {:git/tag "v0.3.0" :git/sha "e418fc9"}}
|
||||
|
|
|
|||
|
|
@ -1,20 +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">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>
|
||||
<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.450</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/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 & 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/bcf2e031f995d1c7473797c70f94b9731634c97b/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/bcf2e031f995d1c7473797c70f94b9731634c97b/src/clj/coffi/ffi.clj#L564">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/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 & 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>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/bcf2e031f995d1c7473797c70f94b9731634c97b/src/clj/coffi/ffi.clj#L738">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/bcf2e031f995d1c7473797c70f94b9731634c97b/src/clj/coffi/ffi.clj#L575">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/bcf2e031f995d1c7473797c70f94b9731634c97b/src/clj/coffi/ffi.clj#L641">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/bcf2e031f995d1c7473797c70f94b9731634c97b/src/clj/coffi/ffi.clj#L181">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/bcf2e031f995d1c7473797c70f94b9731634c97b/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/bcf2e031f995d1c7473797c70f94b9731634c97b/src/clj/coffi/ffi.clj#L605">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/bcf2e031f995d1c7473797c70f94b9731634c97b/src/clj/coffi/ffi.clj#L614">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/bcf2e031f995d1c7473797c70f94b9731634c97b/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/bcf2e031f995d1c7473797c70f94b9731634c97b/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/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>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/bcf2e031f995d1c7473797c70f94b9731634c97b/src/clj/coffi/ffi.clj#L189">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/bcf2e031f995d1c7473797c70f94b9731634c97b/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/bcf2e031f995d1c7473797c70f94b9731634c97b/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>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/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>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/bcf2e031f995d1c7473797c70f94b9731634c97b/src/clj/coffi/ffi.clj#L205">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/bcf2e031f995d1c7473797c70f94b9731634c97b/src/clj/coffi/ffi.clj#L700">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/bcf2e031f995d1c7473797c70f94b9731634c97b/src/clj/coffi/ffi.clj#L659">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>
|
||||
<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/bcf2e031f995d1c7473797c70f94b9731634c97b/src/clj/coffi/ffi.clj#L630">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/bcf2e031f995d1c7473797c70f94b9731634c97b/src/clj/coffi/ffi.clj#L622">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/bcf2e031f995d1c7473797c70f94b9731634c97b/src/clj/coffi/ffi.clj#L436">view source</a></div></div></div></body></html>
|
||||
|
|
@ -1,4 +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">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>
|
||||
<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.450</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/bcf2e031f995d1c7473797c70f94b9731634c97b/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
26
flake.lock
Normal file
26
flake.lock
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
{
|
||||
"nodes": {
|
||||
"nixpkgs": {
|
||||
"locked": {
|
||||
"lastModified": 1727634051,
|
||||
"narHash": "sha256-S5kVU7U82LfpEukbn/ihcyNt2+EvG7Z5unsKW9H/yFA=",
|
||||
"owner": "NixOS",
|
||||
"repo": "nixpkgs",
|
||||
"rev": "06cf0e1da4208d3766d898b7fdab6513366d45b9",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"id": "nixpkgs",
|
||||
"ref": "nixos-unstable",
|
||||
"type": "indirect"
|
||||
}
|
||||
},
|
||||
"root": {
|
||||
"inputs": {
|
||||
"nixpkgs": "nixpkgs"
|
||||
}
|
||||
}
|
||||
},
|
||||
"root": "root",
|
||||
"version": 7
|
||||
}
|
||||
33
flake.nix
Normal file
33
flake.nix
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
{
|
||||
inputs = {
|
||||
nixpkgs.url = "nixpkgs/nixos-unstable";
|
||||
};
|
||||
outputs = { self, nixpkgs }:
|
||||
let
|
||||
system = "x86_64-linux";
|
||||
pkgs = import nixpkgs {
|
||||
inherit system;
|
||||
overlays = [
|
||||
(final: prev: {
|
||||
clojure = prev.clojure.override { jdk = final.jdk22; };
|
||||
})
|
||||
];
|
||||
};
|
||||
in
|
||||
{
|
||||
devShells.${system}.default = pkgs.mkShell rec {
|
||||
packages = [
|
||||
];
|
||||
|
||||
nativeBuildInputs = with pkgs; [
|
||||
clojure
|
||||
];
|
||||
|
||||
buildInputs = with pkgs; [
|
||||
];
|
||||
|
||||
inputsFrom = with pkgs; [
|
||||
];
|
||||
};
|
||||
};
|
||||
}
|
||||
2
pom.xml
2
pom.xml
|
|
@ -2,7 +2,7 @@
|
|||
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
<name>org.suskalo/coffi</name>
|
||||
<description>A Foreign Function Interface in Clojure for JDK 18.</description>
|
||||
<description>A Foreign Function Interface in Clojure for JDK 22+.</description>
|
||||
<url>https://github.com/IGJoshua/coffi</url>
|
||||
<licenses>
|
||||
<license>
|
||||
|
|
|
|||
|
|
@ -14,10 +14,9 @@
|
|||
MethodHandles
|
||||
MethodType)
|
||||
(java.lang.foreign
|
||||
Addressable
|
||||
Linker
|
||||
Linker$Option
|
||||
FunctionDescriptor
|
||||
MemoryAddress
|
||||
MemoryLayout
|
||||
MemorySegment
|
||||
SegmentAllocator)))
|
||||
|
|
@ -56,7 +55,8 @@
|
|||
(defn- downcall-handle
|
||||
"Gets the [[MethodHandle]] for the function at the `sym`."
|
||||
[sym function-descriptor]
|
||||
(.downcallHandle (Linker/nativeLinker) sym function-descriptor))
|
||||
(.downcallHandle (Linker/nativeLinker) sym function-descriptor
|
||||
(make-array Linker$Option 0)))
|
||||
|
||||
(def ^:private load-instructions
|
||||
"Mapping from primitive types to the instruction used to load them onto the stack."
|
||||
|
|
@ -130,20 +130,12 @@
|
|||
[:invokevirtual (prim-classes prim-type) (unbox-fn-for-type prim-type) [prim]]]
|
||||
[]))))
|
||||
|
||||
(defn- coerce-addressable
|
||||
"If the passed `type` is [[MemoryAddress]], returns [[Addressable]], otherwise returns `type`.
|
||||
|
||||
This is used to declare the return types of upcall stubs."
|
||||
[type]
|
||||
(if (= type MemoryAddress)
|
||||
Addressable
|
||||
type))
|
||||
|
||||
(defn- downcall-class
|
||||
"Class definition for an implementation of [[IFn]] which calls a closed over
|
||||
method handle without reflection, unboxing primitives when needed."
|
||||
[args ret]
|
||||
{:flags #{:public :final}
|
||||
:version 8
|
||||
:super clojure.lang.AFunction
|
||||
:fields [{:name "downcall_handle"
|
||||
:type MethodHandle
|
||||
|
|
@ -175,7 +167,7 @@
|
|||
args)
|
||||
[:invokevirtual MethodHandle "invokeExact"
|
||||
(cond->>
|
||||
(conj (mapv (comp coerce-addressable insn-layout) args)
|
||||
(conj (mapv insn-layout args)
|
||||
(insn-layout ret))
|
||||
(not (mem/primitive-type ret)) (cons SegmentAllocator))]
|
||||
(to-object-asm ret)
|
||||
|
|
@ -244,20 +236,20 @@
|
|||
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-session]] is generated."
|
||||
be serialized, a new [[mem/confined-arena]] 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?
|
||||
(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".
|
||||
;; still require an arena, 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 (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,
|
||||
;; return value, but don't require passing an arena 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)))))
|
||||
|
|
@ -273,7 +265,7 @@
|
|||
~ret-type
|
||||
downcall#)
|
||||
(let [;; All our symbols
|
||||
session (gensym "session")
|
||||
arena (gensym "arena")
|
||||
downcall-sym (gensym "downcall")
|
||||
args-sym (when-not const-args?
|
||||
(gensym "args"))
|
||||
|
|
@ -292,7 +284,7 @@
|
|||
(some->>
|
||||
(cond
|
||||
(not (s/valid? ::mem/type type))
|
||||
`(mem/serialize ~sym ~type-sym ~session)
|
||||
`(mem/serialize ~sym ~type-sym ~arena)
|
||||
|
||||
(and (mem/primitive? type)
|
||||
(not (#{::mem/pointer} (mem/primitive-type type))))
|
||||
|
|
@ -300,14 +292,14 @@
|
|||
|
||||
;; cast null pointers to something understood by panama
|
||||
(#{::mem/pointer} type)
|
||||
`(or ~sym (MemoryAddress/NULL))
|
||||
`(or ~sym (MemorySegment/NULL))
|
||||
|
||||
(mem/primitive-type type)
|
||||
`(mem/serialize* ~sym ~type-sym ~session)
|
||||
`(mem/serialize* ~sym ~type-sym ~arena)
|
||||
|
||||
:else
|
||||
`(let [alloc# (mem/alloc-instance ~type-sym)]
|
||||
(mem/serialize-into ~sym ~type-sym alloc# ~session)
|
||||
(mem/serialize-into ~sym ~type-sym alloc# ~arena)
|
||||
alloc#))
|
||||
(list sym)))
|
||||
|
||||
|
|
@ -334,7 +326,7 @@
|
|||
|
||||
:else
|
||||
`(let [~args-sym (map (fn [obj# type#]
|
||||
(mem/serialize obj# type# ~session))
|
||||
(mem/serialize obj# type# ~arena))
|
||||
~args-sym ~args-types-sym)]
|
||||
~expr)))
|
||||
|
||||
|
|
@ -343,7 +335,7 @@
|
|||
;; taking restargs, and so the downcall must be applied
|
||||
(-> `(~@(when (symbol? args) [`apply])
|
||||
~downcall-sym
|
||||
~@(when allocator? [`(mem/session-allocator ~session)])
|
||||
~@(when allocator? [`(mem/arena-allocator ~arena)])
|
||||
~@(if (symbol? args)
|
||||
[args]
|
||||
args))
|
||||
|
|
@ -366,12 +358,12 @@
|
|||
:else
|
||||
(deserialize-segment expr)))
|
||||
|
||||
wrap-session (fn [expr]
|
||||
`(with-open [~session (mem/stack-session)]
|
||||
wrap-arena (fn [expr]
|
||||
`(with-open [~arena (mem/confined-arena)]
|
||||
~expr))
|
||||
wrap-fn (fn [call needs-session?]
|
||||
wrap-fn (fn [call needs-arena?]
|
||||
`(fn [~@(if const-args? arg-syms ['& args-sym])]
|
||||
~(cond-> call needs-session? wrap-session)))]
|
||||
~(cond-> call needs-arena? wrap-arena)))]
|
||||
`(let [;; NOTE(Joshua): To ensure all arguments are evaluated once and
|
||||
;; in-order, they must be bound here
|
||||
~downcall-sym ~downcall
|
||||
|
|
@ -403,15 +395,15 @@
|
|||
[downcall arg-types ret-type]
|
||||
(if (mem/primitive-type ret-type)
|
||||
(fn native-fn [& args]
|
||||
(with-open [session (mem/stack-session)]
|
||||
(with-open [arena (mem/confined-arena)]
|
||||
(mem/deserialize*
|
||||
(apply downcall (map #(mem/serialize %1 %2 session) args arg-types))
|
||||
(apply downcall (map #(mem/serialize %1 %2 arena) args arg-types))
|
||||
ret-type)))
|
||||
(fn native-fn [& args]
|
||||
(with-open [session (mem/stack-session)]
|
||||
(with-open [arena (mem/confined-arena)]
|
||||
(mem/deserialize-from
|
||||
(apply downcall (mem/session-allocator session)
|
||||
(map #(mem/serialize %1 %2 session) args arg-types))
|
||||
(apply downcall (mem/arena-allocator arena)
|
||||
(map #(mem/serialize %1 %2 arena) args arg-types))
|
||||
ret-type)))))
|
||||
|
||||
(defn make-serde-varargs-wrapper
|
||||
|
|
@ -435,6 +427,7 @@
|
|||
If your `args` and `ret` are constants, then it is more efficient to
|
||||
call [[make-downcall]] followed by [[make-serde-wrapper]] because the latter
|
||||
has an inline definition which will result in less overhead from serdes."
|
||||
;; TODO(Joshua): Add an inline arity for when the args and ret types are constant
|
||||
[symbol args ret]
|
||||
(-> symbol
|
||||
(make-downcall args ret)
|
||||
|
|
@ -474,6 +467,7 @@
|
|||
boxes any primitives passed to it and calls a closed over [[IFn]]."
|
||||
[arg-types ret-type]
|
||||
{:flags #{:public :final}
|
||||
:version 8
|
||||
:fields [{:name "upcall_ifn"
|
||||
:type IFn
|
||||
:flags #{:final}}]
|
||||
|
|
@ -489,7 +483,7 @@
|
|||
{:name :upcall
|
||||
:flags #{:public}
|
||||
:desc (conj (mapv insn-layout arg-types)
|
||||
(coerce-addressable (insn-layout ret-type)))
|
||||
(insn-layout ret-type))
|
||||
:emit [[:aload 0]
|
||||
[:getfield :this "upcall_ifn" IFn]
|
||||
(loop [types arg-types
|
||||
|
|
@ -505,7 +499,7 @@
|
|||
inc)))
|
||||
acc))
|
||||
[:invokeinterface IFn "invoke" (repeat (inc (count arg-types)) Object)]
|
||||
(to-prim-asm (coerce-addressable ret-type))
|
||||
(to-prim-asm ret-type)
|
||||
[(return-for-type ret-type :areturn)]]}]})
|
||||
|
||||
(defn- upcall
|
||||
|
|
@ -518,7 +512,7 @@
|
|||
([args] (method-type args ::mem/void))
|
||||
([args ret]
|
||||
(MethodType/methodType
|
||||
^Class (coerce-addressable (mem/java-layout ret))
|
||||
^Class (mem/java-layout ret)
|
||||
^"[Ljava.lang.Class;" (into-array Class (map mem/java-layout args)))))
|
||||
|
||||
(defn- upcall-handle
|
||||
|
|
@ -536,30 +530,30 @@
|
|||
|
||||
(defn- upcall-serde-wrapper
|
||||
"Creates a function that wraps `f` which deserializes the arguments and
|
||||
serializes the return type in the [[global-session]]."
|
||||
serializes the return type in the [[global-arena]]."
|
||||
[f arg-types ret-type]
|
||||
(fn [& args]
|
||||
(mem/serialize
|
||||
(apply f (map mem/deserialize args arg-types))
|
||||
ret-type
|
||||
(mem/global-session))))
|
||||
(mem/global-arena))))
|
||||
|
||||
(defmethod mem/serialize* ::fn
|
||||
[f [_fn arg-types ret-type & {:keys [raw-fn?]}] session]
|
||||
[f [_fn arg-types ret-type & {:keys [raw-fn?]}] arena]
|
||||
(.upcallStub
|
||||
(Linker/nativeLinker)
|
||||
(cond-> f
|
||||
^MethodHandle (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)
|
||||
session))
|
||||
^FunctionDescriptor (function-descriptor arg-types ret-type)
|
||||
^Arena arena
|
||||
(make-array Linker$Option 0)))
|
||||
|
||||
(defmethod mem/deserialize* ::fn
|
||||
[addr [_fn arg-types ret-type & {:keys [raw-fn?]}]]
|
||||
(when-not (mem/null? addr)
|
||||
(vary-meta
|
||||
(-> addr
|
||||
(MemorySegment/ofAddress mem/pointer-size (mem/connected-session))
|
||||
(-> ^MemorySegment addr
|
||||
(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)))
|
||||
|
|
@ -614,7 +608,7 @@
|
|||
(mem/serialize-into
|
||||
newval (.-type static-var)
|
||||
(.-seg static-var)
|
||||
(mem/global-session))
|
||||
(mem/global-arena))
|
||||
newval)
|
||||
|
||||
(defn fswap!
|
||||
|
|
@ -640,9 +634,8 @@
|
|||
|
||||
See [[freset!]], [[fswap!]]."
|
||||
[symbol-or-addr type]
|
||||
(StaticVariable. (mem/as-segment (.address (ensure-symbol symbol-or-addr))
|
||||
(mem/size-of type)
|
||||
(mem/global-session))
|
||||
(StaticVariable. (.reinterpret ^MemorySegment (ensure-symbol symbol-or-addr)
|
||||
^long (mem/size-of type))
|
||||
type (atom nil)))
|
||||
|
||||
(defmacro defvar
|
||||
|
|
|
|||
|
|
@ -24,7 +24,7 @@
|
|||
(pos? r) (conj [::padding [::mem/padding (- align r)]])
|
||||
:always (conj field))
|
||||
fields))
|
||||
(let [strongest-alignment (mem/align-of struct-spec)
|
||||
(let [strongest-alignment (reduce max (map (comp mem/align-of second) (nth struct-spec 1)))
|
||||
r (rem offset strongest-alignment)]
|
||||
(cond-> aligned-fields
|
||||
(pos? r) (conj [::padding [::mem/padding (- strongest-alignment r)]])))))]
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
(ns coffi.mem
|
||||
"Functions for managing native allocations, memory sessions, and (de)serialization.
|
||||
"Functions for managing native allocations, memory arenas, and (de)serialization.
|
||||
|
||||
For any new type to be implemented, three multimethods must be overriden, but
|
||||
which three depends on the native representation of the type.
|
||||
|
|
@ -13,21 +13,17 @@
|
|||
struct, or array, then [[c-layout]] must be overriden to return the native
|
||||
layout of the type, and [[serialize-into]] and [[deserialize-from]] should be
|
||||
overriden to allow marshaling values of the type into and out of memory
|
||||
segments.
|
||||
|
||||
When writing code that manipulates a segment, it's best practice to
|
||||
use [[with-acquired]] on the [[segment-session]] in order to ensure it won't be
|
||||
released during its manipulation."
|
||||
segments."
|
||||
(:require
|
||||
[clojure.set :as set]
|
||||
[clojure.spec.alpha :as s])
|
||||
(:import
|
||||
(java.lang.foreign
|
||||
Addressable
|
||||
MemoryAddress
|
||||
AddressLayout
|
||||
Arena
|
||||
MemoryLayout
|
||||
MemorySegment
|
||||
MemorySession
|
||||
MemorySegment$Scope
|
||||
SegmentAllocator
|
||||
ValueLayout
|
||||
ValueLayout$OfByte
|
||||
|
|
@ -36,126 +32,71 @@
|
|||
ValueLayout$OfLong
|
||||
ValueLayout$OfChar
|
||||
ValueLayout$OfFloat
|
||||
ValueLayout$OfDouble
|
||||
ValueLayout$OfAddress)
|
||||
ValueLayout$OfDouble)
|
||||
(java.lang.ref Cleaner)
|
||||
(java.util.function Consumer)
|
||||
(java.nio ByteOrder)))
|
||||
|
||||
(set! *warn-on-reflection* true)
|
||||
|
||||
(defn stack-session
|
||||
"Constructs a new session for use only in this thread.
|
||||
(defn confined-arena
|
||||
"Constructs a new arena for use only in this thread.
|
||||
|
||||
The memory allocated within this session is cheap to allocate, like a native
|
||||
stack."
|
||||
(^MemorySession []
|
||||
(MemorySession/openConfined))
|
||||
(^MemorySession [^Cleaner cleaner]
|
||||
(MemorySession/openConfined cleaner)))
|
||||
The memory allocated within this arena is cheap to allocate, like a native
|
||||
stack.
|
||||
|
||||
(defn ^:deprecated stack-scope
|
||||
"Constructs a new scope for use only in this thread.
|
||||
The memory allocated within this arena will be cleared once it is closed, so
|
||||
it is usually a good idea to create it in a [[with-open]] clause."
|
||||
(^Arena []
|
||||
(Arena/ofConfined)))
|
||||
|
||||
The memory allocated within this scope is cheap to allocate, like a native
|
||||
stack."
|
||||
^MemorySession []
|
||||
(stack-session))
|
||||
(defn shared-arena
|
||||
"Constructs a new shared memory arena.
|
||||
|
||||
(defn shared-session
|
||||
"Constructs a new shared memory session.
|
||||
This arena can be shared across threads and memory allocated in it will only
|
||||
be cleaned up once any thread accessing the arena closes it."
|
||||
(^Arena []
|
||||
(Arena/ofShared)))
|
||||
|
||||
This session can be shared across threads and memory allocated in it will only
|
||||
be cleaned up once every thread accessing the session closes it."
|
||||
(^MemorySession []
|
||||
(MemorySession/openShared))
|
||||
(^MemorySession [^Cleaner cleaner]
|
||||
(MemorySession/openShared cleaner)))
|
||||
(defn auto-arena
|
||||
"Constructs a new memory arena that is managed by the garbage collector.
|
||||
|
||||
(defn ^:deprecated shared-scope
|
||||
"Constructs a new shared scope.
|
||||
|
||||
This scope can be shared across threads and memory allocated in it will only
|
||||
be cleaned up once every thread accessing the scope closes it."
|
||||
^MemorySession []
|
||||
(shared-session))
|
||||
|
||||
(defn connected-session
|
||||
"Constructs a new memory session to reclaim all connected resources at once.
|
||||
|
||||
The session may be shared across threads, and all resources created with it
|
||||
will be cleaned up at the same time, when all references have been collected.
|
||||
|
||||
This type of session cannot be closed, and therefore should not be created in
|
||||
a [[with-open]] clause."
|
||||
^MemorySession []
|
||||
(MemorySession/openImplicit))
|
||||
|
||||
(defn ^:deprecated connected-scope
|
||||
"Constructs a new scope to reclaim all connected resources at once.
|
||||
|
||||
The scope may be shared across threads, and all resources created with it will
|
||||
The arena may be shared across threads, and all resources created with it will
|
||||
be cleaned up at the same time, when all references have been collected.
|
||||
|
||||
This type of scope cannot be closed, and therefore should not be created in
|
||||
This type of arena cannot be closed, and therefore should not be created in
|
||||
a [[with-open]] clause."
|
||||
^MemorySession []
|
||||
(connected-session))
|
||||
^Arena []
|
||||
(Arena/ofAuto))
|
||||
|
||||
(defn global-session
|
||||
"Constructs the global session, which will never reclaim its resources.
|
||||
(defn global-arena
|
||||
"Constructs the global arena, which will never reclaim its resources.
|
||||
|
||||
This session may be shared across threads, but is intended mainly in cases
|
||||
where memory is allocated with [[alloc]] but is either never freed or whose
|
||||
management is relinquished to a native library, such as when returned from a
|
||||
callback."
|
||||
^MemorySession []
|
||||
(MemorySession/global))
|
||||
|
||||
(defn ^:deprecated global-scope
|
||||
"Constructs the global scope, which will never reclaim its resources.
|
||||
|
||||
This scope may be shared across threads, but is intended mainly in cases where
|
||||
This arena may be shared across threads, but is intended mainly in cases where
|
||||
memory is allocated with [[alloc]] but is either never freed or whose
|
||||
management is relinquished to a native library, such as when returned from a
|
||||
callback."
|
||||
^MemorySession []
|
||||
(global-session))
|
||||
^Arena []
|
||||
(Arena/global))
|
||||
|
||||
(defn session-allocator
|
||||
"Constructs a segment allocator from the given `session`.
|
||||
(defn arena-allocator
|
||||
"Constructs a [[SegmentAllocator]] from the given [[Arena]].
|
||||
|
||||
This is primarily used when working with unwrapped downcall functions. When a
|
||||
downcall function returns a non-primitive type, it must be provided with an
|
||||
allocator."
|
||||
^SegmentAllocator [^MemorySession session]
|
||||
(SegmentAllocator/newNativeArena session))
|
||||
|
||||
(defn ^:deprecated scope-allocator
|
||||
"Constructs a segment allocator from the given `scope`.
|
||||
|
||||
This is primarily used when working with unwrapped downcall functions. When a
|
||||
downcall function returns a non-primitive type, it must be provided with an
|
||||
allocator."
|
||||
^SegmentAllocator [^MemorySession scope]
|
||||
(session-allocator scope))
|
||||
|
||||
(defn segment-session
|
||||
"Gets the memory session used to construct the `segment`."
|
||||
^MemorySession [segment]
|
||||
(.session ^MemorySegment segment))
|
||||
|
||||
(defn ^:deprecated segment-scope
|
||||
"Gets the scope used to construct the `segment`."
|
||||
^MemorySession [segment]
|
||||
(segment-session segment))
|
||||
^SegmentAllocator [^Arena arena]
|
||||
(reify SegmentAllocator
|
||||
(^MemorySegment allocate [_this ^long byte-size ^long byte-alignment]
|
||||
(.allocate arena ^long byte-size ^long byte-alignment))))
|
||||
|
||||
(defn alloc
|
||||
"Allocates `size` bytes.
|
||||
|
||||
If a `session` is provided, the allocation will be reclaimed when it is closed."
|
||||
(^MemorySegment [size] (alloc size (connected-session)))
|
||||
(^MemorySegment [size session] (MemorySegment/allocateNative (long size) ^MemorySession session))
|
||||
(^MemorySegment [size alignment session] (MemorySegment/allocateNative (long size) (long alignment) ^MemorySession session)))
|
||||
If an `arena` is provided, the allocation will be reclaimed when it is closed."
|
||||
(^MemorySegment [size] (alloc size (auto-arena)))
|
||||
(^MemorySegment [size arena] (.allocate ^Arena arena (long size)))
|
||||
(^MemorySegment [size alignment arena] (.allocate ^Arena arena (long size) (long alignment))))
|
||||
|
||||
(defn alloc-with
|
||||
"Allocates `size` bytes using the `allocator`."
|
||||
|
|
@ -164,47 +105,24 @@
|
|||
(^MemorySegment [allocator size alignment]
|
||||
(.allocate ^SegmentAllocator allocator (long size) (long alignment))))
|
||||
|
||||
(defmacro with-acquired
|
||||
"Acquires one or more `sessions` until the `body` completes.
|
||||
|
||||
This is only necessary to do on shared sessions, however if you are operating
|
||||
on an arbitrary passed session, it is best practice to wrap code that
|
||||
interacts with it wrapped in this."
|
||||
{:style/indent 1}
|
||||
[sessions & body]
|
||||
(if (seq sessions)
|
||||
`(let [session# ~(first sessions)
|
||||
res# (volatile! ::invalid-value)]
|
||||
(.whileAlive
|
||||
^MemorySession session#
|
||||
(^:once fn* []
|
||||
(vreset! res#
|
||||
(with-acquired [~@(rest sessions)]
|
||||
~@body))))
|
||||
@res#)
|
||||
`(do ~@body)))
|
||||
(s/fdef with-acquired
|
||||
:args (s/cat :sessions any?
|
||||
:body (s/* any?)))
|
||||
|
||||
(defn address-of
|
||||
"Gets the address of a given segment.
|
||||
|
||||
This value can be used as an argument to functions which take a pointer."
|
||||
^MemoryAddress [addressable]
|
||||
(.address ^Addressable addressable))
|
||||
^long [addressable]
|
||||
(.address ^MemorySegment addressable))
|
||||
|
||||
(defn null?
|
||||
"Checks if a memory address is null."
|
||||
[addr]
|
||||
(or (.equals (MemoryAddress/NULL) addr) (not addr)))
|
||||
(or (.equals (MemorySegment/NULL) addr) (not addr)))
|
||||
|
||||
(defn address?
|
||||
"Checks if an object is a memory address.
|
||||
|
||||
`nil` is considered an address."
|
||||
[addr]
|
||||
(or (nil? addr) (instance? MemoryAddress addr)))
|
||||
(or (nil? addr) (instance? MemorySegment addr)))
|
||||
|
||||
(defn slice
|
||||
"Get a slice over the `segment` with the given `offset`."
|
||||
|
|
@ -213,46 +131,47 @@
|
|||
(^MemorySegment [segment offset size]
|
||||
(.asSlice ^MemorySegment segment (long offset) (long size))))
|
||||
|
||||
(defn slice-into
|
||||
"Get a slice into the `segment` starting at the `address`."
|
||||
(^MemorySegment [address segment]
|
||||
(.asSlice ^MemorySegment segment ^MemoryAddress address))
|
||||
(^MemorySegment [address segment size]
|
||||
(.asSlice ^MemorySegment segment ^MemoryAddress address (long size))))
|
||||
(defn reinterpret
|
||||
"Reinterprets the `segment` as having the passed `size`.
|
||||
|
||||
(defn with-offset
|
||||
"Get a new address `offset` from the old `address`."
|
||||
^MemoryAddress [address offset]
|
||||
(.addOffset ^MemoryAddress address (long offset)))
|
||||
|
||||
(defn add-close-action!
|
||||
"Adds a 0-arity function to be run when the `session` closes."
|
||||
[^MemorySession session ^Runnable action]
|
||||
(.addCloseAction session action)
|
||||
nil)
|
||||
If `arena` is passed, the scope of the `segment` is associated with the arena,
|
||||
as well as its access constraints. If `cleanup` is passed, it will be a
|
||||
1-argument function of a fresh memory segment backed by the same memory as the
|
||||
returned segment which should perform any required cleanup operations. It will
|
||||
be called when the `arena` is closed."
|
||||
(^MemorySegment [^MemorySegment segment size]
|
||||
(.reinterpret segment (long size) (auto-arena) nil))
|
||||
(^MemorySegment [^MemorySegment segment size ^Arena arena]
|
||||
(.reinterpret segment (long size) arena nil))
|
||||
(^MemorySegment [^MemorySegment segment size ^Arena arena cleanup]
|
||||
(.reinterpret segment (long size) arena
|
||||
(reify Consumer
|
||||
(accept [_this segment]
|
||||
(cleanup segment))))))
|
||||
|
||||
(defn as-segment
|
||||
"Dereferences an `address` into a memory segment associated with the `session`."
|
||||
(^MemorySegment [^MemoryAddress address size]
|
||||
(MemorySegment/ofAddress address (long size) (connected-session)))
|
||||
(^MemorySegment [^MemoryAddress address size session]
|
||||
(MemorySegment/ofAddress address (long size) session)))
|
||||
"Dereferences an `address` into a memory segment associated with the `arena` (default global)."
|
||||
(^MemorySegment [^long address]
|
||||
(MemorySegment/ofAddress address))
|
||||
(^MemorySegment [^long address size]
|
||||
(reinterpret (MemorySegment/ofAddress address) size))
|
||||
(^MemorySegment [^long address size ^Arena arena]
|
||||
(reinterpret (MemorySegment/ofAddress address) (long size) arena nil))
|
||||
(^MemorySegment [^long address size ^Arena arena cleanup]
|
||||
(reinterpret (MemorySegment/ofAddress address) (long size) arena cleanup)))
|
||||
|
||||
(defn copy-segment
|
||||
"Copies the content to `dest` from `src`.
|
||||
|
||||
Returns `dest`."
|
||||
^MemorySegment [^MemorySegment dest ^MemorySegment src]
|
||||
(with-acquired [(segment-session src) (segment-session dest)]
|
||||
(.copyFrom dest src)
|
||||
dest))
|
||||
(.copyFrom dest src))
|
||||
|
||||
(defn clone-segment
|
||||
"Clones the content of `segment` into a new segment of the same size."
|
||||
(^MemorySegment [segment] (clone-segment segment (connected-session)))
|
||||
(^MemorySegment [^MemorySegment segment session]
|
||||
(with-acquired [(segment-session segment) session]
|
||||
(copy-segment ^MemorySegment (alloc (.byteSize segment) session) segment))))
|
||||
(^MemorySegment [segment] (clone-segment segment (auto-arena)))
|
||||
(^MemorySegment [^MemorySegment segment ^Arena arena]
|
||||
(copy-segment ^MemorySegment (alloc (.byteSize segment) arena) segment)))
|
||||
|
||||
(defn slice-segments
|
||||
"Constructs a lazy seq of `size`-length memory segments, sliced from `segment`."
|
||||
|
|
@ -307,7 +226,7 @@
|
|||
"The [[MemoryLayout]] for a c-sized double in [[native-endian]] [[ByteOrder]]."
|
||||
ValueLayout/JAVA_DOUBLE)
|
||||
|
||||
(def ^ValueLayout$OfAddress pointer-layout
|
||||
(def ^AddressLayout pointer-layout
|
||||
"The [[MemoryLayout]] for a native pointer in [[native-endian]] [[ByteOrder]]."
|
||||
ValueLayout/ADDRESS)
|
||||
|
||||
|
|
@ -517,20 +436,20 @@
|
|||
(.get segment (.withOrder ^ValueLayout$OfDouble double-layout byte-order) offset)))
|
||||
|
||||
(defn read-address
|
||||
"Reads a [[MemoryAddress]] from the `segment`, at an optional `offset`."
|
||||
"Reads an address from the `segment`, at an optional `offset`, wrapped in a [[MemorySegment]]."
|
||||
{:inline
|
||||
(fn read-address-inline
|
||||
([segment]
|
||||
`(let [segment# ~segment]
|
||||
(.get ^MemorySegment segment# ^ValueLayout$OfAddress pointer-layout 0)))
|
||||
(.get ^MemorySegment segment# ^AddressLayout pointer-layout 0)))
|
||||
([segment offset]
|
||||
`(let [segment# ~segment
|
||||
offset# ~offset]
|
||||
(.get ^MemorySegment segment# ^ValueLayout$OfAddress pointer-layout offset#))))}
|
||||
(^MemoryAddress [^MemorySegment segment]
|
||||
(.get segment ^ValueLayout$OfAddress pointer-layout 0))
|
||||
(^MemoryAddress [^MemorySegment segment ^long offset]
|
||||
(.get segment ^ValueLayout$OfAddress pointer-layout offset)))
|
||||
(.get ^MemorySegment segment# ^AddressLayout pointer-layout offset#))))}
|
||||
(^MemorySegment [^MemorySegment segment]
|
||||
(.get segment ^AddressLayout pointer-layout 0))
|
||||
(^MemorySegment [^MemorySegment segment ^long offset]
|
||||
(.get segment ^AddressLayout pointer-layout offset)))
|
||||
|
||||
(defn write-byte
|
||||
"Writes a [[byte]] to the `segment`, at an optional `offset`."
|
||||
|
|
@ -715,22 +634,22 @@
|
|||
(.set segment (.withOrder ^ValueLayout$OfDouble double-layout byte-order) offset value)))
|
||||
|
||||
(defn write-address
|
||||
"Writes a [[MemoryAddress]] to the `segment`, at an optional `offset`."
|
||||
"Writes the address of the [[MemorySegment]] `value` to the `segment`, at an optional `offset`."
|
||||
{:inline
|
||||
(fn write-address-inline
|
||||
([segment value]
|
||||
`(let [segment# ~segment
|
||||
value# ~value]
|
||||
(.set ^MemorySegment segment# ^ValueLayout$OfAddress pointer-layout 0 ^Addressable value#)))
|
||||
(.set ^MemorySegment segment# ^AddressLayout pointer-layout 0 ^MemorySegment value#)))
|
||||
([segment offset value]
|
||||
`(let [segment# ~segment
|
||||
offset# ~offset
|
||||
value# ~value]
|
||||
(.set ^MemorySegment segment# ^ValueLayout$OfAddress pointer-layout offset# ^Addressable value#))))}
|
||||
(^MemoryAddress [^MemorySegment segment ^MemoryAddress value]
|
||||
(.set segment ^ValueLayout$OfAddress pointer-layout 0 value))
|
||||
(^MemoryAddress [^MemorySegment segment ^long offset ^MemoryAddress value]
|
||||
(.set segment ^ValueLayout$OfAddress pointer-layout offset value)))
|
||||
(.set ^MemorySegment segment# ^AddressLayout pointer-layout offset# ^MemorySegment value#))))}
|
||||
([^MemorySegment segment ^MemorySegment value]
|
||||
(.set segment ^AddressLayout pointer-layout 0 value))
|
||||
([^MemorySegment segment ^long offset ^MemorySegment value]
|
||||
(.set segment ^AddressLayout pointer-layout offset value)))
|
||||
|
||||
(defn- type-dispatch
|
||||
"Gets a type dispatch value from a (potentially composite) type."
|
||||
|
|
@ -867,7 +786,7 @@
|
|||
::char Byte/TYPE
|
||||
::float Float/TYPE
|
||||
::double Double/TYPE
|
||||
::pointer MemoryAddress
|
||||
::pointer MemorySegment
|
||||
::void Void/TYPE})
|
||||
|
||||
(defn java-layout
|
||||
|
|
@ -894,8 +813,8 @@
|
|||
|
||||
(defn alloc-instance
|
||||
"Allocates a memory segment for the given `type`."
|
||||
(^MemorySegment [type] (alloc-instance type (connected-session)))
|
||||
(^MemorySegment [type session] (MemorySegment/allocateNative ^long (size-of type) ^MemorySession session)))
|
||||
(^MemorySegment [type] (alloc-instance type (auto-arena)))
|
||||
(^MemorySegment [type arena] (.allocate ^Arena arena ^long (size-of type) ^long (align-of type))))
|
||||
|
||||
(declare serialize serialize-into)
|
||||
|
||||
|
|
@ -903,136 +822,130 @@
|
|||
"Constructs a serialized version of the `obj` and returns it.
|
||||
|
||||
Any new allocations made during the serialization should be tied to the given
|
||||
`session`, except in extenuating circumstances.
|
||||
`arena`, except in extenuating circumstances.
|
||||
|
||||
This method should only be implemented for types that serialize to primitives."
|
||||
(fn
|
||||
#_{:clj-kondo/ignore [:unused-binding]}
|
||||
[obj type session]
|
||||
[obj type arena]
|
||||
(type-dispatch type)))
|
||||
|
||||
(defmethod serialize* :default
|
||||
[obj type _session]
|
||||
[obj type _arena]
|
||||
(throw (ex-info "Attempted to serialize a non-primitive type with primitive methods"
|
||||
{:type type
|
||||
:object obj})))
|
||||
|
||||
(defmethod serialize* ::byte
|
||||
[obj _type _session]
|
||||
[obj _type _arena]
|
||||
(byte obj))
|
||||
|
||||
(defmethod serialize* ::short
|
||||
[obj _type _session]
|
||||
[obj _type _arena]
|
||||
(short obj))
|
||||
|
||||
(defmethod serialize* ::int
|
||||
[obj _type _session]
|
||||
[obj _type _arena]
|
||||
(int obj))
|
||||
|
||||
(defmethod serialize* ::long
|
||||
[obj _type _session]
|
||||
[obj _type _arena]
|
||||
(long obj))
|
||||
|
||||
(defmethod serialize* ::char
|
||||
[obj _type _session]
|
||||
[obj _type _arena]
|
||||
(char obj))
|
||||
|
||||
(defmethod serialize* ::float
|
||||
[obj _type _session]
|
||||
[obj _type _arena]
|
||||
(float obj))
|
||||
|
||||
(defmethod serialize* ::double
|
||||
[obj _type _session]
|
||||
[obj _type _arena]
|
||||
(double obj))
|
||||
|
||||
(defmethod serialize* ::pointer
|
||||
[obj type session]
|
||||
[obj type arena]
|
||||
(if-not (null? obj)
|
||||
(if (sequential? type)
|
||||
(with-acquired [session]
|
||||
(let [segment (alloc-instance (second type) session)]
|
||||
(serialize-into obj (second type) segment session)
|
||||
(address-of segment)))
|
||||
(let [segment (alloc-instance (second type) arena)]
|
||||
(serialize-into obj (second type) segment arena)
|
||||
(address-of segment))
|
||||
obj)
|
||||
(MemoryAddress/NULL)))
|
||||
(MemorySegment/NULL)))
|
||||
|
||||
(defmethod serialize* ::void
|
||||
[_obj _type _session]
|
||||
[_obj _type _arena]
|
||||
nil)
|
||||
|
||||
(defmulti serialize-into
|
||||
"Writes a serialized version of the `obj` to the given `segment`.
|
||||
|
||||
Any new allocations made during the serialization should be tied to the given
|
||||
`session`, except in extenuating circumstances.
|
||||
`arena`, except in extenuating circumstances.
|
||||
|
||||
This method should be implemented for any type which does not
|
||||
override [[c-layout]].
|
||||
|
||||
For any other type, this will serialize it as [[serialize*]] before writing
|
||||
the result value into the `segment`.
|
||||
|
||||
Implementations of this should be inside a [[with-acquired]] block for the
|
||||
`session` if they perform multiple memory operations."
|
||||
the result value into the `segment`."
|
||||
(fn
|
||||
#_{:clj-kondo/ignore [:unused-binding]}
|
||||
[obj type segment session]
|
||||
[obj type segment arena]
|
||||
(type-dispatch type)))
|
||||
|
||||
(defmethod serialize-into :default
|
||||
[obj type segment session]
|
||||
[obj type segment arena]
|
||||
(if-some [prim-layout (primitive-type type)]
|
||||
(with-acquired [(segment-session segment) session]
|
||||
(serialize-into (serialize* obj type session) prim-layout segment session))
|
||||
(serialize-into (serialize* obj type arena) prim-layout segment arena)
|
||||
(throw (ex-info "Attempted to serialize an object to a type that has not been overridden"
|
||||
{:type type
|
||||
:object obj}))))
|
||||
|
||||
(defmethod serialize-into ::byte
|
||||
[obj _type segment _session]
|
||||
[obj _type segment _arena]
|
||||
(write-byte segment (byte obj)))
|
||||
|
||||
(defmethod serialize-into ::short
|
||||
[obj type segment _session]
|
||||
[obj type segment _arena]
|
||||
(if (sequential? type)
|
||||
(write-short segment 0 (second type) (short obj))
|
||||
(write-short segment (short obj))))
|
||||
|
||||
(defmethod serialize-into ::int
|
||||
[obj type segment _session]
|
||||
[obj type segment _arena]
|
||||
(if (sequential? type)
|
||||
(write-int segment 0 (second type) (int obj))
|
||||
(write-int segment (int obj))))
|
||||
|
||||
(defmethod serialize-into ::long
|
||||
[obj type segment _session]
|
||||
[obj type segment _arena]
|
||||
(if (sequential? type)
|
||||
(write-long segment 0 (second type) (long obj))
|
||||
(write-long segment (long obj))))
|
||||
|
||||
(defmethod serialize-into ::char
|
||||
[obj _type segment _session]
|
||||
[obj _type segment _arena]
|
||||
(write-char segment (char obj)))
|
||||
|
||||
(defmethod serialize-into ::float
|
||||
[obj type segment _session]
|
||||
[obj type segment _arena]
|
||||
(if (sequential? type)
|
||||
(write-float segment 0 (second type) (float obj))
|
||||
(write-float segment (float obj))))
|
||||
|
||||
(defmethod serialize-into ::double
|
||||
[obj type segment _session]
|
||||
[obj type segment _arena]
|
||||
(if (sequential? type)
|
||||
(write-double segment 0 (second type) (double obj))
|
||||
(write-double segment (double obj))))
|
||||
|
||||
(defmethod serialize-into ::pointer
|
||||
[obj type segment session]
|
||||
(with-acquired [(segment-session segment) session]
|
||||
[obj type segment arena]
|
||||
(write-address
|
||||
segment
|
||||
(cond-> obj
|
||||
(sequential? type) (serialize* type session)))))
|
||||
(sequential? type) (serialize* type arena))))
|
||||
|
||||
(defn serialize
|
||||
"Serializes an arbitrary type.
|
||||
|
|
@ -1040,12 +953,12 @@
|
|||
For types which have a primitive representation, this serializes into that
|
||||
representation. For types which do not, it allocates a new segment and
|
||||
serializes into that."
|
||||
([obj type] (serialize obj type (connected-session)))
|
||||
([obj type session]
|
||||
([obj type] (serialize obj type (auto-arena)))
|
||||
([obj type arena]
|
||||
(if (primitive-type type)
|
||||
(serialize* obj type session)
|
||||
(let [segment (alloc-instance type session)]
|
||||
(serialize-into obj type segment session)
|
||||
(serialize* obj type arena)
|
||||
(let [segment (alloc-instance type arena)]
|
||||
(serialize-into obj type segment arena)
|
||||
segment))))
|
||||
|
||||
(declare deserialize deserialize*)
|
||||
|
|
@ -1054,10 +967,7 @@
|
|||
"Deserializes the given segment into a Clojure data structure.
|
||||
|
||||
For types that serialize to primitives, a default implementation will
|
||||
deserialize the primitive before calling [[deserialize*]].
|
||||
|
||||
Implementations of this should be inside a [[with-acquired]] block for the the
|
||||
`segment`'s session if they perform multiple memory operations."
|
||||
deserialize the primitive before calling [[deserialize*]]."
|
||||
(fn
|
||||
#_{:clj-kondo/ignore [:unused-binding]}
|
||||
[segment type]
|
||||
|
|
@ -1113,9 +1023,8 @@
|
|||
|
||||
(defmethod deserialize-from ::pointer
|
||||
[segment type]
|
||||
(with-acquired [(segment-session segment)]
|
||||
(cond-> (read-address segment)
|
||||
(sequential? type) (deserialize* type))))
|
||||
(sequential? type) (deserialize* type)))
|
||||
|
||||
(defmulti deserialize*
|
||||
"Deserializes a primitive object into a Clojure data structure.
|
||||
|
|
@ -1165,8 +1074,11 @@
|
|||
[addr type]
|
||||
(when-not (null? addr)
|
||||
(if (sequential? type)
|
||||
(deserialize-from (as-segment addr (size-of (second type)))
|
||||
(second type))
|
||||
(let [target-type (second type)]
|
||||
(deserialize-from
|
||||
(.reinterpret ^MemorySegment (read-address addr)
|
||||
^long (size-of target-type))
|
||||
target-type))
|
||||
addr)))
|
||||
|
||||
(defmethod deserialize* ::void
|
||||
|
|
@ -1188,8 +1100,7 @@
|
|||
(defn seq-of
|
||||
"Constructs a lazy sequence of `type` elements deserialized from `segment`."
|
||||
[type segment]
|
||||
(with-acquired [(segment-session segment)]
|
||||
(map #(deserialize % type) (slice-segments segment (size-of type)))))
|
||||
(map #(deserialize % type) (slice-segments segment (size-of type))))
|
||||
|
||||
;;; Raw composite types
|
||||
;; TODO(Joshua): Ensure that all the raw values don't have anything happen on
|
||||
|
|
@ -1200,7 +1111,7 @@
|
|||
(c-layout type))
|
||||
|
||||
(defmethod serialize-into ::raw
|
||||
[obj _type segment _session]
|
||||
[obj _type segment _arena]
|
||||
(if (instance? MemorySegment obj)
|
||||
(copy-segment segment obj)
|
||||
obj))
|
||||
|
|
@ -1218,15 +1129,15 @@
|
|||
::pointer)
|
||||
|
||||
(defmethod serialize* ::c-string
|
||||
[obj _type session]
|
||||
[obj _type ^Arena arena]
|
||||
(if obj
|
||||
(address-of (.allocateUtf8String (session-allocator session) ^String obj))
|
||||
(MemoryAddress/NULL)))
|
||||
(.allocateFrom arena ^String obj)
|
||||
(MemorySegment/NULL)))
|
||||
|
||||
(defmethod deserialize* ::c-string
|
||||
[addr _type]
|
||||
(when-not (null? addr)
|
||||
(.getUtf8String ^MemoryAddress addr 0)))
|
||||
(.getString (.reinterpret ^MemorySegment addr Integer/MAX_VALUE) 0)))
|
||||
|
||||
;;; Union types
|
||||
|
||||
|
|
@ -1237,7 +1148,7 @@
|
|||
(into-array MemoryLayout items))))
|
||||
|
||||
(defmethod serialize-into ::union
|
||||
[obj [_union _types & {:keys [dispatch extract]} :as type] segment session]
|
||||
[obj [_union _types & {:keys [dispatch extract]} :as type] segment arena]
|
||||
(when-not dispatch
|
||||
(throw (ex-info "Attempted to serialize a union with no dispatch function"
|
||||
{:type type
|
||||
|
|
@ -1249,7 +1160,7 @@
|
|||
obj)
|
||||
type
|
||||
segment
|
||||
session)))
|
||||
arena)))
|
||||
|
||||
(defmethod deserialize-from ::union
|
||||
[segment type]
|
||||
|
|
@ -1266,7 +1177,7 @@
|
|||
(into-array MemoryLayout fields))))
|
||||
|
||||
(defmethod serialize-into ::struct
|
||||
[obj [_struct fields] segment session]
|
||||
[obj [_struct fields] segment arena]
|
||||
(loop [offset 0
|
||||
fields fields]
|
||||
(when (seq fields)
|
||||
|
|
@ -1274,7 +1185,7 @@
|
|||
size (size-of type)]
|
||||
(serialize-into
|
||||
(get obj field) type
|
||||
(slice segment offset size) session)
|
||||
(slice segment offset size) arena)
|
||||
(recur (long (+ offset size)) (rest fields))))))
|
||||
|
||||
(defmethod deserialize-from ::struct
|
||||
|
|
@ -1297,10 +1208,10 @@
|
|||
|
||||
(defmethod c-layout ::padding
|
||||
[[_padding size]]
|
||||
(MemoryLayout/paddingLayout (* 8 size)))
|
||||
(MemoryLayout/paddingLayout size))
|
||||
|
||||
(defmethod serialize-into ::padding
|
||||
[_obj [_padding _size] _segment _session]
|
||||
[_obj [_padding _size] _segment _arena]
|
||||
nil)
|
||||
|
||||
(defmethod deserialize-from ::padding
|
||||
|
|
@ -1316,9 +1227,9 @@
|
|||
(c-layout type)))
|
||||
|
||||
(defmethod serialize-into ::array
|
||||
[obj [_array type count] segment session]
|
||||
[obj [_array type count] segment arena]
|
||||
(dorun
|
||||
(map #(serialize-into %1 type %2 session)
|
||||
(map #(serialize-into %1 type %2 arena)
|
||||
obj
|
||||
(slice-segments (slice segment 0 (* count (size-of type)))
|
||||
(size-of type)))))
|
||||
|
|
@ -1363,10 +1274,10 @@
|
|||
variants))))
|
||||
|
||||
(defmethod serialize* ::enum
|
||||
[obj [_enum variants & {:keys [repr]}] session]
|
||||
[obj [_enum variants & {:keys [repr]}] arena]
|
||||
(serialize* ((enum-variants-map variants) obj)
|
||||
(or repr ::int)
|
||||
session))
|
||||
arena))
|
||||
|
||||
(defmethod deserialize* ::enum
|
||||
[obj [_enum variants & {:keys [_repr]}]]
|
||||
|
|
@ -1381,9 +1292,9 @@
|
|||
::int))
|
||||
|
||||
(defmethod serialize* ::flagset
|
||||
[obj [_flagset bits & {:keys [repr]}] session]
|
||||
[obj [_flagset bits & {:keys [repr]}] arena]
|
||||
(let [bits-map (enum-variants-map bits)]
|
||||
(reduce #(bit-set %1 (get bits-map %2)) (serialize* 0 (or repr ::int) session) obj)))
|
||||
(reduce #(bit-set %1 (get bits-map %2)) (serialize* 0 (or repr ::int) arena) obj)))
|
||||
|
||||
(defmethod deserialize* ::flagset
|
||||
[obj [_flagset bits & {:keys [repr]}]]
|
||||
|
|
@ -1415,8 +1326,8 @@
|
|||
[_type#]
|
||||
(primitive-type aliased#))
|
||||
(defmethod serialize* ~new-type
|
||||
[obj# _type# session#]
|
||||
(serialize* obj# aliased# session#))
|
||||
[obj# _type# arena#]
|
||||
(serialize* obj# aliased# arena#))
|
||||
(defmethod deserialize* ~new-type
|
||||
[obj# _type#]
|
||||
(deserialize* obj# aliased#)))
|
||||
|
|
@ -1425,8 +1336,8 @@
|
|||
[_type#]
|
||||
(c-layout aliased#))
|
||||
(defmethod serialize-into ~new-type
|
||||
[obj# _type# segment# session#]
|
||||
(serialize-into obj# aliased# segment# session#))
|
||||
[obj# _type# segment# arena#]
|
||||
(serialize-into obj# aliased# segment# arena#))
|
||||
(defmethod deserialize-from ~new-type
|
||||
[segment# _type#]
|
||||
(deserialize-from segment# aliased#)))))
|
||||
|
|
|
|||
|
|
@ -10,6 +10,8 @@ import java.lang.foreign.*;
|
|||
*/
|
||||
public class Loader {
|
||||
|
||||
static SymbolLookup lookup = Linker.nativeLinker().defaultLookup().or(SymbolLookup.loaderLookup());
|
||||
|
||||
/**
|
||||
* Loads a library from a given absolute file path.
|
||||
*
|
||||
|
|
@ -37,7 +39,6 @@ public class Loader {
|
|||
* @param symbol The name of the symbol to load from a library.
|
||||
*/
|
||||
public static MemorySegment findSymbol(String symbol) {
|
||||
return Linker.nativeLinker().defaultLookup().lookup(symbol)
|
||||
.orElseGet(() -> SymbolLookup.loaderLookup().lookup(symbol).orElse(null));
|
||||
return lookup.find(symbol).orElse(null);
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -26,10 +26,18 @@ CString upcall_test(StringFactory fun) {
|
|||
return fun();
|
||||
}
|
||||
|
||||
int upcall_test2(int (*f)(void)) {
|
||||
return f();
|
||||
}
|
||||
|
||||
int counter = 0;
|
||||
|
||||
static char* responses[] = { "Hello, world!", "Goodbye friend.", "co'oi prenu" };
|
||||
|
||||
char* upcall_test_int_fn_string_ret(int (*f)(void)) {
|
||||
return responses[f()];
|
||||
}
|
||||
|
||||
CString get_string1(void) {
|
||||
return responses[counter++ % 3];
|
||||
}
|
||||
|
|
@ -63,3 +71,10 @@ AlignmentTest get_struct() {
|
|||
|
||||
return ret;
|
||||
}
|
||||
|
||||
void test_call_with_trailing_string_arg(int a, int b, char* text) {
|
||||
printf("call of `test_call_with_trailing_string_arg` with a=%i b=%i text='%s'",1,2,text);
|
||||
printf("\r ");
|
||||
return;
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -29,8 +29,18 @@
|
|||
|
||||
(t/deftest can-make-upcall
|
||||
(t/is (= ((ffi/cfn "upcall_test" [[::ffi/fn [] ::mem/c-string]] ::mem/c-string)
|
||||
(fn [] "hello"))
|
||||
"hello")))
|
||||
(fn [] "hello from clojure from c from clojure"))
|
||||
"hello from clojure from c from clojure")))
|
||||
|
||||
(t/deftest can-make-upcall2
|
||||
(t/is (= ((ffi/cfn "upcall_test2" [[::ffi/fn [] ::mem/int]] ::mem/int)
|
||||
(fn [] 5))
|
||||
5)))
|
||||
|
||||
(t/deftest can-make-upcall-int-fn-string-ret
|
||||
(t/is (= ((ffi/cfn "upcall_test_int_fn_string_ret" [[::ffi/fn [] ::mem/int]] ::mem/c-string)
|
||||
(fn [] 2))
|
||||
"co'oi prenu")))
|
||||
|
||||
(mem/defalias ::alignment-test
|
||||
(layout/with-c-layout
|
||||
|
|
@ -49,3 +59,12 @@
|
|||
(ffi/freset! (ffi/static-variable "counter" ::mem/int) 1)
|
||||
(t/is (= ((ffi/cfn "get_string1" [] ::mem/c-string))
|
||||
"Goodbye friend.")))
|
||||
|
||||
(t/deftest can-call-with-trailing-string-arg
|
||||
(t/is
|
||||
(=
|
||||
((ffi/cfn "test_call_with_trailing_string_arg"
|
||||
[::mem/int ::mem/int ::mem/c-string]
|
||||
::mem/void)
|
||||
1 2 "third arg"))))
|
||||
|
||||
|
|
|
|||
32
test/clj/coffi/mem_test.clj
Normal file
32
test/clj/coffi/mem_test.clj
Normal file
|
|
@ -0,0 +1,32 @@
|
|||
(ns coffi.mem-test
|
||||
(:require
|
||||
[clojure.test :as t]
|
||||
[coffi.ffi :as ffi]
|
||||
[coffi.layout :as layout]
|
||||
[coffi.mem :as mem])
|
||||
(:import
|
||||
(java.lang.foreign
|
||||
AddressLayout
|
||||
Arena
|
||||
MemoryLayout
|
||||
MemorySegment
|
||||
MemorySegment$Scope
|
||||
SegmentAllocator
|
||||
ValueLayout
|
||||
ValueLayout$OfByte
|
||||
ValueLayout$OfShort
|
||||
ValueLayout$OfInt
|
||||
ValueLayout$OfLong
|
||||
ValueLayout$OfChar
|
||||
ValueLayout$OfFloat
|
||||
ValueLayout$OfDouble)
|
||||
(java.lang.ref Cleaner)
|
||||
(java.nio ByteOrder)))
|
||||
|
||||
(ffi/load-library "target/ffi_test.so")
|
||||
|
||||
(t/deftest can-serialize-string
|
||||
(t/is
|
||||
(instance? MemorySegment (mem/serialize "this is a string" ::mem/c-string))))
|
||||
|
||||
|
||||
Loading…
Reference in a new issue