From 8e6947392473614d3dbc7d3b6d9878e700bf74e8 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Mon, 25 Oct 2021 09:46:41 -0500 Subject: [PATCH 01/15] Add section for unreleased --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index baa009d..97b1c53 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,8 @@ # 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/). +## [Unreleased] + ## [0.2.277] - 2021-10-25 ### Fixed - Non-primitive arguments on upcalls would generate invalid bytecode with `nil` instructions @@ -73,6 +75,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.2.277...HEAD [0.2.277]: https://github.com/IGJoshua/coffi/compare/v0.2.259...v0.2.277 [0.2.259]: https://github.com/IGJoshua/coffi/compare/v0.1.251...v0.2.259 [0.1.251]: https://github.com/IGJoshua/coffi/compare/v0.1.246...v0.1.251 From 1b8923bc33db6d1d58fd12362db5a6be45ee9bd8 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Mon, 10 Jan 2022 13:29:01 -0600 Subject: [PATCH 02/15] Turn off lsp unused public var lint --- .clj-kondo/config.edn | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.clj-kondo/config.edn b/.clj-kondo/config.edn index 9529527..d4a9459 100644 --- a/.clj-kondo/config.edn +++ b/.clj-kondo/config.edn @@ -1 +1,2 @@ -{:config-paths ["org.suskalo/coffi"]} +{:config-paths ["org.suskalo/coffi"] + :linters {:clojure-lsp/unused-public-var {:level :off}}} From 579393f830c349a4857c40dbfbcdbbfee63d7528 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Mon, 10 Jan 2022 13:30:01 -0600 Subject: [PATCH 03/15] Add align-of --- src/clj/coffi/mem.clj | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/clj/coffi/mem.clj b/src/clj/coffi/mem.clj index b003216..5095a59 100644 --- a/src/clj/coffi/mem.clj +++ b/src/clj/coffi/mem.clj @@ -349,6 +349,11 @@ [type] (.byteSize ^MemoryLayout (c-layout type))) +(defn align-of + "The alignment in bytes of the given `type`." + [type] + (.byteAlignment ^MemoryLayout (c-layout type))) + (defn alloc-instance "Allocates a memory segment for the given `type`." ([type] (alloc-instance type (connected-scope))) From 95856cb4f3279567339f78160b340735c3d53b19 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Mon, 10 Jan 2022 13:31:27 -0600 Subject: [PATCH 04/15] Add with-c-layout function --- src/clj/coffi/layout.clj | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 src/clj/coffi/layout.clj diff --git a/src/clj/coffi/layout.clj b/src/clj/coffi/layout.clj new file mode 100644 index 0000000..d92e02d --- /dev/null +++ b/src/clj/coffi/layout.clj @@ -0,0 +1,29 @@ +(ns coffi.layout + "Functions for adjusting the layout of structs." + (:require + [coffi.mem :as mem])) + +(defn with-c-layout + "Forces a struct specification to C layout rules. + + This will add padding fields between fields to match C alignment + requirements." + [struct-spec] + (let [aligned-fields + (loop [offset 0 + aligned-fields [] + fields (nth struct-spec 1)] + (if (seq fields) + (let [[[_ type :as field] & fields] fields + size (mem/size-of type) + r (rem offset (mem/align-of type))] + (recur (+ offset r size) + (cond-> aligned-fields + (pos? r) (conj [:padding [::mem/padding r]]) + :always (conj field)) + fields)) + (let [strongest-alignment (mem/align-of struct-spec) + r (rem offset strongest-alignment)] + (cond-> aligned-fields + (pos? r) (conj [:padding [::mem/padding r]])))))] + (assoc struct-spec 1 aligned-fields))) From 49f9e60b11fed39cdd41e721bb04bb6be20be999 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Mon, 10 Jan 2022 13:34:58 -0600 Subject: [PATCH 05/15] Allow expressions that evaluate to types in defalias --- src/clj/coffi/mem.clj | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/clj/coffi/mem.clj b/src/clj/coffi/mem.clj index 5095a59..201f39e 100644 --- a/src/clj/coffi/mem.clj +++ b/src/clj/coffi/mem.clj @@ -781,7 +781,8 @@ aliased type." {:style/indent [:defn]} [new-type aliased-type] - (if (primitive-type aliased-type) + (if (and (s/valid? ::type aliased-type) + (primitive-type aliased-type)) `(let [aliased# ~aliased-type] (defmethod primitive-type ~new-type [_type#] @@ -804,4 +805,4 @@ (deserialize-from segment# aliased#))))) (s/fdef defalias :args (s/cat :new-type qualified-keyword? - :aliased-type ::type)) + :aliased-type any?)) From da12b26e3c71acc8d0373cb8aff08defd2c4c47c Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Mon, 10 Jan 2022 14:06:34 -0600 Subject: [PATCH 06/15] Fix bug with incorrect padding size --- src/clj/coffi/layout.clj | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/clj/coffi/layout.clj b/src/clj/coffi/layout.clj index d92e02d..047bd62 100644 --- a/src/clj/coffi/layout.clj +++ b/src/clj/coffi/layout.clj @@ -17,13 +17,14 @@ (let [[[_ type :as field] & fields] fields size (mem/size-of type) r (rem offset (mem/align-of type))] - (recur (+ offset r size) + (recur (cond-> (+ offset size) + (pos? r) (+ (- size r))) (cond-> aligned-fields - (pos? r) (conj [:padding [::mem/padding r]]) + (pos? r) (conj [::padding [::mem/padding (- size r)]]) :always (conj field)) fields)) (let [strongest-alignment (mem/align-of struct-spec) r (rem offset strongest-alignment)] (cond-> aligned-fields - (pos? r) (conj [:padding [::mem/padding r]])))))] + (pos? r) (conj [::padding [::mem/padding (- strongest-alignment r)]])))))] (assoc struct-spec 1 aligned-fields))) From 900112b6e42a1997ad2f9119427c46e37ea1963e Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Mon, 10 Jan 2022 14:22:19 -0600 Subject: [PATCH 07/15] Fix bug where characters were read as java characters --- src/clj/coffi/mem.clj | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/clj/coffi/mem.clj b/src/clj/coffi/mem.clj index b003216..cf8bf38 100644 --- a/src/clj/coffi/mem.clj +++ b/src/clj/coffi/mem.clj @@ -550,7 +550,7 @@ (defmethod deserialize-from ::char [segment _type] - (MemoryAccess/getChar segment)) + (char (Byte/toUnsignedInt (MemoryAccess/getByte segment)))) (defmethod deserialize-from ::float [segment _type] From fb927e827aa3ef984edda10a2eba6648bcdef0c4 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Mon, 10 Jan 2022 14:37:56 -0600 Subject: [PATCH 08/15] Add test for c alignment --- test/c/ffi_test.c | 15 +++++++++++++++ test/clj/coffi/ffi_test.clj | 18 ++++++++++++++++-- 2 files changed, 31 insertions(+), 2 deletions(-) diff --git a/test/c/ffi_test.c b/test/c/ffi_test.c index 4d9d520..8235c1b 100644 --- a/test/c/ffi_test.c +++ b/test/c/ffi_test.c @@ -48,3 +48,18 @@ StringFactory get_downcall(int whichString) { return 0; } } + +typedef struct alignment_test { + char a; + double x; + float y; +} AlignmentTest; + +AlignmentTest get_struct() { + AlignmentTest ret = {}; + ret.a = 'x'; + ret.x = 3.14; + ret.y = 42.0; + + return ret; +} diff --git a/test/clj/coffi/ffi_test.clj b/test/clj/coffi/ffi_test.clj index 122e075..d7be985 100644 --- a/test/clj/coffi/ffi_test.clj +++ b/test/clj/coffi/ffi_test.clj @@ -1,8 +1,9 @@ (ns coffi.ffi-test (:require [clojure.test :as t] - [coffi.mem :as mem] - [coffi.ffi :as ffi])) + [coffi.ffi :as ffi] + [coffi.layout :as layout] + [coffi.mem :as mem])) (ffi/load-library "target/ffi_test.so") @@ -30,3 +31,16 @@ (t/is (= ((ffi/cfn "upcall_test" [[::ffi/fn [] ::mem/c-string]] ::mem/c-string) (fn [] "hello")) "hello"))) + +(mem/defalias ::alignment-test + (layout/with-c-layout + [::mem/struct + [[:a ::mem/char] + [:x ::mem/double] + [:y ::mem/float]]])) + +(t/deftest padding-matches + (t/is (= (dissoc ((ffi/cfn "get_struct" [] ::alignment-test)) ::layout/padding) + {:a \x + :x 3.14 + :y 42.0}))) From a5db2d4f3a7bc2c6686a48beb81b5f879aa5cef6 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Mon, 10 Jan 2022 14:46:00 -0600 Subject: [PATCH 09/15] Update changelog --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 97b1c53..1cfbdb1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,8 @@ All notable changes to this project will be documented in this file. This change log follows the conventions of [keepachangelog.com](http://keepachangelog.com/). ## [Unreleased] +### Fixed +- C-characters were being read as UTF-16 rather than ASCII code points ## [0.2.277] - 2021-10-25 ### Fixed From d54863ff2b5b91162b6e3a42419b7d0dbe8cc56f Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Mon, 10 Jan 2022 14:54:53 -0600 Subject: [PATCH 10/15] Update changelog --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 97b1c53..920c85a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,8 @@ All notable changes to this project will be documented in this file. This change log follows the conventions of [keepachangelog.com](http://keepachangelog.com/). ## [Unreleased] +### Added +- New `coffi.layout` namespace with support for forcing C layout rules on structs ## [0.2.277] - 2021-10-25 ### Fixed From f96016ca2d006265d7ba140f58593d9121c133e2 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Mon, 10 Jan 2022 14:57:08 -0600 Subject: [PATCH 11/15] Version bump --- build.clj | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build.clj b/build.clj index 039f034..d4f2ea4 100644 --- a/build.clj +++ b/build.clj @@ -17,7 +17,7 @@ [clojure.tools.build.api :as b])) (def lib-coord 'org.suskalo/coffi) -(def version (format "0.2.%s" (b/git-count-revs nil))) +(def version (format "0.3.%s" (b/git-count-revs nil))) (def resource-dirs ["resources/"]) From 1bbb8a7d95eb351b26d693211770b64a626b06a0 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Mon, 10 Jan 2022 14:57:48 -0600 Subject: [PATCH 12/15] Fix name field in pom --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index 34a7f9e..8b013fd 100644 --- a/pom.xml +++ b/pom.xml @@ -1,7 +1,7 @@ 4.0.0 - coffi + org.suskalo/coffi A Foreign Function Interface in Clojure for JDK 17. https://github.com/IGJoshua/coffi From 0d8fa7f6a837583edbc796431f930998160cc8f3 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Mon, 10 Jan 2022 15:05:46 -0600 Subject: [PATCH 13/15] Update changelog for release --- CHANGELOG.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a5cfe8e..db60e8b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,7 @@ # 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/). -## [Unreleased] +## [0.3.298] - 2022-01-10 ### Added - New `coffi.layout` namespace with support for forcing C layout rules on structs @@ -80,7 +80,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.2.277...HEAD +[0.3.298]: https://github.com/IGJoshua/coffi/compare/v0.2.277...v0.3.298 [0.2.277]: https://github.com/IGJoshua/coffi/compare/v0.2.259...v0.2.277 [0.2.259]: https://github.com/IGJoshua/coffi/compare/v0.1.251...v0.2.259 [0.1.251]: https://github.com/IGJoshua/coffi/compare/v0.1.246...v0.1.251 From fecee74d727b9f7e4ac111555e4d16c94aea0c3c Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Mon, 10 Jan 2022 15:05:55 -0600 Subject: [PATCH 14/15] Update codox version --- deps.edn | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deps.edn b/deps.edn index c78de3a..c3c604b 100644 --- a/deps.edn +++ b/deps.edn @@ -24,7 +24,7 @@ :codox {:extra-deps {codox/codox {:mvn/version "0.10.7"}} :exec-fn codox.main/generate-docs :exec-args {:name "coffi" - :version "v0.2.277" + :version "v0.3.298" :description "A Foreign Function Interface in Clojure for JDK 17." :source-paths ["src/clj"] :output-path "docs" From a5e9f94a35c03ba440443eba0ed8004b3e87dca6 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Mon, 10 Jan 2022 15:06:21 -0600 Subject: [PATCH 15/15] Update codox documentation --- docs/coffi.ffi.html | 18 +++++++++--------- docs/coffi.mem.html | 46 ++++++++++++++++++++++----------------------- docs/index.html | 2 +- 3 files changed, 33 insertions(+), 33 deletions(-) diff --git a/docs/coffi.ffi.html b/docs/coffi.ffi.html index 19be1f6..4301514 100644 --- a/docs/coffi.ffi.html +++ b/docs/coffi.ffi.html @@ -1,19 +1,19 @@ -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

find-symbol

(find-symbol sym)

Gets the MemoryAddress 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

find-symbol

(find-symbol sym)

Gets the MemoryAddress 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, and the address of the value can be queried with address-of.

-

See freset!, fswap!.

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 +

See freset!, fswap!.

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.mem.html b/docs/coffi.mem.html index 77d8b1e..c34767b 100644 --- a/docs/coffi.mem.html +++ b/docs/coffi.mem.html @@ -1,37 +1,37 @@ -coffi.mem documentation

Project

Namespaces

Public Vars

coffi.mem

Functions for managing native allocations, resource scopes, and (de)serialization.

+coffi.mem documentation

Project

Namespaces

Public Vars

coffi.mem

Functions for managing native allocations, resource scopes, 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-scope in order to ensure it won’t be released during its manipulation.

add-close-action!

(add-close-action! scope action)

Adds a 0-arity function to be run when the scope 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

alloc

(alloc size)(alloc size scope)

Allocates size bytes.

-

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

view source

alloc-instance

(alloc-instance type)(alloc-instance type scope)

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 scope)(as-segment address size scope cleanup)

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

-

If cleanup is provided, it is a 0-arity function run when the scope is closed. This can be used to register a free method for the memory, or do other cleanup in a way that doesn’t require modifying the code at the point of freeing, and allows shared or garbage collected resources to be freed correctly.

view source

c-layout

multimethod

Gets the layout object for a given type.

+

When writing code that manipulates a segment, it’s best practice to use with-acquired on the segment-scope in order to ensure it won’t be released during its manipulation.

add-close-action!

(add-close-action! scope action)

Adds a 0-arity function to be run when the scope 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 scope)

Allocates size bytes.

+

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

view source

alloc-instance

(alloc-instance type)(alloc-instance type scope)

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 scope)(as-segment address size scope cleanup)

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

+

If cleanup is provided, it is a 0-arity function run when the scope is closed. This can be used to register a free method for the memory, or do other cleanup in a way that doesn’t require modifying the code at the point of freeing, and allows shared or garbage collected resources to be freed correctly.

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

clone-segment

(clone-segment segment)(clone-segment segment scope)

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

view source

connected-scope

(connected-scope)

Constructs a new scope to reclaim all connected resources at once.

+

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

view source

clone-segment

(clone-segment segment)(clone-segment segment scope)

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

view source

connected-scope

(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

copy-segment

(copy-segment dest src)

Copies the content to dest from src

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.

+

This type of scope 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

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 scope if they perform multiple memory operations.

view source

global-scope

(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

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

null?

(null? addr)

Checks if a memory address is null.

view source

primitive-type

multimethod

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

+

Implementations of this should be inside a with-acquired block for the the segment’s scope if they perform multiple memory operations.

view source

global-scope

(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

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

null?

(null? addr)

Checks if a memory address is null.

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?

A set of all primitive types.

view source

scope-allocator

(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

(segment-scope segment)

Gets the scope 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 scope)

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.

+

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

view source

primitive?

A set of all primitive types.

view source

scope-allocator

(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

(segment-scope segment)

Gets the scope 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 scope)

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

+

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 scope, 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 scope if they perform multiple memory operations.

view source

shared-scope

(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

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

(slice-global address size)

Gets a slice of the global address space.

-

Because this fetches from the global segment, it has no associated scope, and therefore the reference created here cannot prevent the value from being freed. Be careful to ensure that you are not retaining an object incorrectly.

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

(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

with-acquired

macro

(with-acquired scopes & body)

Acquires one or more scopes until the body completes.

-

This is only necessary to do on shared scopes, however if you are operating on an arbitrary passed scope, 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
\ No newline at end of file +

Implementations of this should be inside a with-acquired block for the scope if they perform multiple memory operations.

view source

shared-scope

(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

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

(slice-global address size)

Gets a slice of the global address space.

+

Because this fetches from the global segment, it has no associated scope, and therefore the reference created here cannot prevent the value from being freed. Be careful to ensure that you are not retaining an object incorrectly.

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

(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

with-acquired

macro

(with-acquired scopes & body)

Acquires one or more scopes until the body completes.

+

This is only necessary to do on shared scopes, however if you are operating on an arbitrary passed scope, 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
\ No newline at end of file diff --git a/docs/index.html b/docs/index.html index 342adf3..7381afb 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1,3 +1,3 @@ -coffi v0.2.277

Project

Namespaces

coffi v0.2.277

A Foreign Function Interface in Clojure for JDK 17.

Namespaces

coffi.ffi

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

Public variables and functions:

coffi.mem

Functions for managing native allocations, resource scopes, and (de)serialization.

Public variables and functions:

\ No newline at end of file +coffi v0.3.298

Project

Namespaces

coffi v0.3.298

A Foreign Function Interface in Clojure for JDK 17.

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, resource scopes, and (de)serialization.

Public variables and functions:

\ No newline at end of file