Getting Started
+Generated by Codox
coffi v1.0.486
Getting Started
Installation
This library is available on Clojars. Add one of the following entries to the :deps key of your deps.edn:
org.suskalo/coffi {:mvn/version "x.y.z"}
@@ -144,4 +144,25 @@ Point zero(void) {
Be aware however that there is no synchronization on these types. The value being read is not read atomically, so you may see an inconsistent state if the value is being mutated on another thread.
A parallel function fswap! is also provided, but it does not provide any atomic semantics either.
The memory that backs the static variable can be fetched with the function static-variable-segment, which can be used to pass a pointer to the static variable to native functions that require it.
+Complex Wrappers
+Some functions require more complex code to map nicely to a Clojure function. The defcfn macro provides facilities to wrap the native function with some Clojure code to make this easier.
+(defcfn takes-array
+ "takes_array_with_count" [::mem/pointer ::mem/long] ::mem/void
+ native-fn
+ [ints]
+ (let [arr-len (count ints)
+ int-array (mem/serialize ints [::mem/array ::mem/int arr-len])]
+ (native-fn int-array arr-len)))
+
+The symbol native-fn can be any unqualified symbol, and names the native function being wrapped. It must be called in the function body below if you want to call the native code.
+This serialize function has a paired deserialize, and allows marshaling Clojure data back and forth to native data structures.
+This can be used to implement out variables often seen in native code.
+(defcfn out-int
+ "out_int" [::mem/pointer] ::mem/void
+ native-fn
+ [i]
+ (let [int-ptr (mem/serialize i [::mem/pointer ::mem/int])]
+ (native-fn int-ptr)
+ (mem/deserialize int-ptr [::mem/pointer ::mem/int])))
+
Generated by Codox
coffi v1.0.486
Memory Management
+In order to serialize any non-primitive type, off-heap memory needs to be allocated. When memory is allocated inside the JVM, the memory is associated with an arena. If none is provided, 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 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.
(defcfn out-int
+ "out_int" [::mem/pointer] ::mem/void
+ native-fn
+ [i]
+ (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]))))
+This will free the pointer immediately upon leaving the function.
+When memory needs to be accessible from multiple threads, there’s shared-arena. When a shared-arena is .closed, 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 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.
Generated by Codox
coffi v1.0.486
Built-in Types
+Primitives
+Arrays
+Pointers
+Structs
+Enums
+Flagsets
+Unions
+Unions in coffi are rather limited. They can be serialized, but not deserialized without external information.
+[::mem/union
+ #{::mem/float ::mem/double}
+ :dispatch #(cond
+ (float? %) ::mem/float
+ (double? %) ::mem/double)]
+This is a minimal union in coffi. If the :dispatch keyword argument is not passed, then the union cannot be serialized, as coffi would not know which type to serialize the values as. In the example with a tagged union, a dispatch function was not provided because the type was only used for the native layout.
In addition to a dispatch function, when serializing a union an extract function may also be provided. In the case of the value in the tagged union from before, it could be represented for serialization purposes like so:
+[::mem/union
+ #{::mem/int ::mem/c-string}
+ :dispatch #(case (first %)
+ :ok ::mem/int
+ :err ::mem/c-string)
+ :extract second]
+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 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.
Raw Types
+Generated by Codox
coffi v1.0.486
Custom Types
+Custom types with serializers and deserializers may be created. This is done using two sets of three multimethods which can be extended by the user. For any given type, only one set need be implemented.
+Two examples of custom types are given here, one is a 3d vector, and the other an example of a tagged union.
+Vector3
+For the vector type, it will serialize to a pointer to an array of three floats.
+The multimethod primitive-type returns the primitive type that a given type serializes to. For this example, it should be a pointer.
(defmethod mem/primitive-type ::vector
+ [_type]
+ ::mem/pointer)
+For any type which doesn’t serialize to a primitive, it returns nil, and therefore need not be overriden.
+Next is serialize* and deserialize*, multimethods that work with types that serialize to primitives.
(defmethod mem/serialize* ::vector
+ [obj _type arena]
+ (mem/serialize obj [::mem/array ::mem/float 3] arena))
+
+(defmethod mem/deserialize* ::vector
+ [segment _type]
+ (mem/deserialize (mem/reinterpret segment (mem/size-of [::mem/array ::mem/float 3]))
+ [::mem/array ::mem/float 3]))
+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 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:
(defcfn returns-vector
+ "returns_vector" [] ::mem/pointer
+ native-fn
+ [arena]
+ (let [ret-ptr (native-fn)]
+ (-> (reinterpret ret-ptr (mem/size-of ::vector) arena free-vector!)
+ (deserialize ::vector))))
+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 naming the tag and the value. The type itself will need to take arguments, similar to struct. For example, if we were to represent a result type like in Rust, we might have the following values:
[:ok 5]
+[:err "Invalid number format"]
+To represent this, we can have a tagged-union type. For this instance of the result type, it may look like this:
[::tagged-union [:ok :err] {:ok ::mem/int :err ::mem/c-string}]
+The native representation of these objects is a struct of the tag and a union of the value. In order to correctly serialize the data and pass it to native code, we need a representation of the native layout of the data. The c-layout multimethod provides that.
(defmethod mem/c-layout ::tagged-union
+ [[_tagged-union tags type-map]]
+ (mem/c-layout [::mem/struct
+ [[:tag ::mem/long]
+ [:value [::mem/union (vals type-map)]]]]))
+Types with type arguments are represented as vectors of the type name and any additional arguments. The type name is what is dispatched on for the multimethods.
+Now that we have a native layout, we need to be able to serialize and deserialize the value into and out of memory segments. This is accomplished with serialize-into and deserialize-from.
(defn item-index
+ "Gets the index of the first occurance of `item` in `coll`."
+ [coll item]
+ (first
+ (->> coll
+ (map-indexed vector)
+ (filter (comp #{item} second))
+ (map first))))
+
+(defmethod mem/serialize-into ::tagged-union
+ [obj [_tagged-union tags type-map] segment arena]
+ (mem/serialize-into
+ {:tag (item-index tags (first obj))
+ :value (second obj)}
+ [::mem/struct
+ [[:tag ::mem/long]
+ [:value (get type-map (first obj))]]]
+ segment
+ arena))
+This serialization method is rather simple, it just turns the vector value into a map, and serializes it as a struct, choosing the type of the value based on the tag.
+(defmethod mem/deserialize-from ::tagged-union
+ [segment [_tagged-union tags type-map]]
+ (let [tag (mem/deserialize-from segment ::mem/long)]
+ [(nth tags tag)
+ (mem/deserialize-from
+ (mem/slice segment (mem/size-of ::mem/long))
+ (get type-map tag))]))
+Deserialization is a little more complex. First the tag is retrieved from the beginning of the segment, and then the type of the value is decided based on that before it is deserialized.
+Generated by Codox
coffi v1.0.486
Low-Level Wrappers
+Unwrapped Native Handles
+Some native libraries work with handles to large amounts of data at once, making it undesirable to marshal data back and forth from Clojure, both because it’s not necessary to work with the data in Clojure directly, or also because of the high (de)serialization costs associated with marshaling. In cases like these, unwrapped native handles are desirable.
+The functions make-downcall and make-varargs-factory are also provided to create raw function handles.
(def raw-strlen (ffi/make-downcall "strlen" [::mem/c-string] ::mem/long))
+(raw-strlen (mem/serialize "hello" ::mem/c-string))
+;; => 5
+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 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 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:
+[::ffi/fn [::mem/int] ::mem/int :raw-fn? true]
+Clojure functions serialized to this type will have their arguments and return value exactly match the types specified and will not perform any serialization or deserialization at their boundaries.
+One important caveat to consider when writing wrappers for performance-sensitive functions is that the convenience macro defcfn that coffi provides will already perform no serialization or deserialization on primitive arguments and return types, so for functions with only primitive argument and return types there is no performance reason to choose unwrapped native handles over the convenience macro.
Manual (De)Serialization
+Coffi uses multimethods to dispatch to (de)serialization functions to enable code that’s generic over the types it operates on. However, in cases where you know the exact types that you will be (de)serializing and the multimethod dispatch overhead is too high a cost, it may be appropriate to manually handle (de)serializing data. This will often be done paired with Unwrapped Native Handles.
+Convenience functions are provided to both read and write all primitive types and addresses, including byte order.
+As an example, when wrapping a function that returns an array of big-endian floats, the following code might be used.
+;; 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 [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* out-floats)
+ floats-addr (mem/read-address out-floats)
+ floats-slice (mem/reinterpret floats-addr (unchecked-multiply-int mem/float-size num-floats))]
+ ;; Using a try/finally to perform an operation when the stack frame exits,
+ ;; but not to try to catch anything.
+ (try
+ (loop [floats (transient [])
+ index 0]
+ (if (>= index num-floats)
+ (persistent! floats)
+ (recur (conj! floats (mem/read-float floats-slice
+ (unchecked-multiply-int index mem/float-size)
+ mem/big-endian))
+ (unchecked-inc-int index))))
+ (finally
+ (release-floats* floats-addr))))))
+The above code manually performs all memory operations rather than relying on coffi’s dispatch. This will be more performant, but because multimethod overhead is usually relatively low, it’s recommended to use the multimethod variants for convenience in colder functions.
+Generated by Codox
coffi v1.0.486
Data Model
+In addition to the macros and functions provided to build a Clojure API for native libraries, facilities are provided for taking data and loading all the symbols specified by it. This can be useful if a library provides (or an external provider maintains) a data representation of their API, as Clojure data to represent it may be programmatically generated from these sources.
+The data to represent an API is a map with the following form:
+(def strlen-libspec
+ {:strlen {:type :function
+ :symbol "strlen"
+ :function/args [::mem/c-string]
+ :function/ret ::mem/long}})
+Each key in this map represents a single symbol to be loaded. The value is a map with at least the keys :type and :symbol. These are the currently recognized types:
-
+
- function +
- varargs-factory +
- const +
- static-var +
Each one has its own set of additional keys which can be added to the map. Both function and varargs-factory have the three keys :function/args, :function/ret, and :function/raw-fn?. The const type has :const/type and static-var has :static-var/type.
This data can be passed to the function reify-libspec, which will take the data and return a map from the same keys as the input map to whatever value is appropriate for a given symbol type (e.g. a Clojure function for function, a value for const, etc.).
(ffi/reify-libspec strlen-libspec)
+;; => {:strlen #function[...]}
+This functionality can be extended by specifying new types as implementations of the multimethod reify-symbolspec, although it’s recommended that for any library authors who do so, namespaced keywords be used to name types.
Generated by Codox
coffi v1.0.486
Benchmarks
+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 alternative libraries on JDK <16) introduces more overhead when calling native code than JNI does.
+In order to provide a benchmark to see how much of a difference the different native interfaces make, we can use criterium to benchmark each. GLFW’s glfwGetTime function will be used for the test as it performs a simple operation, and is conveniently already wrapped in JNI by the excellent LWJGL library.
The following benchmarks were run on a Lenovo Thinkpad with an Intel i7-10610U running Manjaro Linux, using Clojure 1.10.3 on Java 17.
+JNI
+The baseline for performance is the JNI. Using LWJGL it’s relatively simple to benchmark. The following Clojure CLI command will start a repl with LWJGL and criterium loaded.
+$ clj -Sdeps '{:deps {org.lwjgl/lwjgl {:mvn/version "3.2.3"}
+ org.lwjgl/lwjgl-glfw {:mvn/version "3.2.3"}
+ org.lwjgl/lwjgl$natives-linux {:mvn/version "3.2.3"}
+ org.lwjgl/lwjgl-glfw$natives-linux {:mvn/version "3.2.3"}
+ criterium/criterium {:mvn/version "0.4.6"}}}'
+Then from the repl
+user=> (import 'org.lwjgl.glfw.GLFW)
+org.lwjgl.glfw.GLFW
+user=> (require '[criterium.core :as bench])
+nil
+user=> (GLFW/glfwInit)
+true
+user=> (bench/bench (GLFW/glfwGetTime) :verbose)
+amd64 Linux 5.10.68-1-MANJARO 8 cpu(s)
+OpenJDK 64-Bit Server VM 17+35-2724
+Runtime arguments: -Dclojure.basis=/home/jsusk/.clojure/.cpcache/2667074721.basis
+Evaluation count : 1613349900 in 60 samples of 26889165 calls.
+ Execution time sample mean : 32.698446 ns
+ Execution time mean : 32.697811 ns
+Execution time sample std-deviation : 1.274600 ns
+ Execution time std-deviation : 1.276437 ns
+ Execution time lower quantile : 30.750813 ns ( 2.5%)
+ Execution time upper quantile : 33.757662 ns (97.5%)
+ Overhead used : 6.400704 ns
+nil
+GLFW requires that we initialize it before calling the glfwGetTime function. Besides that this is a simple interop call which directly maps to the native function.
This gives us a basis of 32.7 ns +/-1.3 ns. All other libraries will be evaluated relative to this result.
+To ensure fairness, we’ll also get that overhead value to be used in further tests.
+user=> bench/estimated-overhead-cache
+6.400703613065185E-9
+Coffi
+The dependencies when using coffi are simpler, but it also requires some JVM options to support the foreign access api.
+$ clj -Sdeps '{:deps {org.suskalo/coffi {:mvn/version "0.1.205"}
+ criterium/criterium {:mvn/version "0.4.6"}}}' \
+ -J--add-modules=jdk.incubator.foreign \
+ -J--enable-native-access=ALL-UNNAMED
+In order to ensure fair comparisons, we’re going to use the same overhead value on each run, so before we do the benchmark we’ll set it to the observed value from last time.
+user=> (require '[criterium.core :as bench])
+nil
+user=> (alter-var-root #'bench/estimated-overhead-cache (constantly 6.400703613065185E-9))
+6.400703613065185E-9
+user=> (require '[coffi.ffi :as ffi])
+nil
+user=> (require '[coffi.mem :as mem])
+nil
+user=> (ffi/load-system-library "glfw")
+nil
+user=> ((ffi/cfn "glfwInit" [] ::mem/int))
+1
+user=> (let [f (ffi/cfn "glfwGetTime" [] ::mem/double)]
+ (bench/bench (f) :verbose))
+amd64 Linux 5.10.68-1-MANJARO 8 cpu(s)
+OpenJDK 64-Bit Server VM 17+35-2724
+Runtime arguments: --add-modules=jdk.incubator.foreign --enable-native-access=ALL-UNNAMED -Dclojure.basis=/home/jsusk/.clojure/.cpcache/72793624.basis
+Evaluation count : 1657995600 in 60 samples of 27633260 calls.
+ Execution time sample mean : 31.382665 ns
+ Execution time mean : 31.386493 ns
+Execution time sample std-deviation : 1.598571 ns
+ Execution time std-deviation : 1.608818 ns
+ Execution time lower quantile : 29.761194 ns ( 2.5%)
+ Execution time upper quantile : 33.228276 ns (97.5%)
+ Overhead used : 6.400704 ns
+nil
+This result is about 1.3 ns faster, and while that is less than the standard deviation of 1.6, it’s quite close to it.
+Clojure-JNA
+Clojure-JNA uses the JNA library, which was designed to provide Java with an easy way to access native libraries, but which is known for not having the greatest performance. Since this is an older project, I’m also including the clojure dependency to ensure the correct version is used.
+$ clj -Sdeps '{:deps {org.clojure/clojure {:mvn/version "1.10.3"}
+ net.n01se/clojure-jna {:mvn/version "1.0.0"}
+ criterium/criterium {:mvn/version "0.4.6"}}}'
+The naive way to call the function using Clojure-JNA is to use jna/invoke.
user=> (require '[criterium.core :as bench])
+nil
+user=> (alter-var-root #'bench/estimated-overhead-cache (constantly 6.400703613065185E-9))
+6.400703613065185E-9
+user=> (require '[net.n01se.clojure-jna :as jna])
+nil
+user=> (jna/invoke Integer glfw/glfwInit)
+1
+user=> (bench/bench (jna/invoke Double glfw/glfwGetTime) :verbose)
+amd64 Linux 5.10.68-1-MANJARO 8 cpu(s)
+OpenJDK 64-Bit Server VM 17+35-2724
+Runtime arguments: -Dclojure.basis=/home/jsusk/.clojure/.cpcache/3229486237.basis
+Evaluation count : 195948720 in 60 samples of 3265812 calls.
+ Execution time sample mean : 350.335614 ns
+ Execution time mean : 350.373520 ns
+Execution time sample std-deviation : 24.833070 ns
+ Execution time std-deviation : 24.755929 ns
+ Execution time lower quantile : 300.000019 ns ( 2.5%)
+ Execution time upper quantile : 365.759273 ns (97.5%)
+ Overhead used : 6.400704 ns
+
+Found 13 outliers in 60 samples (21.6667 %)
+ low-severe 12 (20.0000 %)
+ low-mild 1 (1.6667 %)
+ Variance from outliers : 53.4220 % Variance is severely inflated by outliers
+nil
+As you can see, this method of calling functions is very bad for performance, with call overhead dominating function runtime by an order of magnitude. That said, this isn’t a completely fair comparison, nor the most realistic, because this way of calling functions looks the function up on each invocation.
+To adjust for this, we’ll use the jna/to-fn function to give a persistent handle to the function that we can call.
user=> (let [f (jna/to-fn Double glfw/glfwGetTime)]
+ (bench/bench (f) :verbose))
+amd64 Linux 5.10.68-1-MANJARO 8 cpu(s)
+OpenJDK 64-Bit Server VM 17+35-2724
+Runtime arguments: -Dclojure.basis=/home/jsusk/.clojure/.cpcache/3229486237.basis
+Evaluation count : 611095020 in 60 samples of 10184917 calls.
+ Execution time sample mean : 104.623634 ns
+ Execution time mean : 104.638406 ns
+Execution time sample std-deviation : 7.649296 ns
+ Execution time std-deviation : 7.638963 ns
+ Execution time lower quantile : 92.446016 ns ( 2.5%)
+ Execution time upper quantile : 110.258832 ns (97.5%)
+ Overhead used : 6.400704 ns
+nil
+This is much better, but is still about 3x slower than JNI, meaning the overhead from using JNA is still bigger than the function runtime.
+This performance penalty is still small in the scope of longer-running functions, and so may not be a concern for your application, but it is something to be aware of.
+tech.jna
+The tech.jna library is similar in scope to Clojure-JNA, however was written to fit into an ecosystem of libraries meant for array-based programming for machine learning and data science.
+$ clj -Sdeps '{:deps {techascent/tech.jna {:mvn/version "4.05"}
+ criterium/criterium {:mvn/version "0.4.6"}}}'
+This library is also quite simple to use, the only slightly odd thing I’m doing here is to dereference the var outside the benchmark in order to ensure it’s an apples-to-apples comparison. We don’t want var dereference time mucking up our benchmark.
+user=> (require '[criterium.core :as bench])
+nil
+user=> (alter-var-root #'bench/estimated-overhead-cache (constantly 6.400703613065185E-9))
+6.400703613065185E-9
+user=> (require '[tech.v3.jna :as jna])
+nil
+user=> (jna/def-jna-fn "glfw" glfwInit "initialize glfw" Integer)
+#'user/glfwInit
+user=> (glfwInit)
+Oct 09, 2021 10:30:50 AM clojure.tools.logging$eval1122$fn__1125 invoke
+INFO: Library glfw found at [:system "glfw"]
+1
+user=> (jna/def-jna-fn "glfw" glfwGetTime "gets the time as a double since init" Double)
+#'user/glfwGetTime
+user=> (let [f @#'glfwGetTime]
+ (bench/bench (f) :verbose))
+amd64 Linux 5.10.68-1-MANJARO 8 cpu(s)
+OpenJDK 64-Bit Server VM 17+35-2724
+Runtime arguments: -Dclojure.basis=/home/jsusk/.clojure/.cpcache/2910209237.basis
+Evaluation count : 323281680 in 60 samples of 5388028 calls.
+ Execution time sample mean : 203.976803 ns
+ Execution time mean : 203.818712 ns
+Execution time sample std-deviation : 14.557312 ns
+ Execution time std-deviation : 14.614080 ns
+ Execution time lower quantile : 179.732593 ns ( 2.5%)
+ Execution time upper quantile : 213.929374 ns (97.5%)
+ Overhead used : 6.400704 ns
+nil
+This version is even slower than Clojure-JNA. I’m unsure where this overhead is coming from, but I’ll admit that I haven’t looked at their implementations very closely.
+dtype-next
+The library dtype-next replaced tech.jna in the toolkit of the group working on machine learning and array-based programming, and it includes support for composite data types including structs, as well as primitive functions and callbacks.
+In addition, dtype-next has two different ffi backends. First is JNA, which is usable on any JDK version, and is what we’ll use for the first benchmark. Second is the Java 16 version of Project Panama, which will be shown next.
+In order to use the dtype-next ffi with the JNA backend, the JNA library has to be included in the dependencies.
+$ clj -Sdeps '{:deps {cnuernber/dtype-next {:mvn/version "8.032"}
+ net.java.dev.jna/jna {:mvn/version "5.8.0"}
+ criterium/criterium {:mvn/version "0.4.6"}}}'
+The dtype-next library also requires some more ceremony around declaring native functions. One advantage this has is that multiple symbols with the same name can be loaded from different shared libraries, but it also does increase friction when defining native wrappers.
+Some easier ways to define native wrappers are provided than what is seen here, but they share some disadvantages in documentation over the core methods provided in coffi, although they are comparable to the data model provided in coffi.
+user=> (require '[criterium.core :as bench])
+nil
+user=> (alter-var-root #'bench/estimated-overhead-cache (constantly 6.400703613065185E-9))
+6.400703613065185E-9
+user=> (require '[tech.v3.datatype.ffi :as dt-ffi])
+nil
+user=> (def fn-defs {:glfwInit {:rettype :int32} :glfwGetTime {:rettype :float64}})
+#'user/fn-defs
+user=> (def library-def (dt-ffi/define-library fn-defs))
+#'user/library-def
+user=> (def library-instance (dt-ffi/instantiate-library library-def "/usr/lib/libglfw.so"))
+#'user/library-instance
+user=> (def init (:glfwInit @library-instance))
+#'user/init
+user=> (init)
+1
+user=> (let [f (:glfwGetTime @library-instance)]
+ (bench/bench (f) :verbose))
+amd64 Linux 5.10.68-1-MANJARO 8 cpu(s)
+OpenJDK 64-Bit Server VM 17+35-2724
+Runtime arguments: -Dclojure.basis=/home/jsusk/.clojure/.cpcache/643862289.basis
+Evaluation count : 710822100 in 60 samples of 11847035 calls.
+ Execution time sample mean : 90.900112 ns
+ Execution time mean : 90.919917 ns
+Execution time sample std-deviation : 6.463312 ns
+ Execution time std-deviation : 6.470108 ns
+ Execution time lower quantile : 79.817126 ns ( 2.5%)
+ Execution time upper quantile : 95.454652 ns (97.5%)
+ Overhead used : 6.400704 ns
+nil
+This version of JNA usage is significantly faster than either of the other JNA libraries, but is still substantially slower than using JNI or coffi.
+In addition to the JNA backend, dtype-next has a Java 16-specific backend that uses an older version of Panama. This version requires similar setup to coffi in order to run.
+$ clj -Sdeps '{:deps {cnuernber/dtype-next {:mvn/version "8.032"}
+ criterium/criterium {:mvn/version "0.4.6"}}}' \
+ -J--add-modules=jdk.incubator.foreign \
+ -J-Dforeign.restricted=permit \
+ -J--add-opens=java.base/java.lang=ALL-UNNAMED \
+ -J-Djava.library.path=/usr/lib/x86_64-linux-gnu
+The actual code to run the benchmark is identical to the last example, but is reproduced here for completeness.
+user=> (require '[criterium.core :as bench])
+nil
+user=> (alter-var-root #'bench/estimated-overhead-cache (constantly 6.400703613065185E-9))
+6.400703613065185E-9
+user=> (require '[tech.v3.datatype.ffi :as dt-ffi])
+nil
+user=> (def fn-defs {:glfwInit {:rettype :int32} :glfwGetTime {:rettype :float64}})
+#'user/fn-defs
+user=> (def library-def (dt-ffi/define-library fn-defs))
+#'user/library-def
+user=> (def library-instance (dt-ffi/instantiate-library library-def "/usr/lib/libglfw.so"))
+#'user/library-instance
+user=> (def init (:glfwInit @library-instance))
+#'user/init
+user=> (init)
+1
+user=> (let [f (:glfwGetTime @library-instance)]
+ (bench/bench (f) :verbose))
+amd64 Linux 5.10.68-1-MANJARO 8 cpu(s)
+OpenJDK 64-Bit Server VM 16.0.2+7
+Runtime arguments: --add-modules=jdk.incubator.foreign -Dforeign.restricted=permit --add-opens=java.base/java.lang=ALL-UNNAMED -Djava.library.path=/usr/lib/x86_64-linux-gnu -Dclojure.basis=/home/jsusk/.clojure/.cpcache/2337051659.basis
+Evaluation count : 1588513080 in 60 samples of 26475218 calls.
+ Execution time sample mean : 58.732468 ns
+ Execution time mean : 58.647361 ns
+Execution time sample std-deviation : 9.732389 ns
+ Execution time std-deviation : 9.791738 ns
+ Execution time lower quantile : 31.318115 ns ( 2.5%)
+ Execution time upper quantile : 65.449222 ns (97.5%)
+ Overhead used : 6.400704 ns
+
+Found 14 outliers in 60 samples (23.3333 %)
+ low-severe 8 (13.3333 %)
+ low-mild 4 (6.6667 %)
+ high-mild 2 (3.3333 %)
+ Variance from outliers : 87.6044 % Variance is severely inflated by outliers
+nil
+Not reproduced here, but notable for comparison, in my testing Java 16’s version of the JNI version performed about the same.
+This is significantly faster than the JNA version of dtype-next, but it is still slower than modern Panama. This is likely to simply be a result of optimizations and changes to the Panama API, and when dtype-next is updated to use the Java 17 version of Panama I expect it will perform in line with coffi, but this benchmark will be reproduced when this happens. Still, this shows that as it stands, coffi is the fastest FFI available to Clojure developers.
+Generated by Codox
coffi v1.0.486
coffi.ffi
Functions for creating handles to native functions and loading native libraries.
+Generated by Codox
coffi v1.0.486
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.
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.
+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.
-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.
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.
ensure-symbol
(ensure-symbol symbol-or-addr)Returns the argument if it is a MemorySegment, otherwise calls find-symbol on it.
-freset!
(freset! static-var newval)Sets the value of static-var to newval, running it through serialize.
fswap!
(fswap! static-var f & args)Non-atomically runs the function f over the value stored in static-var.
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.
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.
ensure-symbol
(ensure-symbol symbol-or-addr)Returns the argument if it is a MemorySegment, otherwise calls find-symbol on it.
+freset!
(freset! static-var newval)Sets the value of static-var to newval, running it through serialize.
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.
load-system-library
(load-system-library libname)Loads the library named libname from the system’s load path.
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.
load-system-library
(load-system-library libname)Loads the library named libname from the system’s load path.
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.
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.
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.
make-varargs-factory
(make-varargs-factory symbol required-args ret)Returns a function for constructing downcalls with additional types for arguments.
+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.
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.
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.
-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.
-reify-symbolspec
multimethod
Takes a spec for a symbol reference and returns a live value for that type.
-static-variable
(static-variable symbol-or-addr type)Constructs a reference to a mutable value stored in symbol-or-addr.
reify-symbolspec
multimethod
Takes a spec for a symbol reference and returns a live value for that type.
+static-variable
(static-variable symbol-or-addr type)static-variable-segment
(static-variable-segment static-var)Gets the backing MemorySegment from static-var.
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.
-vacfn-factory
(vacfn-factory symbol required-args ret)Constructs a varargs factory to call the native function referenced by symbol.
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.
-Generated by Codox
coffi v1.0.486
coffi.layout
Functions for adjusting the layout of structs.
+Generated by Codox
coffi v1.0.486
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.
-Generated by Codox
coffi v1.0.486
coffi.mem
Functions for managing native allocations, memory arenas, and (de)serialization.
+Generated by Codox
coffi v1.0.486
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.
address?
(address? addr)Checks if an object is a memory address.
nil is considered an address.
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.
alloc-instance
(alloc-instance type)(alloc-instance type arena)Allocates a memory segment for the given type.
alloc-with
(alloc-with allocator size)(alloc-with allocator size alignment)Allocates size bytes using the allocator.
alloc-instance
(alloc-instance type)(alloc-instance type arena)Allocates a memory segment for the given type.
alloc-with
(alloc-with allocator size)(alloc-with allocator size alignment)Allocates size bytes using the allocator.
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.
-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).
auto-arena
(auto-arena)Constructs a new memory arena that is managed by the garbage collector.
+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).
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.
-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.
-clone-segment
(clone-segment segment)(clone-segment segment arena)Clones the content of segment into a new segment of the same size.
clone-segment
(clone-segment segment)(clone-segment segment arena)Clones the content of segment into a new segment of the same size.
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.
-defalias
macro
(defalias new-type aliased-type)Defines a type alias from new-type to aliased-type.
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.
-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.
-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.
-deserialize-from
multimethod
Deserializes the given segment into a Clojure data structure.
+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*.
-global-arena
(global-arena)Constructs the global arena, which will never reclaim its resources.
+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.
-java-layout
(java-layout type)Gets the Java class to an argument of this type for a method handle.
+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.
-native-endian
The ByteOrder for the native endianness of the current hardware.
See big-endian, little-endian.
-null
The NULL pointer object.
While this object is safe to pass to functions which serialize to a pointer, it’s generally encouraged to simply pass nil. This value primarily exists to make it easier to write custom types with a primitive pointer representation.
primitive-type
multimethod
Gets the primitive type that is used to pass as an argument for the type.
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.
-read-address
(read-address segment)(read-address segment offset)Reads an address from the segment, at an optional offset, wrapped in a MemorySegment.
read-byte
(read-byte segment)(read-byte segment offset)Reads a byte from the segment, at an optional offset.
read-char
(read-char segment)(read-char segment offset)Reads a char from the segment, at an optional offset.
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.
read-address
(read-address segment)(read-address segment offset)Reads an address from the segment, at an optional offset, wrapped in a MemorySegment.
read-byte
(read-byte segment)(read-byte segment offset)Reads a byte from the segment, at an optional offset.
read-char
(read-char segment)(read-char segment offset)Reads a char from the segment, at an optional offset.
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.
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.
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.
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.
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.
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.
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.
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.
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.
reinterpret
(reinterpret segment size)(reinterpret segment size arena)(reinterpret segment size arena cleanup)Reinterprets the segment as having the passed size.
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.
seq-of
(seq-of type segment)Constructs a lazy sequence of type elements deserialized from segment.
seq-of
(seq-of type segment)Constructs a lazy sequence of type elements deserialized from segment.
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.
-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.
-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.
slice
(slice segment offset)(slice segment offset size)Get a slice over the segment with the given offset.
slice-segments
(slice-segments segment size)Constructs a lazy seq of size-length memory segments, sliced from segment.
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.
write-byte
(write-byte segment value)(write-byte segment offset value)Writes a byte to the segment, at an optional offset.
write-char
(write-char segment value)(write-char segment offset value)Writes a char to the segment, at an optional offset.
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.
slice
(slice segment offset)(slice segment offset size)Get a slice over the segment with the given offset.
slice-segments
(slice-segments segment size)Constructs a lazy seq of size-length memory segments, sliced from segment.
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.
write-byte
(write-byte segment value)(write-byte segment offset value)Writes a byte to the segment, at an optional offset.
write-char
(write-char segment value)(write-char segment offset value)Writes a char to the segment, at an optional offset.
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.
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.
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.
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.
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.
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.
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.
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.
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.