From 3948e63089270aa1295ad5d13b87b6e4123d6107 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Fri, 31 Mar 2023 11:02:54 -0500 Subject: [PATCH 1/6] Update readme --- README.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 908748e..ab15e44 100644 --- a/README.md +++ b/README.md @@ -1117,10 +1117,7 @@ stands, coffi is the fastest FFI available to Clojure developers. The project author is aware of these issues and plans to fix them in a future release: -- On M1 Macs occasional crashes are present when returning structs by value from - native code. At the moment this appears to be an upstream issue with Panama, - and will be reported once a minimal reproduction case with only Panama is - produced. +No known issues, hooray! ## Future Plans These features are planned for future releases. @@ -1140,10 +1137,11 @@ 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. -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 +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 @@ -1154,6 +1152,6 @@ September 2023. ## License -Copyright © 2022 Joshua Suskalo +Copyright © 2023 Joshua Suskalo Distributed under the Eclipse Public License version 1.0. From bcf2e031f995d1c7473797c70f94b9731634c97b Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Tue, 1 Oct 2024 14:18:31 -0400 Subject: [PATCH 2/6] Update readme and codox definitions for release tag --- README.md | 4 ++-- deps.edn | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 1252781..fa0b2aa 100644 --- a/README.md +++ b/README.md @@ -16,8 +16,8 @@ This library is available on Clojars. Add one of the following entries to the `:deps` key of your `deps.edn`: ```clojure -org.suskalo/coffi {:mvn/version "0.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 diff --git a/deps.edn b/deps.edn index a7eccbc..33448e5 100644 --- a/deps.edn +++ b/deps.edn @@ -21,11 +21,11 @@ :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"}} :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}" From bfb9e76986601cadde29f4ce1ee10c54db6a535b Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Wed, 2 Oct 2024 14:43:41 -0400 Subject: [PATCH 3/6] Update codox documentation --- deps.edn | 4 +- docs/coffi.ffi.html | 41 ++++++++--- docs/coffi.layout.html | 6 +- docs/coffi.mem.html | 153 +++++++++++++++++++++++++++++------------ docs/index.html | 5 +- 5 files changed, 150 insertions(+), 59 deletions(-) diff --git a/deps.edn b/deps.edn index 33448e5..cc8687e 100644 --- a/deps.edn +++ b/deps.edn @@ -22,6 +22,7 @@ :exec-fn cognitect.test-runner.api/test} :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 "v1.0.450" @@ -29,8 +30,7 @@ :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"]} + :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 From 34952f548f10faebe6e6d2391e9f451649719bbe Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Wed, 2 Oct 2024 14:47:46 -0400 Subject: [PATCH 4/6] Update changelog for release date --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8609d15..985b21c 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] +## [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 From c5b528a7fe8a3b8e577a7a6e30640cb44a6820a6 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Wed, 2 Oct 2024 14:50:56 -0400 Subject: [PATCH 5/6] Add temporary fix for version listed in build --- build.clj | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/build.clj b/build.clj index 89f7b5c..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/"]) From 5f2759b53ad4448f8a40249fc0bb930b3a2906d5 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Wed, 2 Oct 2024 14:51:15 -0400 Subject: [PATCH 6/6] Update description in pom --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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