diff --git a/.envrc b/.envrc new file mode 100644 index 0000000..3550a30 --- /dev/null +++ b/.envrc @@ -0,0 +1 @@ +use flake diff --git a/.gitignore b/.gitignore index 76247e5..dab8849 100644 --- a/.gitignore +++ b/.gitignore @@ -14,3 +14,4 @@ /.socket-repl-port .hgignore .hg/ +/.direnv diff --git a/CHANGELOG.md b/CHANGELOG.md index 34ec353..985b21c 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index ab15e44..fa0b2aa 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,23 @@ # coffi [![Clojars Project](https://img.shields.io/clojars/v/org.suskalo/coffi.svg)](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 diff --git a/build.clj b/build.clj index bdbf2ba..c20f633 100644 --- a/build.clj +++ b/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" - "src/java/coffi/ffi/Loader.java" - "-d" class-dir - "-target" "19" - "-source" "19"]}) + (let [compilation-result + (b/process {:command-args ["javac" + "src/java/coffi/ffi/Loader.java" + "-d" class-dir + "-target" "22" + "-source" "22"]})] + (when-not (zero? (:exit compilation-result)) + (b/delete {:path class-dir}))) opts) (defn- write-pom diff --git a/deps.edn b/deps.edn index d0e1469..cc8687e 100644 --- a/deps.edn +++ b/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"}} diff --git a/docs/coffi.ffi.html b/docs/coffi.ffi.html index fe8810e..638e909 100644 --- a/docs/coffi.ffi.html +++ b/docs/coffi.ffi.html @@ -1,20 +1,41 @@ -coffi.ffi documentation

Project

Namespaces

Public Vars

coffi.ffi

Functions for creating handles to native functions and loading native libraries.

cfn

(cfn symbol args ret)

Constructs a Clojure function to call the native function referenced by symbol.

+coffi.ffi documentation

Project

Namespaces

Public Vars

coffi.ffi

Functions for creating handles to native functions and loading native libraries.

+

cfn

(cfn symbol args ret)

Constructs a Clojure function to call the native function referenced by symbol.

The function returned will serialize any passed arguments into the args types, and deserialize the return to the ret type.

-

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.

view source

const

(const symbol-or-addr type)

Gets the value of a constant stored in symbol-or-addr.

view source

defcfn

macro

(defcfn name docstring? attr-map? symbol arg-types ret-type)(defcfn name docstring? attr-map? symbol arg-types ret-type native-fn & fn-tail)

Defines a Clojure function which maps to a native function.

+

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.

+
view source

const

(const symbol-or-addr type)

Gets the value of a constant stored in symbol-or-addr.

+
view source

defcfn

macro

(defcfn name docstring? attr-map? symbol arg-types ret-type)(defcfn name docstring? attr-map? symbol arg-types ret-type native-fn & fn-tail)

Defines a Clojure function which maps to a native function.

name is the symbol naming the resulting var. symbol is a symbol or string naming the library symbol to link against. arg-types is a vector of qualified keywords representing the argument types. ret-type is a single qualified keyword representing the return type. fn-tail is the body of the function (potentially with multiple arities) which wraps the native one. Inside the function, native-fn 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.

If no fn-tail is provided, then the resulting function will simply serialize the arguments according to arg-types, call the native function, and deserialize the return value.

The number of args in the fn-tail need not match the number of arg-types for the native function. It need only call the native wrapper function with the correct arguments.

-

See serialize, deserialize, make-downcall.

view source

defconst

macro

(defconst symbol docstring? symbol-or-addr type)

Defines a var named by symbol to be the value of the given type from symbol-or-addr.

view source

defvar

macro

(defvar symbol docstring? symbol-or-addr type)

Defines a var named by symbol to be a reference to the native memory from symbol-or-addr.

view source

ensure-symbol

(ensure-symbol symbol-or-addr)

Returns the argument if it is a MemorySegment, otherwise calls find-symbol on it.

view source

find-symbol

(find-symbol sym)

Gets the MemorySegment of a symbol from the loaded libraries.

view source

freset!

(freset! static-var newval)

Sets the value of static-var to newval, running it through serialize.

view source

fswap!

(fswap! static-var f & args)

Non-atomically runs the function f over the value stored in static-var.

-

The value is deserialized before passing it to f, and serialized before putting the value into static-var.

view source

load-library

(load-library path)

Loads the library at path.

view source

load-system-library

(load-system-library libname)

Loads the library named libname from the system’s load path.

view source

make-downcall

(make-downcall symbol-or-addr args ret)

Constructs a downcall function reference to symbol-or-addr with the given args and ret types.

+

See serialize, deserialize, make-downcall.

+
view source

defconst

macro

(defconst symbol docstring? symbol-or-addr type)

Defines a var named by symbol to be the value of the given type from symbol-or-addr.

+
view source

defvar

macro

(defvar symbol docstring? symbol-or-addr type)

Defines a var named by symbol to be a reference to the native memory from symbol-or-addr.

+
view source

ensure-symbol

(ensure-symbol symbol-or-addr)

Returns the argument if it is a MemorySegment, otherwise calls find-symbol on it.

+
view source

find-symbol

(find-symbol sym)

Gets the MemorySegment of a symbol from the loaded libraries.

+
view source

freset!

(freset! static-var newval)

Sets the value of static-var to newval, running it through serialize.

+
view source

fswap!

(fswap! static-var f & args)

Non-atomically runs the function f over the value stored in static-var.

+

The value is deserialized before passing it to f, and serialized before putting the value into static-var.

+
view source

load-library

(load-library path)

Loads the library at path.

+
view source

load-system-library

(load-system-library libname)

Loads the library named libname from the system’s load path.

+
view source

make-downcall

(make-downcall symbol-or-addr args ret)

Constructs a downcall function reference to symbol-or-addr with the given args and ret types.

The function returned takes only arguments whose types match exactly the java-layout for that type, and returns an argument with exactly the java-layout of the ret type. This function will perform no serialization or deserialization of arguments or the return type.

-

If the ret type is non-primitive, then the returned function will take a first argument of a SegmentAllocator.

view source

make-serde-varargs-wrapper

(make-serde-varargs-wrapper varargs-factory required-args ret-type)

Constructs a wrapper function for the varargs-factory which produces functions that serialize the arguments and deserialize the return value.

view source

make-serde-wrapper

(make-serde-wrapper downcall arg-types ret-type)

Constructs a wrapper function for the downcall which serializes the arguments and deserializes the return value.

view source

make-varargs-factory

(make-varargs-factory symbol required-args ret)

Returns a function for constructing downcalls with additional types for arguments.

+

If the ret type is non-primitive, then the returned function will take a first argument of a SegmentAllocator.

+
view source

make-serde-varargs-wrapper

(make-serde-varargs-wrapper varargs-factory required-args ret-type)

Constructs a wrapper function for the varargs-factory which produces functions that serialize the arguments and deserialize the return value.

+
view source

make-serde-wrapper

(make-serde-wrapper downcall arg-types ret-type)

Constructs a wrapper function for the downcall which serializes the arguments and deserializes the return value.

+
view source

make-varargs-factory

(make-varargs-factory symbol required-args ret)

Returns a function for constructing downcalls with additional types for arguments.

The required-args 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.

The returned function is memoized, so that only one downcall function will be generated per combination of argument types.

-

See make-downcall.

view source

reify-libspec

(reify-libspec libspec)

Loads all the symbols specified in the libspec.

-

The value of each key of the passed map is transformed as by reify-symbolspec.

view source

reify-symbolspec

multimethod

Takes a spec for a symbol reference and returns a live value for that type.

view source

static-variable

(static-variable symbol-or-addr type)

Constructs a reference to a mutable value stored in symbol-or-addr.

+

See make-downcall.

+
view source

reify-libspec

(reify-libspec libspec)

Loads all the symbols specified in the libspec.

+

The value of each key of the passed map is transformed as by reify-symbolspec.

+
view source

reify-symbolspec

multimethod

Takes a spec for a symbol reference and returns a live value for that type.

+
view source

static-variable

(static-variable symbol-or-addr type)

Constructs a reference to a mutable value stored in symbol-or-addr.

The returned value can be dereferenced, and has metadata.

-

See freset!, fswap!.

view source

static-variable-segment

(static-variable-segment static-var)

Gets the backing MemorySegment from static-var.

-

This is primarily useful when you need to pass the static variable’s address to a native function which takes an Addressable.

view source

vacfn-factory

(vacfn-factory symbol required-args ret)

Constructs a varargs factory to call the native function referenced by symbol.

-

The function returned takes any number of type arguments and returns a specialized Clojure function for calling the native function with those arguments.

view source
+

See freset!, fswap!.

+
view source

static-variable-segment

(static-variable-segment static-var)

Gets the backing MemorySegment from static-var.

+

This is primarily useful when you need to pass the static variable’s address to a native function which takes an Addressable.

+
view source

vacfn-factory

(vacfn-factory symbol required-args ret)

Constructs a varargs factory to call the native function referenced by symbol.

+

The function returned takes any number of type arguments and returns a specialized Clojure function for calling the native function with those arguments.

+
view source
\ No newline at end of file diff --git a/docs/coffi.layout.html b/docs/coffi.layout.html index 9ef58c1..f76061e 100644 --- a/docs/coffi.layout.html +++ b/docs/coffi.layout.html @@ -1,4 +1,6 @@ -coffi.layout documentation

Project

Namespaces

Public Vars

coffi.layout

Functions for adjusting the layout of structs.

with-c-layout

(with-c-layout struct-spec)

Forces a struct specification to C layout rules.

-

This will add padding fields between fields to match C alignment requirements.

view source
+coffi.layout documentation

Project

Namespaces

Public Vars

coffi.layout

Functions for adjusting the layout of structs.

+

with-c-layout

(with-c-layout struct-spec)

Forces a struct specification to C layout rules.

+

This will add padding fields between fields to match C alignment requirements.

+
view source
\ No newline at end of file diff --git a/docs/coffi.mem.html b/docs/coffi.mem.html index 5296955..a2f55d9 100644 --- a/docs/coffi.mem.html +++ b/docs/coffi.mem.html @@ -1,55 +1,120 @@ -coffi.mem documentation

Project

Namespaces

Public Vars

coffi.mem

Functions for managing native allocations, memory sessions, and (de)serialization.

+coffi.mem documentation

Project

Namespaces

Public Vars

coffi.mem

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.

If the native representation of the type is a primitive (whether or not other data beyond the primitive is associated with it, as e.g. a pointer), then primitive-type must be overriden to return which primitive type it is serialized as, then serialize* and deserialize* should be overriden.

If the native representation of the type is a composite type, like a union, 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.

add-close-action!

(add-close-action! session action)

Adds a 0-arity function to be run when the session closes.

view source

address-of

(address-of addressable)

Gets the address of a given segment.

-

This value can be used as an argument to functions which take a pointer.

view source

address?

(address? addr)

Checks if an object is a memory address.

-

nil is considered an address.

view source

align-of

(align-of type)

The alignment in bytes of the given type.

view source

alloc

(alloc size)(alloc size session)(alloc size alignment session)

Allocates size bytes.

-

If a session is provided, the allocation will be reclaimed when it is closed.

view source

alloc-instance

(alloc-instance type)(alloc-instance type session)

Allocates a memory segment for the given type.

view source

alloc-with

(alloc-with allocator size)(alloc-with allocator size alignment)

Allocates size bytes using the allocator.

view source

as-segment

(as-segment address size)(as-segment address size session)

Dereferences an address into a memory segment associated with the session.

view source

big-endian

The big-endian ByteOrder.

-

See little-endian, native-endian.

view source

byte-layout

The MemoryLayout for a byte in native-endian ByteOrder.

view source

c-layout

multimethod

Gets the layout object for a given type.

+

address-of

(address-of addressable)

Gets the address of a given segment.

+

This value can be used as an argument to functions which take a pointer.

+
view source

address?

(address? addr)

Checks if an object is a memory address.

+

nil is considered an address.

+
view source

align-of

(align-of type)

The alignment in bytes of the given type.

+
view source

alloc

(alloc size)(alloc size arena)(alloc size alignment arena)

Allocates size bytes.

+

If an arena is provided, the allocation will be reclaimed when it is closed.

+
view source

alloc-instance

(alloc-instance type)(alloc-instance type arena)

Allocates a memory segment for the given type.

+
view source

alloc-with

(alloc-with allocator size)(alloc-with allocator size alignment)

Allocates size bytes using the allocator.

+
view source

arena-allocator

(arena-allocator arena)

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.

+
view source

as-segment

(as-segment address)(as-segment address size)(as-segment address size arena)(as-segment address size arena cleanup)

Dereferences an address into a memory segment associated with the arena (default global).

+
view source

auto-arena

(auto-arena)

Constructs a new memory arena that is managed by the garbage collector.

+

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 arena cannot be closed, and therefore should not be created in a with-open clause.

+
view source

big-endian

The big-endian ByteOrder.

+

See little-endian, native-endian.

+
view source

byte-layout

The MemoryLayout for a byte in native-endian ByteOrder.

+
view source

c-layout

multimethod

Gets the layout object for a given type.

If a type is primitive it will return the appropriate primitive layout (see c-prim-layout).

-

Otherwise, it should return a GroupLayout for the given type.

view source

char-layout

The MemoryLayout for a c-sized char in native-endian ByteOrder.

view source

clone-segment

(clone-segment segment)(clone-segment segment session)

Clones the content of segment into a new segment of the same size.

view source

connected-scope

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 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 a with-open clause.

view source

connected-session

(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.

view source

copy-segment

(copy-segment dest src)

Copies the content to dest from src.

-

Returns dest.

view source

defalias

macro

(defalias new-type aliased-type)

Defines a type alias from new-type to aliased-type.

-

This creates needed serialization and deserialization implementations for the aliased type.

view source

deserialize

(deserialize obj type)

Deserializes an arbitrary type.

-

For types which have a primitive representation, this deserializes the primitive representation. For types which do not, this deserializes out of a segment.

view source

deserialize*

multimethod

Deserializes a primitive object into a Clojure data structure.

-

This is intended for use with types that are returned as a primitive but which need additional processing before they can be returned.

view source

deserialize-from

multimethod

Deserializes the given segment into a Clojure data structure.

+

Otherwise, it should return a GroupLayout for the given type.

+
view source

char-layout

The MemoryLayout for a c-sized char in native-endian ByteOrder.

+
view source

clone-segment

(clone-segment segment)(clone-segment segment arena)

Clones the content of segment into a new segment of the same size.

+
view source

confined-arena

(confined-arena)

Constructs a new arena for use only in this thread.

+

The memory allocated within this arena is cheap to allocate, like a native stack.

+

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.

+
view source

copy-segment

(copy-segment dest src)

Copies the content to dest from src.

+

Returns dest.

+
view source

defalias

macro

(defalias new-type aliased-type)

Defines a type alias from new-type to aliased-type.

+

This creates needed serialization and deserialization implementations for the aliased type.

+
view source

deserialize

(deserialize obj type)

Deserializes an arbitrary type.

+

For types which have a primitive representation, this deserializes the primitive representation. For types which do not, this deserializes out of a segment.

+
view source

deserialize*

multimethod

Deserializes a primitive object into a Clojure data structure.

+

This is intended for use with types that are returned as a primitive but which need additional processing before they can be returned.

+
view source

deserialize-from

multimethod

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.

view source

double-alignment

The alignment in bytes of a c-sized double.

view source

double-layout

The MemoryLayout for a c-sized double in native-endian ByteOrder.

view source

double-size

The size in bytes of a c-sized double.

view source

float-alignment

The alignment in bytes of a c-sized float.

view source

float-layout

The MemoryLayout for a c-sized float in native-endian ByteOrder.

view source

float-size

The size in bytes of a c-sized float.

view source

global-scope

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 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.

view source

global-session

(global-session)

Constructs the global session, 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.

view source

int-alignment

The alignment in bytes of a c-sized int.

view source

int-layout

The MemoryLayout for a c-sized int in native-endian ByteOrder.

view source

int-size

The size in bytes of a c-sized int.

view source

java-layout

(java-layout type)

Gets the Java class to an argument of this type for a method handle.

-

If a type serializes to a primitive it returns return a Java primitive type. Otherwise, it returns MemorySegment.

view source

java-prim-layout

Map of primitive type names to the Java types for a method handle.

view source

little-endian

The little-endian ByteOrder.

-

See big-endian, native-endian

view source

long-alignment

The alignment in bytes of a c-sized long.

view source

long-layout

The MemoryLayout for a c-sized long in native-endian ByteOrder.

view source

long-size

The size in bytes of a c-sized long.

view source

native-endian

The ByteOrder for the native endianness of the current hardware.

-

See big-endian, little-endian.

view source

null?

(null? addr)

Checks if a memory address is null.

view source

pointer-alignment

The alignment in bytes of a c-sized pointer.

view source

pointer-layout

The MemoryLayout for a native pointer in native-endian ByteOrder.

view source

pointer-size

The size in bytes of a c-sized pointer.

view source

primitive-type

multimethod

Gets the primitive type that is used to pass as an argument for the type.

+
view source

double-alignment

The alignment in bytes of a c-sized double.

+
view source

double-layout

The MemoryLayout for a c-sized double in native-endian ByteOrder.

+
view source

double-size

The size in bytes of a c-sized double.

+
view source

float-alignment

The alignment in bytes of a c-sized float.

+
view source

float-layout

The MemoryLayout for a c-sized float in native-endian ByteOrder.

+
view source

float-size

The size in bytes of a c-sized float.

+
view source

global-arena

(global-arena)

Constructs the global arena, which will never reclaim its resources.

+

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.

+
view source

int-alignment

The alignment in bytes of a c-sized int.

+
view source

int-layout

The MemoryLayout for a c-sized int in native-endian ByteOrder.

+
view source

int-size

The size in bytes of a c-sized int.

+
view source

java-layout

(java-layout type)

Gets the Java class to an argument of this type for a method handle.

+

If a type serializes to a primitive it returns return a Java primitive type. Otherwise, it returns MemorySegment.

+
view source

java-prim-layout

Map of primitive type names to the Java types for a method handle.

+
view source

little-endian

The little-endian ByteOrder.

+

See big-endian, native-endian

+
view source

long-alignment

The alignment in bytes of a c-sized long.

+
view source

long-layout

The MemoryLayout for a c-sized long in native-endian ByteOrder.

+
view source

long-size

The size in bytes of a c-sized long.

+
view source

native-endian

The ByteOrder for the native endianness of the current hardware.

+

See big-endian, little-endian.

+
view source

null?

(null? addr)

Checks if a memory address is null.

+
view source

pointer-alignment

The alignment in bytes of a c-sized pointer.

+
view source

pointer-layout

The MemoryLayout for a native pointer in native-endian ByteOrder.

+
view source

pointer-size

The size in bytes of a c-sized pointer.

+
view source

primitive-type

multimethod

Gets the primitive type that is used to pass as an argument for the type.

This is for objects which are passed to native functions as primitive types, but which need additional logic to be performed during serialization and deserialization.

Implementations of this method should take into account that type arguments may not always be evaluated before passing to this function.

-

Returns nil for any type which does not have a primitive representation.

view source

primitive-types

A set of all primitive types.

view source

primitive?

(primitive? type)

A predicate to determine if a given type is primitive.

view source

read-address

(read-address segment)(read-address segment offset)

Reads a MemoryAddress from the segment, at an optional offset.

view source

read-byte

(read-byte segment)(read-byte segment offset)

Reads a byte from the segment, at an optional offset.

view source

read-char

(read-char segment)(read-char segment offset)

Reads a char from the segment, at an optional offset.

view source

read-double

(read-double segment)(read-double segment offset)(read-double segment offset byte-order)

Reads a double from the segment, at an optional offset.

-

If byte-order is not provided, it defaults to native-endian.

view source

read-float

(read-float segment)(read-float segment offset)(read-float segment offset byte-order)

Reads a float from the segment, at an optional offset.

-

If byte-order is not provided, it defaults to native-endian.

view source

read-int

(read-int segment)(read-int segment offset)(read-int segment offset byte-order)

Reads a int from the segment, at an optional offset.

-

If byte-order is not provided, it defaults to native-endian.

view source

read-long

(read-long segment)(read-long segment offset)(read-long segment offset byte-order)

Reads a long from the segment, at an optional offset.

-

If byte-order is not provided, it defaults to native-endian.

view source

read-short

(read-short segment)(read-short segment offset)(read-short segment offset byte-order)

Reads a short from the segment, at an optional offset.

-

If byte-order is not provided, it defaults to native-endian.

view source

scope-allocator

deprecated

(scope-allocator scope)

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.

view source

segment-scope

deprecated

(segment-scope segment)

Gets the scope used to construct the segment.

view source

segment-session

(segment-session segment)

Gets the memory session used to construct the segment.

view source

seq-of

(seq-of type segment)

Constructs a lazy sequence of type elements deserialized from segment.

view source

serialize

(serialize obj type)(serialize obj type session)

Serializes an arbitrary type.

-

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.

view source

serialize*

multimethod

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.

-

This method should only be implemented for types that serialize to primitives.

view source

serialize-into

multimethod

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.

+

Returns nil for any type which does not have a primitive representation.

+
view source

primitive-types

A set of all primitive types.

+
view source

primitive?

(primitive? type)

A predicate to determine if a given type is primitive.

+
view source

read-address

(read-address segment)(read-address segment offset)

Reads an address from the segment, at an optional offset, wrapped in a MemorySegment.

+
view source

read-byte

(read-byte segment)(read-byte segment offset)

Reads a byte from the segment, at an optional offset.

+
view source

read-char

(read-char segment)(read-char segment offset)

Reads a char from the segment, at an optional offset.

+
view source

read-double

(read-double segment)(read-double segment offset)(read-double segment offset byte-order)

Reads a double from the segment, at an optional offset.

+

If byte-order is not provided, it defaults to native-endian.

+
view source

read-float

(read-float segment)(read-float segment offset)(read-float segment offset byte-order)

Reads a float from the segment, at an optional offset.

+

If byte-order is not provided, it defaults to native-endian.

+
view source

read-int

(read-int segment)(read-int segment offset)(read-int segment offset byte-order)

Reads a int from the segment, at an optional offset.

+

If byte-order is not provided, it defaults to native-endian.

+
view source

read-long

(read-long segment)(read-long segment offset)(read-long segment offset byte-order)

Reads a long from the segment, at an optional offset.

+

If byte-order is not provided, it defaults to native-endian.

+
view source

read-short

(read-short segment)(read-short segment offset)(read-short segment offset byte-order)

Reads a short from the segment, at an optional offset.

+

If byte-order is not provided, it defaults to native-endian.

+
view source

reinterpret

(reinterpret segment size)(reinterpret segment size arena)(reinterpret segment size arena cleanup)

Reinterprets the segment as having the passed size.

+

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.

+
view source

seq-of

(seq-of type segment)

Constructs a lazy sequence of type elements deserialized from segment.

+
view source

serialize

(serialize obj type)(serialize obj type arena)

Serializes an arbitrary type.

+

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.

+
view source

serialize*

multimethod

Constructs a serialized version of the obj and returns it.

+

Any new allocations made during the serialization should be tied to the given arena, except in extenuating circumstances.

+

This method should only be implemented for types that serialize to primitives.

+
view source

serialize-into

multimethod

Writes a serialized version of the obj to the given segment.

+

Any new allocations made during the serialization should be tied to the given 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.

view source

session-allocator

(session-allocator session)

Constructs a segment allocator from the given session.

-

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.

view source

shared-scope

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.

view source

shared-session

(shared-session)(shared-session cleaner)

Constructs a new shared memory session.

-

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.

view source

short-alignment

The alignment in bytes of a c-sized short.

view source

short-layout

The MemoryLayout for a c-sized short in native-endian ByteOrder.

view source

short-size

The size in bytes of a c-sized short.

view source

size-of

(size-of type)

The size in bytes of the given type.

view source

slice

(slice segment offset)(slice segment offset size)

Get a slice over the segment with the given offset.

view source

slice-into

(slice-into address segment)(slice-into address segment size)

Get a slice into the segment starting at the address.

view source

slice-segments

(slice-segments segment size)

Constructs a lazy seq of size-length memory segments, sliced from segment.

view source

stack-scope

deprecated

(stack-scope)

Constructs a new scope for use only in this thread.

-

The memory allocated within this scope is cheap to allocate, like a native stack.

view source

stack-session

(stack-session)(stack-session cleaner)

Constructs a new session for use only in this thread.

-

The memory allocated within this session is cheap to allocate, like a native stack.

view source

with-acquired

macro

(with-acquired sessions & body)

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.

view source

with-offset

(with-offset address offset)

Get a new address offset from the old address.

view source

write-address

(write-address segment value)(write-address segment offset value)

Writes a MemoryAddress to the segment, at an optional offset.

view source

write-byte

(write-byte segment value)(write-byte segment offset value)

Writes a byte to the segment, at an optional offset.

view source

write-char

(write-char segment value)(write-char segment offset value)

Writes a char to the segment, at an optional offset.

view source

write-double

(write-double segment value)(write-double segment offset value)(write-double segment offset byte-order value)

Writes a double to the segment, at an optional offset.

-

If byte-order is not provided, it defaults to native-endian.

view source

write-float

(write-float segment value)(write-float segment offset value)(write-float segment offset byte-order value)

Writes a float to the segment, at an optional offset.

-

If byte-order is not provided, it defaults to native-endian.

view source

write-int

(write-int segment value)(write-int segment offset value)(write-int segment offset byte-order value)

Writes a int to the segment, at an optional offset.

-

If byte-order is not provided, it defaults to native-endian.

view source

write-long

(write-long segment value)(write-long segment offset value)(write-long segment offset byte-order value)

Writes a long to the segment, at an optional offset.

-

If byte-order is not provided, it defaults to native-endian.

view source

write-short

(write-short segment value)(write-short segment offset value)(write-short segment offset byte-order value)

Writes a short to the segment, at an optional offset.

-

If byte-order is not provided, it defaults to native-endian.

view source
+
view source

shared-arena

(shared-arena)

Constructs a new shared memory arena.

+

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.

+
view source

short-alignment

The alignment in bytes of a c-sized short.

+
view source

short-layout

The MemoryLayout for a c-sized short in native-endian ByteOrder.

+
view source

short-size

The size in bytes of a c-sized short.

+
view source

size-of

(size-of type)

The size in bytes of the given type.

+
view source

slice

(slice segment offset)(slice segment offset size)

Get a slice over the segment with the given offset.

+
view source

slice-segments

(slice-segments segment size)

Constructs a lazy seq of size-length memory segments, sliced from segment.

+
view source

write-address

(write-address segment value)(write-address segment offset value)

Writes the address of the MemorySegment value to the segment, at an optional offset.

+
view source

write-byte

(write-byte segment value)(write-byte segment offset value)

Writes a byte to the segment, at an optional offset.

+
view source

write-char

(write-char segment value)(write-char segment offset value)

Writes a char to the segment, at an optional offset.

+
view source

write-double

(write-double segment value)(write-double segment offset value)(write-double segment offset byte-order value)

Writes a double to the segment, at an optional offset.

+

If byte-order is not provided, it defaults to native-endian.

+
view source

write-float

(write-float segment value)(write-float segment offset value)(write-float segment offset byte-order value)

Writes a float to the segment, at an optional offset.

+

If byte-order is not provided, it defaults to native-endian.

+
view source

write-int

(write-int segment value)(write-int segment offset value)(write-int segment offset byte-order value)

Writes a int to the segment, at an optional offset.

+

If byte-order is not provided, it defaults to native-endian.

+
view source

write-long

(write-long segment value)(write-long segment offset value)(write-long segment offset byte-order value)

Writes a long to the segment, at an optional offset.

+

If byte-order is not provided, it defaults to native-endian.

+
view source

write-short

(write-short segment value)(write-short segment offset value)(write-short segment offset byte-order value)

Writes a short to the segment, at an optional offset.

+

If byte-order is not provided, it defaults to native-endian.

+
view source
\ No newline at end of file diff --git a/docs/index.html b/docs/index.html index 5193885..5a5c360 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1,3 +1,6 @@ -coffi v0.6.409

Project

Namespaces

coffi v0.6.409

A Foreign Function Interface in Clojure for JDK 19.

Namespaces

coffi.ffi

Functions for creating handles to native functions and loading native libraries.

Public variables and functions:

coffi.layout

Functions for adjusting the layout of structs.

Public variables and functions:

coffi.mem

Functions for managing native allocations, memory sessions, and (de)serialization.

Public variables and functions:

+coffi v1.0.450

Project

Namespaces

coffi v1.0.450

A Foreign Function Interface in Clojure for JDK 22+.

Namespaces

coffi.ffi

Functions for creating handles to native functions and loading native libraries.

+

Public variables and functions:

coffi.layout

Functions for adjusting the layout of structs.

+

Public variables and functions:

coffi.mem

Functions for managing native allocations, memory arenas, and (de)serialization.

+

Public variables and functions:

\ No newline at end of file diff --git a/flake.lock b/flake.lock new file mode 100644 index 0000000..7729448 --- /dev/null +++ b/flake.lock @@ -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 +} diff --git a/flake.nix b/flake.nix new file mode 100644 index 0000000..4c97e2f --- /dev/null +++ b/flake.nix @@ -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; [ + ]; + }; + }; +} diff --git a/pom.xml b/pom.xml index d2a6a67..6021c3d 100644 --- a/pom.xml +++ b/pom.xml @@ -2,7 +2,7 @@ 4.0.0 org.suskalo/coffi - A Foreign Function Interface in Clojure for JDK 18. + A Foreign Function Interface in Clojure for JDK 22+. https://github.com/IGJoshua/coffi diff --git a/src/clj/coffi/ffi.clj b/src/clj/coffi/ffi.clj index 371aeef..d3d770b 100644 --- a/src/clj/coffi/ffi.clj +++ b/src/clj/coffi/ffi.clj @@ -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 - (not raw-fn?) (upcall-serde-wrapper arg-types ret-type) - :always (upcall-handle arg-types ret-type)) - (function-descriptor arg-types ret-type) - session)) + ^MethodHandle (cond-> f + (not raw-fn?) (upcall-serde-wrapper arg-types ret-type) + :always (upcall-handle arg-types ret-type)) + ^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 diff --git a/src/clj/coffi/layout.clj b/src/clj/coffi/layout.clj index 15a2db6..810a41f 100644 --- a/src/clj/coffi/layout.clj +++ b/src/clj/coffi/layout.clj @@ -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)]])))))] diff --git a/src/clj/coffi/mem.clj b/src/clj/coffi/mem.clj index abafd54..ec5e665 100644 --- a/src/clj/coffi/mem.clj +++ b/src/clj/coffi/mem.clj @@ -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] - (write-address - segment - (cond-> obj - (sequential? type) (serialize* type session))))) + [obj type segment arena] + (write-address + segment + (cond-> obj + (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)))) + (cond-> (read-address segment) + (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#))))) diff --git a/src/java/coffi/ffi/Loader.java b/src/java/coffi/ffi/Loader.java index 8830118..ef458fc 100644 --- a/src/java/coffi/ffi/Loader.java +++ b/src/java/coffi/ffi/Loader.java @@ -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); } } diff --git a/test/c/ffi_test.c b/test/c/ffi_test.c index c689e87..24e6959 100644 --- a/test/c/ffi_test.c +++ b/test/c/ffi_test.c @@ -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; +} + diff --git a/test/clj/coffi/ffi_test.clj b/test/clj/coffi/ffi_test.clj index 15cc4b6..d45e3ae 100644 --- a/test/clj/coffi/ffi_test.clj +++ b/test/clj/coffi/ffi_test.clj @@ -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")))) + diff --git a/test/clj/coffi/mem_test.clj b/test/clj/coffi/mem_test.clj new file mode 100644 index 0000000..b52c1eb --- /dev/null +++ b/test/clj/coffi/mem_test.clj @@ -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)))) + +