From e00f8d2a7f15fa613ca5fc17b86d174c3dcd9ade Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Mon, 10 Jan 2022 15:36:42 -0600 Subject: [PATCH 01/33] Add unreleased section --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index db60e8b..9994575 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.3.298] - 2022-01-10 ### Added - New `coffi.layout` namespace with support for forcing C layout rules on structs @@ -80,6 +82,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.3.298...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 From 110dc490b225f52f4016780990ca72c8aa030739 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Mon, 10 Jan 2022 15:37:36 -0600 Subject: [PATCH 02/33] Add missing codox doc file for namespace --- docs/coffi.layout.html | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 docs/coffi.layout.html diff --git a/docs/coffi.layout.html b/docs/coffi.layout.html new file mode 100644 index 0000000..5daf5ef --- /dev/null +++ b/docs/coffi.layout.html @@ -0,0 +1,4 @@ + +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 From faca63b50c2d4bbe4c937103f0ec9d1f027844fb Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Tue, 18 Jan 2022 13:25:56 -0600 Subject: [PATCH 03/33] Add constants for byte orders --- src/clj/coffi/mem.clj | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/src/clj/coffi/mem.clj b/src/clj/coffi/mem.clj index e647268..a2a20c1 100644 --- a/src/clj/coffi/mem.clj +++ b/src/clj/coffi/mem.clj @@ -21,6 +21,7 @@ (:require [clojure.spec.alpha :as s]) (:import + (java.nio ByteOrder) (jdk.incubator.foreign Addressable CLinker @@ -205,6 +206,24 @@ (map #(slice segment (* % size) size) (range num-segments)))) +(def big-endian + "The big-endian [[ByteOrder]]. + + See [[little-endian]], [[native-endian]]." + ByteOrder/BIG_ENDIAN) + +(def little-endian + "The little-endian [[ByteOrder]]. + + See [[big-endian]], [[native-endian]]" + ByteOrder/LITTLE_ENDIAN) + +(def native-endian + "The [[ByteOrder]] for the native endianness of the current hardware. + + See [[big-endian]], [[little-endian]]." + (ByteOrder/nativeOrder)) + (defn- type-dispatch "Gets a type dispatch value from a (potentially composite) type." [type] From 55d770cc3419b4717f0557d4271815ee372f6148 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Tue, 18 Jan 2022 13:26:35 -0600 Subject: [PATCH 04/33] Add layout constants for c-style primitive layouts --- src/clj/coffi/mem.clj | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/src/clj/coffi/mem.clj b/src/clj/coffi/mem.clj index a2a20c1..025988d 100644 --- a/src/clj/coffi/mem.clj +++ b/src/clj/coffi/mem.clj @@ -224,6 +224,24 @@ See [[big-endian]], [[little-endian]]." (ByteOrder/nativeOrder)) +(def byte-layout CLinker/C_CHAR) + +(def short-layout CLinker/C_SHORT) + +(def int-layout CLinker/C_INT) + +(def long-layout CLinker/C_LONG) + +(def long-long-layout CLinker/C_LONG_LONG) + +(def char-layout CLinker/C_CHAR) + +(def float-layout CLinker/C_FLOAT) + +(def double-layout CLinker/C_DOUBLE) + +(def pointer-layout CLinker/C_POINTER) + (defn- type-dispatch "Gets a type dispatch value from a (potentially composite) type." [type] From 7350a5df1c275b6151d5ee7283eaec50c923e00b Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Tue, 18 Jan 2022 13:27:22 -0600 Subject: [PATCH 05/33] Use layout primitives in c-layout multimethod --- src/clj/coffi/mem.clj | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/clj/coffi/mem.clj b/src/clj/coffi/mem.clj index 025988d..c43694a 100644 --- a/src/clj/coffi/mem.clj +++ b/src/clj/coffi/mem.clj @@ -326,39 +326,39 @@ (defmethod c-layout ::byte [_type] - CLinker/C_CHAR) + byte-layout) (defmethod c-layout ::short [_type] - CLinker/C_SHORT) + short-layout) (defmethod c-layout ::int [_type] - CLinker/C_INT) + int-layout) (defmethod c-layout ::long [_type] - CLinker/C_LONG) + long-layout) (defmethod c-layout ::long-long [_type] - CLinker/C_LONG_LONG) + long-long-layout) (defmethod c-layout ::char [_type] - CLinker/C_CHAR) + char-layout) (defmethod c-layout ::float [_type] - CLinker/C_FLOAT) + float-layout) (defmethod c-layout ::double [_type] - CLinker/C_DOUBLE) + double-layout) (defmethod c-layout ::pointer [_type] - CLinker/C_POINTER) + pointer-layout) (def java-prim-layout "Map of primitive type names to the Java types for a method handle." From b960c01bb3940d110905d3be38de435bbdfd5587 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Tue, 18 Jan 2022 13:28:00 -0600 Subject: [PATCH 06/33] Add support for layouts being passed to size-of and align-of --- src/clj/coffi/mem.clj | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/src/clj/coffi/mem.clj b/src/clj/coffi/mem.clj index c43694a..ad66d26 100644 --- a/src/clj/coffi/mem.clj +++ b/src/clj/coffi/mem.clj @@ -378,18 +378,22 @@ If a type serializes to a primitive it returns return a Java primitive type. Otherwise, it returns [[MemorySegment]]." - [type] + ^Class [type] (java-prim-layout (or (primitive-type type) type) MemorySegment)) (defn size-of "The size in bytes of the given `type`." - [type] - (.byteSize ^MemoryLayout (c-layout type))) + ^long [type] + (let [t (cond-> type + (not (instance? MemoryLayout type)) c-layout)] + (.byteSize ^MemoryLayout t))) (defn align-of "The alignment in bytes of the given `type`." - [type] - (.byteAlignment ^MemoryLayout (c-layout type))) + ^long [type] + (let [t (cond-> type + (not (instance? MemoryLayout type)) c-layout)] + (.byteAlignment ^MemoryLayout t))) (defn alloc-instance "Allocates a memory segment for the given `type`." From b029a41f6a2cbcb9d28d85e1e6beada9bff35189 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Tue, 18 Jan 2022 13:28:43 -0600 Subject: [PATCH 07/33] Update type hinting for alloc-instance based on size-of --- src/clj/coffi/mem.clj | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/clj/coffi/mem.clj b/src/clj/coffi/mem.clj index ad66d26..d11673b 100644 --- a/src/clj/coffi/mem.clj +++ b/src/clj/coffi/mem.clj @@ -397,8 +397,8 @@ (defn alloc-instance "Allocates a memory segment for the given `type`." - ([type] (alloc-instance type (connected-scope))) - ([type scope] (MemorySegment/allocateNative (long (size-of type)) ^ResourceScope scope))) + (^MemorySegment [type] (alloc-instance type (connected-scope))) + (^MemorySegment [type scope] (MemorySegment/allocateNative ^long (size-of type) ^ResourceScope scope))) (declare serialize serialize-into) From e8b3c8e2b2c75b907b0d34dd6164792775bf2fe9 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Tue, 18 Jan 2022 13:38:32 -0600 Subject: [PATCH 08/33] Add type hints to most utility functions --- src/clj/coffi/mem.clj | 55 +++++++++++++++++++++++-------------------- 1 file changed, 29 insertions(+), 26 deletions(-) diff --git a/src/clj/coffi/mem.clj b/src/clj/coffi/mem.clj index d11673b..049d9fe 100644 --- a/src/clj/coffi/mem.clj +++ b/src/clj/coffi/mem.clj @@ -88,14 +88,14 @@ "Allocates `size` bytes. If a `scope` is provided, the allocation will be reclaimed when it is closed." - ([size] (alloc size (connected-scope))) - ([size scope] (MemorySegment/allocateNative (long size) ^ResourceScope scope))) + (^MemorySegment [size] (alloc size (connected-scope))) + (^MemorySegment [size scope] (MemorySegment/allocateNative (long size) ^ResourceScope scope))) (defn alloc-with "Allocates `size` bytes using the `allocator`." - ([allocator size] + (^MemorySegment [allocator size] (.allocate ^SegmentAllocator allocator (long size))) - ([allocator size alignment] + (^MemorySegment [allocator size alignment] (.allocate ^SegmentAllocator allocator (long size) (long alignment)))) (defmacro with-acquired @@ -123,7 +123,7 @@ "Gets the address of a given segment. This value can be used as an argument to functions which take a pointer." - [addressable] + ^MemoryAddress [addressable] (.address ^Addressable addressable)) (defn null? @@ -144,27 +144,27 @@ 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." - [address size] + ^MemorySegment [address size] (.asSlice (MemorySegment/globalNativeSegment) ^MemoryAddress address (long size))) (defn slice "Get a slice over the `segment` with the given `offset`." - ([segment offset] + (^MemorySegment [segment offset] (.asSlice ^MemorySegment segment (long offset))) - ([segment offset size] + (^MemorySegment [segment offset size] (.asSlice ^MemorySegment segment (long offset) (long size)))) (defn slice-into "Get a slice into the `segment` starting at the `address`." - ([address segment] + (^MemorySegment [address segment] (.asSlice ^MemorySegment segment ^MemoryAddress address)) - ([address segment size] + (^MemorySegment [address segment size] (.asSlice ^MemorySegment segment ^MemoryAddress address (long size)))) (defn with-offset "Get a new address `offset` from the old `address`." - [address offset] + ^MemoryAddress [address offset] (.addOffset ^MemoryAddress address (long offset))) (defn as-segment @@ -175,34 +175,37 @@ 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." - ([address size scope] - (.asSegment ^MemoryAddress address size scope)) - ([address size scope cleanup] - (.asSegment ^MemoryAddress address size cleanup scope))) + (^MemorySegment [^MemoryAddress address size scope] + (.asSegment address (long size) scope)) + (^MemorySegment [^MemoryAddress address size ^ResourceScope scope cleanup] + (.asSegment address (long size) cleanup scope))) (defn add-close-action! "Adds a 0-arity function to be run when the `scope` closes." - [scope action] - (.addCloseAction ^ResourceScope scope action)) + [^ResourceScope scope ^Runnable action] + (.addCloseAction scope action) + nil) (defn copy-segment - "Copies the content to `dest` from `src`" - [dest src] + "Copies the content to `dest` from `src`. + + Returns `dest`." + ^MemorySegment [^MemorySegment dest ^MemorySegment src] (with-acquired (map segment-scope [src dest]) - (.copyFrom ^MemorySegment dest ^MemorySegment src))) + (.copyFrom dest src) + dest)) (defn clone-segment "Clones the content of `segment` into a new segment of the same size." - ([segment] (clone-segment segment (connected-scope))) - ([segment scope] + (^MemorySegment [segment] (clone-segment segment (connected-scope))) + (^MemorySegment [^MemorySegment segment scope] (with-acquired [(segment-scope segment) scope] - (doto ^MemorySegment (alloc (.byteSize ^MemorySegment segment) scope) - (copy-segment segment))))) + (copy-segment ^MemorySegment (alloc (.byteSize segment) scope) segment)))) (defn slice-segments "Constructs a lazy seq of `size`-length memory segments, sliced from `segment`." - [segment size] - (let [num-segments (quot (.byteSize ^MemorySegment segment) size)] + [^MemorySegment segment size] + (let [num-segments (quot (.byteSize segment) size)] (map #(slice segment (* % size) size) (range num-segments)))) From 2cfa0ed6231209037e512fd8d1d6c8acc789768a Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Tue, 18 Jan 2022 13:38:48 -0600 Subject: [PATCH 09/33] Add docstrings to layout defs --- src/clj/coffi/mem.clj | 36 +++++++++++++++++++++++++++--------- 1 file changed, 27 insertions(+), 9 deletions(-) diff --git a/src/clj/coffi/mem.clj b/src/clj/coffi/mem.clj index 049d9fe..ecd2369 100644 --- a/src/clj/coffi/mem.clj +++ b/src/clj/coffi/mem.clj @@ -227,23 +227,41 @@ See [[big-endian]], [[little-endian]]." (ByteOrder/nativeOrder)) -(def byte-layout CLinker/C_CHAR) +(def byte-layout + "The [[MemoryLayout]] for a byte in [[native-endian]] [[ByteOrder]]." + CLinker/C_CHAR) -(def short-layout CLinker/C_SHORT) +(def short-layout + "The [[MemoryLayout]] for a c-sized short in [[native-endian]] [[ByteOrder]]." + CLinker/C_SHORT) -(def int-layout CLinker/C_INT) +(def int-layout + "The [[MemoryLayout]] for a c-sized int in [[native-endian]] [[ByteOrder]]." + CLinker/C_INT) -(def long-layout CLinker/C_LONG) +(def long-layout + "The [[MemoryLayout]] for a c-sized long in [[native-endian]] [[ByteOrder]]." + CLinker/C_LONG) -(def long-long-layout CLinker/C_LONG_LONG) +(def long-long-layout + "The [[MemoryLayout]] for a c-sized long-long in [[native-endian]] [[ByteOrder]]." + CLinker/C_LONG_LONG) -(def char-layout CLinker/C_CHAR) +(def char-layout + "The [[MemoryLayout]] for a c-sized char in [[native-endian]] [[ByteOrder]]." + CLinker/C_CHAR) -(def float-layout CLinker/C_FLOAT) +(def float-layout + "The [[MemoryLayout]] for a c-sized float in [[native-endian]] [[ByteOrder]]." + CLinker/C_FLOAT) -(def double-layout CLinker/C_DOUBLE) +(def double-layout + "The [[MemoryLayout]] for a c-sized double in [[native-endian]] [[ByteOrder]]." + CLinker/C_DOUBLE) -(def pointer-layout CLinker/C_POINTER) +(def pointer-layout + "The [[MemoryLayout]] for a native pointer in [[native-endian]] [[ByteOrder]]." + CLinker/C_POINTER) (defn- type-dispatch "Gets a type dispatch value from a (potentially composite) type." From cf529bbd3d7e632b53145c79cc1d347c2a6a0a57 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Tue, 18 Jan 2022 13:39:04 -0600 Subject: [PATCH 10/33] Add functions for reading and writing primitives --- src/clj/coffi/mem.clj | 247 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 247 insertions(+) diff --git a/src/clj/coffi/mem.clj b/src/clj/coffi/mem.clj index ecd2369..2e2cec0 100644 --- a/src/clj/coffi/mem.clj +++ b/src/clj/coffi/mem.clj @@ -263,6 +263,253 @@ "The [[MemoryLayout]] for a native pointer in [[native-endian]] [[ByteOrder]]." CLinker/C_POINTER) +(defn read-byte + "Reads a [[byte]] from the `segment`, at an optional `offset`." + {:inline + (fn read-byte-inline + ([segment] + `(MemoryAccess/getByte ~segment)) + ([segment offset] + `(MemoryAccess/getByteAtOffset ~segment ~offset)))} + ([^MemorySegment segment] + (MemoryAccess/getByte segment)) + ([^MemorySegment segment ^long offset] + (MemoryAccess/getByteAtOffset segment offset))) + +(defn read-short + "Reads a [[short]] from the `segment`, at an optional `offset`. + + If `byte-order` is not provided, it defaults to [[native-endian]]." + {:inline + (fn read-short-inline + ([segment] + `(MemoryAccess/getShort ~segment)) + ([segment offset] + `(MemoryAccess/getShortAtOffset ~segment ~offset)) + ([segment offset byte-order] + `(MemoryAccess/getShortAtOffset ~segment ~offset ~byte-order)))} + ([^MemorySegment segment] + (MemoryAccess/getShort segment)) + ([^MemorySegment segment ^long offset] + (MemoryAccess/getShortAtOffset segment offset)) + ([^MemorySegment segment ^long offset ^ByteOrder byte-order] + (MemoryAccess/getShortAtOffset segment offset byte-order))) + +(defn read-int + "Reads a [[int]] from the `segment`, at an optional `offset`. + + If `byte-order` is not provided, it defaults to [[native-endian]]." + {:inline + (fn read-int-inline + ([segment] + `(MemoryAccess/getInt ~segment)) + ([segment offset] + `(MemoryAccess/getIntAtOffset ~segment ~offset)) + ([segment offset byte-order] + `(MemoryAccess/getIntAtOffset ~segment ~offset ~byte-order)))} + ([^MemorySegment segment] + (MemoryAccess/getInt segment)) + ([^MemorySegment segment ^long offset] + (MemoryAccess/getIntAtOffset segment offset)) + ([^MemorySegment segment ^long offset ^ByteOrder byte-order] + (MemoryAccess/getIntAtOffset segment offset byte-order))) + +(defn read-long + "Reads a [[long]] from the `segment`, at an optional `offset`. + + If `byte-order` is not provided, it defaults to [[native-endian]]." + {:inline + (fn read-long-inline + ([segment] + `(MemoryAccess/getLong ~segment)) + ([segment offset] + `(MemoryAccess/getLongAtOffset ~segment ~offset)) + ([segment offset byte-order] + `(MemoryAccess/getLongAtOffset ~segment ~offset ~byte-order)))} + (^long [^MemorySegment segment] + (MemoryAccess/getLong segment)) + (^long [^MemorySegment segment ^long offset] + (MemoryAccess/getLongAtOffset segment offset)) + (^long [^MemorySegment segment ^long offset ^ByteOrder byte-order] + (MemoryAccess/getLongAtOffset segment offset byte-order))) + +(defn read-char + "Reads a [[char]] from the `segment`, at an optional `offset`." + {:inline + (fn read-char-inline + ([segment] + `(char (Byte/toUnsignedInt (MemoryAccess/getByte ~segment)))) + ([segment offset] + `(char (Byte/toUnsignedInt (MemoryAccess/getByteAtOffset ~segment ~offset)))))} + ([^MemorySegment segment] + (char (Byte/toUnsignedInt (MemoryAccess/getByte segment)))) + ([^MemorySegment segment ^long offset] + (char (Byte/toUnsignedInt (MemoryAccess/getByteAtOffset segment offset))))) + +(defn read-float + "Reads a [[float]] from the `segment`, at an optional `offset`. + + If `byte-order` is not provided, it defaults to [[native-endian]]." + {:inline + (fn read-float-inline + ([segment] + `(MemoryAccess/getFloat ~segment)) + ([segment offset] + `(MemoryAccess/getFloatAtOffset ~segment ~offset)) + ([segment offset byte-order] + `(MemoryAccess/getFloatAtOffset ~segment ~offset ~byte-order)))} + ([^MemorySegment segment] + (MemoryAccess/getFloat segment)) + ([^MemorySegment segment ^long offset] + (MemoryAccess/getFloatAtOffset segment offset)) + ([^MemorySegment segment ^long offset ^ByteOrder byte-order] + (MemoryAccess/getFloatAtOffset segment offset byte-order))) + +(defn read-double + "Reads a [[double]] from the `segment`, at an optional `offset`. + + If `byte-order` is not provided, it defaults to [[native-endian]]." + {:inline + (fn read-double-inline + ([segment] + `(MemoryAccess/getDouble ~segment)) + ([segment offset] + `(MemoryAccess/getDoubleAtOffset ~segment ~offset)) + ([segment offset byte-order] + `(MemoryAccess/getDoubleAtOffset ~segment ~offset ~byte-order)))} + (^double [^MemorySegment segment] + (MemoryAccess/getDouble segment)) + (^double [^MemorySegment segment ^long offset] + (MemoryAccess/getDoubleAtOffset segment offset)) + (^double [^MemorySegment segment ^long offset ^ByteOrder byte-order] + (MemoryAccess/getDoubleAtOffset segment offset byte-order))) + +(defn write-byte + "Writes a [[byte]] to the `segment`, at an optional `offset`." + {:inline + (fn write-byte-inline + ([segment value] + `(MemoryAccess/setByte ~segment ~value)) + ([segment offset value] + `(MemoryAccess/setByteAtOffset ~segment ~offset ~value)))} + ([^MemorySegment segment value] + (MemoryAccess/setByte segment ^byte value)) + ([^MemorySegment segment ^long offset value] + (MemoryAccess/setByteAtOffset segment offset ^byte value))) + +(defn write-short + "Writes a [[short]] to the `segment`, at an optional `offset`. + + If `byte-order` is not provided, it defaults to [[native-endian]]." + {:inline + (fn write-short-inline + ([segment value] + `(MemoryAccess/setShort ~segment ~value)) + ([segment offset value] + `(MemoryAccess/setShortAtOffset ~segment ~offset ~value)) + ([segment offset byte-order value] + `(MemoryAccess/setShortAtOffset ~segment ~offset ~byte-order ~value)))} + ([^MemorySegment segment value] + (MemoryAccess/setShort segment ^short value)) + ([^MemorySegment segment ^long offset value] + (MemoryAccess/setShortAtOffset segment offset ^short value)) + ([^MemorySegment segment ^long offset ^ByteOrder byte-order value] + (MemoryAccess/setShortAtOffset segment offset byte-order ^short value))) + +(defn write-int + "Writes a [[int]] to the `segment`, at an optional `offset`. + + If `byte-order` is not provided, it defaults to [[native-endian]]." + {:inline + (fn write-int-inline + ([segment value] + `(MemoryAccess/setInt ~segment ~value)) + ([segment offset value] + `(MemoryAccess/setIntAtOffset ~segment ~offset ~value)) + ([segment offset byte-order value] + `(MemoryAccess/setIntAtOffset ~segment ~offset ~byte-order ~value)))} + ([^MemorySegment segment value] + (MemoryAccess/setInt segment ^int value)) + ([^MemorySegment segment ^long offset value] + (MemoryAccess/setIntAtOffset segment offset ^int value)) + ([^MemorySegment segment ^long offset ^ByteOrder byte-order value] + (MemoryAccess/setIntAtOffset segment offset byte-order ^int value))) + +(defn write-long + "Writes a [[long]] to the `segment`, at an optional `offset`. + + If `byte-order` is not provided, it defaults to [[native-endian]]." + {:inline + (fn write-long-inline + ([segment value] + `(MemoryAccess/setLong ~segment ~value)) + ([segment offset value] + `(MemoryAccess/setLongAtOffset ~segment ~offset ~value)) + ([segment offset byte-order value] + `(MemoryAccess/setLongAtOffset ~segment ~offset ~byte-order ~value)))} + (^long [^MemorySegment segment ^long value] + (MemoryAccess/setLong segment value)) + (^long [^MemorySegment segment ^long offset ^long value] + (MemoryAccess/setLongAtOffset segment offset value)) + (^long [^MemorySegment segment ^long offset ^ByteOrder byte-order ^long value] + (MemoryAccess/setLongAtOffset segment offset byte-order value))) + +(defn write-char + "Writes a [[char]] to the `segment`, at an optional `offset`." + {:inline + (fn write-char-inline + ([segment value] + `(MemoryAccess/setByte ~segment (unchecked-byte (unchecked-int ~value)))) + ([segment offset value] + `(MemoryAccess/setByteAtOffset ~segment ~offset (unchecked-byte (unchecked-int ~value)))))} + ([^MemorySegment segment value] + (MemoryAccess/setByte + segment + ;; HACK(Joshua): The Clojure runtime doesn't have an unchecked-byte cast for + ;; characters, so this double cast is necessary unless I emit + ;; my own bytecode with insn. + (unchecked-byte (unchecked-int ^char value)))) + ([^MemorySegment segment ^long offset value] + (MemoryAccess/setByteAtOffset segment offset (unchecked-byte (unchecked-int ^char value))))) + +(defn write-float + "Writes a [[float]] to the `segment`, at an optional `offset`. + + If `byte-order` is not provided, it defaults to [[native-endian]]." + {:inline + (fn write-float-inline + ([segment value] + `(MemoryAccess/setFloat ~segment ~value)) + ([segment offset value] + `(MemoryAccess/setFloatAtOffset ~segment ~offset ~value)) + ([segment offset byte-order value] + `(MemoryAccess/setFloatAtOffset ~segment ~offset ~byte-order ~value)))} + ([^MemorySegment segment value] + (MemoryAccess/setFloat segment ^float value)) + ([^MemorySegment segment ^long offset value] + (MemoryAccess/setFloatAtOffset segment offset ^float value)) + ([^MemorySegment segment ^long offset ^ByteOrder byte-order value] + (MemoryAccess/setFloatAtOffset segment offset byte-order ^float value))) + +(defn write-double + "Writes a [[double]] to the `segment`, at an optional `offset`. + + If `byte-order` is not provided, it defaults to [[native-endian]]." + {:inline + (fn write-double-inline + ([segment value] + `(MemoryAccess/setDouble ~segment ~value)) + ([segment offset value] + `(MemoryAccess/setDoubleAtOffset ~segment ~offset ~value)) + ([segment offset byte-order value] + `(MemoryAccess/setDoubleAtOffset ~segment ~offset ~byte-order ~value)))} + (^double [^MemorySegment segment ^double value] + (MemoryAccess/setDouble segment value)) + (^double [^MemorySegment segment ^long offset ^double value] + (MemoryAccess/setDoubleAtOffset segment offset value)) + (^double [^MemorySegment segment ^long offset ^ByteOrder byte-order ^double value] + (MemoryAccess/setDoubleAtOffset segment offset byte-order value))) + (defn- type-dispatch "Gets a type dispatch value from a (potentially composite) type." [type] From ded50d7a29037c9509806c41051d4b012a93562d Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Tue, 18 Jan 2022 13:48:44 -0600 Subject: [PATCH 11/33] Update (de)serialization multimethods to use new prim functions --- src/clj/coffi/mem.clj | 80 ++++++++++++++++++++++++++++--------------- 1 file changed, 52 insertions(+), 28 deletions(-) diff --git a/src/clj/coffi/mem.clj b/src/clj/coffi/mem.clj index 2e2cec0..79306fa 100644 --- a/src/clj/coffi/mem.clj +++ b/src/clj/coffi/mem.clj @@ -765,35 +765,47 @@ (defmethod serialize-into ::byte [obj _type segment _scope] - (MemoryAccess/setByte segment (byte obj))) + (write-byte segment (byte obj))) (defmethod serialize-into ::short - [obj _type segment _scope] - (MemoryAccess/setShort segment (short obj))) + [obj type segment _scope] + (if (sequential? type) + (write-short segment 0 (second type) (short obj)) + (write-short segment (short obj)))) (defmethod serialize-into ::int - [obj _type segment _scope] - (MemoryAccess/setInt segment (int obj))) + [obj type segment _scope] + (if (sequential? type) + (write-int segment 0 (second type) (int obj)) + (write-int segment (int obj)))) (defmethod serialize-into ::long - [obj _type segment _scope] - (MemoryAccess/setLong segment (long obj))) + [obj type segment _scope] + (if (sequential? type) + (write-long segment 0 (second type) (long obj)) + (write-long segment (long obj)))) (defmethod serialize-into ::long-long - [obj _type segment _scope] - (MemoryAccess/setLong segment (long obj))) + [obj type segment _scope] + (if (sequential? type) + (write-long segment 0 (second type) (long obj)) + (write-long segment (long obj)))) (defmethod serialize-into ::char [obj _type segment _scope] - (MemoryAccess/setChar segment (char obj))) + (write-char segment (char obj))) (defmethod serialize-into ::float - [obj _type segment _scope] - (MemoryAccess/setFloat segment (float obj))) + [obj type segment _scope] + (if (sequential? type) + (write-float segment 0 (second type) (float obj)) + (write-float segment (float obj)))) (defmethod serialize-into ::double - [obj _type segment _scope] - (MemoryAccess/setDouble segment (double obj))) + [obj type segment _scope] + (if (sequential? type) + (write-double segment 0 (second type) (double obj)) + (write-double segment (double obj)))) (defmethod serialize-into ::pointer [obj type segment scope] @@ -844,35 +856,47 @@ (defmethod deserialize-from ::byte [segment _type] - (MemoryAccess/getByte segment)) + (read-byte segment)) (defmethod deserialize-from ::short - [segment _type] - (MemoryAccess/getShort segment)) + [segment type] + (if (sequential? type) + (read-short segment 0 (second type)) + (read-short segment))) (defmethod deserialize-from ::int - [segment _type] - (MemoryAccess/getInt segment)) + [segment type] + (if (sequential? type) + (read-int segment 0 (second type)) + (read-int segment))) (defmethod deserialize-from ::long - [segment _type] - (MemoryAccess/getLong segment)) + [segment type] + (if (sequential? type) + (read-long segment 0 (second type)) + (read-long segment))) (defmethod deserialize-from ::long-long - [segment _type] - (MemoryAccess/getLong segment)) + [segment type] + (if (sequential? type) + (read-long segment 0 (second type)) + (read-long segment))) (defmethod deserialize-from ::char [segment _type] - (char (Byte/toUnsignedInt (MemoryAccess/getByte segment)))) + (read-char segment)) (defmethod deserialize-from ::float - [segment _type] - (MemoryAccess/getFloat segment)) + [segment type] + (if (sequential? type) + (read-float segment 0 (second type)) + (read-float segment))) (defmethod deserialize-from ::double - [segment _type] - (MemoryAccess/getDouble segment)) + [segment type] + (if (sequential? type) + (read-double segment 0 (second type)) + (read-double segment))) (defmethod deserialize-from ::pointer [segment type] From 634f37114428c130267a8ed772ae8a59f33ee8c2 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Tue, 18 Jan 2022 14:00:00 -0600 Subject: [PATCH 12/33] Throw an exception on testing invalid type objects --- src/clj/coffi/mem.clj | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/clj/coffi/mem.clj b/src/clj/coffi/mem.clj index 79306fa..42394ad 100644 --- a/src/clj/coffi/mem.clj +++ b/src/clj/coffi/mem.clj @@ -515,7 +515,8 @@ [type] (cond (qualified-keyword? type) type - (sequential? type) (keyword (first type)))) + (sequential? type) (keyword (first type)) + :else (throw (ex-info "Invalid type object" {:type type})))) (def primitive? "A set of all primitive types." From 6ba905e6bf19aec08aed66d9b198aad99aabb671 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Tue, 18 Jan 2022 14:00:13 -0600 Subject: [PATCH 13/33] Update primitive? to be a function --- src/clj/coffi/mem.clj | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/clj/coffi/mem.clj b/src/clj/coffi/mem.clj index 42394ad..72903e1 100644 --- a/src/clj/coffi/mem.clj +++ b/src/clj/coffi/mem.clj @@ -518,11 +518,16 @@ (sequential? type) (keyword (first type)) :else (throw (ex-info "Invalid type object" {:type type})))) -(def primitive? +(def primitive-types "A set of all primitive types." #{::byte ::short ::int ::long ::long-long ::char ::float ::double ::pointer}) +(defn primitive? + "A predicate to determine if a given type is primitive." + [type] + (contains? primitive-types (type-dispatch type))) + (defmulti primitive-type "Gets the primitive type that is used to pass as an argument for the `type`. From 104db6b8fdf8cddf1a8fe9c37db073c043bb508f Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Tue, 18 Jan 2022 14:15:08 -0600 Subject: [PATCH 14/33] Add type hints to layout constants --- src/clj/coffi/mem.clj | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/src/clj/coffi/mem.clj b/src/clj/coffi/mem.clj index 72903e1..5ac5b6f 100644 --- a/src/clj/coffi/mem.clj +++ b/src/clj/coffi/mem.clj @@ -31,7 +31,8 @@ MemorySegment ResourceScope ResourceScope$Handle - SegmentAllocator))) + SegmentAllocator + ValueLayout))) (defn stack-scope "Constructs a new scope for use only in this thread. @@ -209,57 +210,57 @@ (map #(slice segment (* % size) size) (range num-segments)))) -(def big-endian +(def ^ByteOrder big-endian "The big-endian [[ByteOrder]]. See [[little-endian]], [[native-endian]]." ByteOrder/BIG_ENDIAN) -(def little-endian +(def ^ByteOrder little-endian "The little-endian [[ByteOrder]]. See [[big-endian]], [[native-endian]]" ByteOrder/LITTLE_ENDIAN) -(def native-endian +(def ^ByteOrder native-endian "The [[ByteOrder]] for the native endianness of the current hardware. See [[big-endian]], [[little-endian]]." (ByteOrder/nativeOrder)) -(def byte-layout +(def ^ValueLayout byte-layout "The [[MemoryLayout]] for a byte in [[native-endian]] [[ByteOrder]]." CLinker/C_CHAR) -(def short-layout +(def ^ValueLayout short-layout "The [[MemoryLayout]] for a c-sized short in [[native-endian]] [[ByteOrder]]." CLinker/C_SHORT) -(def int-layout +(def ^ValueLayout int-layout "The [[MemoryLayout]] for a c-sized int in [[native-endian]] [[ByteOrder]]." CLinker/C_INT) -(def long-layout +(def ^ValueLayout long-layout "The [[MemoryLayout]] for a c-sized long in [[native-endian]] [[ByteOrder]]." CLinker/C_LONG) -(def long-long-layout +(def ^ValueLayout long-long-layout "The [[MemoryLayout]] for a c-sized long-long in [[native-endian]] [[ByteOrder]]." CLinker/C_LONG_LONG) -(def char-layout +(def ^ValueLayout char-layout "The [[MemoryLayout]] for a c-sized char in [[native-endian]] [[ByteOrder]]." CLinker/C_CHAR) -(def float-layout +(def ^ValueLayout float-layout "The [[MemoryLayout]] for a c-sized float in [[native-endian]] [[ByteOrder]]." CLinker/C_FLOAT) -(def double-layout +(def ^ValueLayout double-layout "The [[MemoryLayout]] for a c-sized double in [[native-endian]] [[ByteOrder]]." CLinker/C_DOUBLE) -(def pointer-layout +(def ^ValueLayout pointer-layout "The [[MemoryLayout]] for a native pointer in [[native-endian]] [[ByteOrder]]." CLinker/C_POINTER) From 7c62207613af099d75e6f79b9f71468b3b36fe9f Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Tue, 18 Jan 2022 14:15:18 -0600 Subject: [PATCH 15/33] Allow non-native byte orders on primitives --- src/clj/coffi/mem.clj | 36 ++++++++++++++++++++++++------------ 1 file changed, 24 insertions(+), 12 deletions(-) diff --git a/src/clj/coffi/mem.clj b/src/clj/coffi/mem.clj index 5ac5b6f..868d41a 100644 --- a/src/clj/coffi/mem.clj +++ b/src/clj/coffi/mem.clj @@ -604,32 +604,44 @@ byte-layout) (defmethod c-layout ::short - [_type] - short-layout) + [type] + (if (sequential? type) + (.withOrder short-layout (second type)) + short-layout)) (defmethod c-layout ::int - [_type] - int-layout) + [type] + (if (sequential? type) + (.withOrder int-layout (second type)) + int-layout)) (defmethod c-layout ::long - [_type] - long-layout) + [type] + (if (sequential? type) + (.withOrder long-layout (second type)) + long-layout)) (defmethod c-layout ::long-long - [_type] - long-long-layout) + [type] + (if (sequential? type) + (.withOrder long-long-layout (second type)) + long-long-layout)) (defmethod c-layout ::char [_type] char-layout) (defmethod c-layout ::float - [_type] - float-layout) + [type] + (if (sequential? type) + (.withOrder float-layout (second type)) + float-layout)) (defmethod c-layout ::double - [_type] - double-layout) + [type] + (if (sequential? type) + (.withOrder double-layout (second type)) + double-layout)) (defmethod c-layout ::pointer [_type] From d6cfa115e120cbaf9f763ae57b4e7a7b738cbec1 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Tue, 18 Jan 2022 14:24:10 -0600 Subject: [PATCH 16/33] Update changelog --- CHANGELOG.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9994575..f09ed29 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,15 @@ 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 +- Support for non-native byte orders of primitive types +- Functions for reading and writing primitive types (e.g. `coffi.mem/read-float`, `coffi.mem/write-long`, etc.) +- Layout objects may now be passed to `coffi.mem/size-of` and `coffi.mem/align-of` +- Constants for native-order primitive layouts +- Constants for byte orders + +### Changed +- The `coffi.mem/primitive?` predicate is now actually a function instead of a set ## [0.3.298] - 2022-01-10 ### Added From 5c560e684db43ad6837f654b95c2da2b8e5708d3 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Tue, 18 Jan 2022 15:39:49 -0600 Subject: [PATCH 17/33] Add convenience functions for reading and writing addresses --- src/clj/coffi/mem.clj | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/src/clj/coffi/mem.clj b/src/clj/coffi/mem.clj index 868d41a..53166d9 100644 --- a/src/clj/coffi/mem.clj +++ b/src/clj/coffi/mem.clj @@ -385,6 +385,19 @@ (^double [^MemorySegment segment ^long offset ^ByteOrder byte-order] (MemoryAccess/getDoubleAtOffset segment offset byte-order))) +(defn read-address + "Reads a [[MemoryAddress]] from the `segment`, at an optional `offset`." + {:inline + (fn read-address-inline + ([segment] + `(MemoryAccess/getAddress ~segment)) + ([segment offset] + `(MemoryAccess/getAddressAtOffset ~segment ~offset)))} + (^MemoryAddress [^MemorySegment segment] + (MemoryAccess/getAddress segment)) + (^MemoryAddress [^MemorySegment segment ^long offset] + (MemoryAccess/getAddressAtOffset segment offset))) + (defn write-byte "Writes a [[byte]] to the `segment`, at an optional `offset`." {:inline @@ -511,6 +524,19 @@ (^double [^MemorySegment segment ^long offset ^ByteOrder byte-order ^double value] (MemoryAccess/setDoubleAtOffset segment offset byte-order value))) +(defn write-address + "Writes a [[MemoryAddress]] to the `segment`, at an optional `offset`." + {:inline + (fn write-address-inline + ([segment value] + `(MemoryAccess/setAddress ~segment ~value)) + ([segment offset value] + `(MemoryAccess/setAddressAtOffset ~segment ~offset ~value)))} + (^MemoryAddress [^MemorySegment segment ^MemoryAddress value] + (MemoryAccess/setAddress segment value)) + (^MemoryAddress [^MemorySegment segment ^long offset ^MemoryAddress value] + (MemoryAccess/setAddressAtOffset segment offset value))) + (defn- type-dispatch "Gets a type dispatch value from a (potentially composite) type." [type] From 447117e092e9208f60facf0aa0de1f92b9f34b91 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Tue, 18 Jan 2022 15:40:31 -0600 Subject: [PATCH 18/33] Add caveat in unwrapped native handles about defcfn with primitives --- README.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index fa1a6ee..7ff40d2 100644 --- a/README.md +++ b/README.md @@ -534,12 +534,14 @@ to the user to call `deserialize-from` on that segment with the appropriate type. ### Unwrapped Native Handles -Sometimes the overhead brought by the automatic serialization and -deserialization from the methods explained so far is too much. In cases like -these, unwrapped native handles are desirable. +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 provided to create -these raw handles. +The functions `make-downcall` and `make-varargs-factory` are also provided to +create raw function handles. ```clojure (def raw-strlen (ffi/make-downcall "strlen" [::mem/c-string] ::mem/long)) @@ -547,7 +549,7 @@ these raw handles. ;; => 5 ``` -In these cases, the argument types are expected to exactly match the types +With raw handles, the argument types are expected to exactly match the types expected by the native function. For primitive types, those are primitives. For addresses, that is `MemoryAddress`, and for composite types like structs and unions, that is `MemorySegment`. Both `MemoryAddress` and `MemorySegment` come @@ -569,6 +571,13 @@ 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. + ### 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 From 0ad6308846ae7d72dd761e1ba8890ba9c96839b9 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Tue, 18 Jan 2022 15:40:51 -0600 Subject: [PATCH 19/33] Add section to readme about manual deserialization --- README.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/README.md b/README.md index 7ff40d2..d87a0f9 100644 --- a/README.md +++ b/README.md @@ -578,6 +578,47 @@ 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](#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 floats, the +following code might be used. + +``` clojure +(let [function-handle (ffi/make-downcall "returns_float_array" [::mem/pointer] ::mem/int) + release-floats (ffi/make-downcall "releases_float_array" [::mem/pointer] ::mem/void) + pointer-size (mem/size-of ::mem/pointer) + float-size (mem/size-of ::mem/float)] + (defn returns-float-array + [] + (with-open [scope (mem/stack-scope)] + (let [out-floats (mem/alloc pointer-size scope) + num-floats (function-handle (mem/address-of out-floats)) + floats-addr (mem/read-address out-floats) + floats-slice (mem/slice-global floats-addr (unchecked-multiply-int float-size num-floats)) + ret (loop [floats (transient []) + index 0] + (if (>= index num-floats) + (persistent! floats) + (recur (conj! floats (mem/read-float floats-slice (unchecked-multiply-int index float-size))) + (inc index))))] + (release-floats floats-addr) + ret)))) +``` + +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. + ### 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 From 95ff261189fb648d99e46f61b78cf90e9e2985f0 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Tue, 18 Jan 2022 15:49:29 -0600 Subject: [PATCH 20/33] Use big-endian stuff as an example --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index d87a0f9..8ce2187 100644 --- a/README.md +++ b/README.md @@ -589,8 +589,8 @@ Handles](#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 floats, the -following code might be used. +As an example, when wrapping a function that returns an array of big-endian +floats, the following code might be used. ``` clojure (let [function-handle (ffi/make-downcall "returns_float_array" [::mem/pointer] ::mem/int) @@ -608,7 +608,9 @@ following code might be used. index 0] (if (>= index num-floats) (persistent! floats) - (recur (conj! floats (mem/read-float floats-slice (unchecked-multiply-int index float-size))) + (recur (conj! floats (mem/read-float floats-slice + (unchecked-multiply-int index float-size) + mem/big-endian)) (inc index))))] (release-floats floats-addr) ret)))) From 6c999861ade36cc1602208184dcd57d97cbadf5c Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Tue, 18 Jan 2022 15:50:36 -0600 Subject: [PATCH 21/33] Use unchecked-inc-int for performance example --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8ce2187..85a3490 100644 --- a/README.md +++ b/README.md @@ -611,7 +611,7 @@ floats, the following code might be used. (recur (conj! floats (mem/read-float floats-slice (unchecked-multiply-int index float-size) mem/big-endian)) - (inc index))))] + (unchecked-inc-int index))))] (release-floats floats-addr) ret)))) ``` From 3f3910c12372650906d9b811d863dc800507c9fc Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Tue, 18 Jan 2022 15:56:43 -0600 Subject: [PATCH 22/33] Update copyright date --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 85a3490..bde27ea 100644 --- a/README.md +++ b/README.md @@ -1106,6 +1106,6 @@ September 2023. ## License -Copyright © 2021 Joshua Suskalo +Copyright © 2022 Joshua Suskalo Distributed under the Eclipse Public License version 1.0. From 7ec2cd157597a4f47cf87335193c56e011f34a7f Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Wed, 19 Jan 2022 10:56:46 -0600 Subject: [PATCH 23/33] Add size and alignment constants for primitives --- src/clj/coffi/mem.clj | 56 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/src/clj/coffi/mem.clj b/src/clj/coffi/mem.clj index 53166d9..21db3d4 100644 --- a/src/clj/coffi/mem.clj +++ b/src/clj/coffi/mem.clj @@ -264,6 +264,62 @@ "The [[MemoryLayout]] for a native pointer in [[native-endian]] [[ByteOrder]]." CLinker/C_POINTER) +(def short-size + "The size in bytes of a c-sized short." + (.byteSize short-layout)) + +(def int-size + "The size in bytes of a c-sized int." + (.byteSize int-layout)) + +(def long-size + "The size in bytes of a c-sized long." + (.byteSize long-layout)) + +(def long-long-size + "The size in bytes of a c-sized long long." + (.byteSize long-long-layout)) + +(def float-size + "The size in bytes of a c-sized float." + (.byteSize float-layout)) + +(def double-size + "The size in bytes of a c-sized double." + (.byteSize double-layout)) + +(def pointer-size + "The size in bytes of a c-sized pointer." + (.byteSize pointer-layout)) + +(def short-alignment + "The alignment in bytes of a c-sized short." + (.byteAlignment short-layout)) + +(def int-alignment + "The alignment in bytes of a c-sized int." + (.byteAlignment int-layout)) + +(def long-alignment + "The alignment in bytes of a c-sized long." + (.byteAlignment long-layout)) + +(def long-long-alignment + "The alignment in bytes of a c-sized long long." + (.byteAlignment long-long-layout)) + +(def float-alignment + "The alignment in bytes of a c-sized float." + (.byteAlignment float-layout)) + +(def double-alignment + "The alignment in bytes of a c-sized double." + (.byteAlignment double-layout)) + +(def pointer-alignment + "The alignment in bytes of a c-sized pointer." + (.byteAlignment pointer-layout)) + (defn read-byte "Reads a [[byte]] from the `segment`, at an optional `offset`." {:inline From 5ae32161b380578bed7d97f4d97bc3f66c5ca42b Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Wed, 19 Jan 2022 10:57:01 -0600 Subject: [PATCH 24/33] Update readme example with manual serdes for style --- README.md | 44 +++++++++++++++++++++++--------------------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index bde27ea..80aa22f 100644 --- a/README.md +++ b/README.md @@ -593,27 +593,29 @@ As an example, when wrapping a function that returns an array of big-endian floats, the following code might be used. ``` clojure -(let [function-handle (ffi/make-downcall "returns_float_array" [::mem/pointer] ::mem/int) - release-floats (ffi/make-downcall "releases_float_array" [::mem/pointer] ::mem/void) - pointer-size (mem/size-of ::mem/pointer) - float-size (mem/size-of ::mem/float)] - (defn returns-float-array - [] - (with-open [scope (mem/stack-scope)] - (let [out-floats (mem/alloc pointer-size scope) - num-floats (function-handle (mem/address-of out-floats)) - floats-addr (mem/read-address out-floats) - floats-slice (mem/slice-global floats-addr (unchecked-multiply-int float-size num-floats)) - ret (loop [floats (transient []) - index 0] - (if (>= index num-floats) - (persistent! floats) - (recur (conj! floats (mem/read-float floats-slice - (unchecked-multiply-int index float-size) - mem/big-endian)) - (unchecked-inc-int index))))] - (release-floats floats-addr) - ret)))) +(def ^:private returns-float-array* (ffi/make-downcall "returns_float_array" [::mem/pointer] ::mem/int)) +(def ^:private release-floats* (ffi/make-downcall "releases_float_array" [::mem/pointer] ::mem/void)) + +(defn returns-float-array + [] + (with-open [scope (mem/stack-scope)] + (let [out-floats (mem/alloc mem/pointer-size scope) + num-floats (function-handle (mem/address-of out-floats)) + floats-addr (mem/read-address out-floats) + floats-slice (mem/slice-global floats-addr (unchecked-multiply-int mem/float-size num-floats))] + ;; Using a try/finally to perform an operation when the stack frame exits, + ;; 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 From 3e63230c1f44cd6f260b15ed52635f0e22753d27 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Wed, 19 Jan 2022 11:00:57 -0600 Subject: [PATCH 25/33] type hint size and alignment constants --- src/clj/coffi/mem.clj | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/src/clj/coffi/mem.clj b/src/clj/coffi/mem.clj index 21db3d4..492f786 100644 --- a/src/clj/coffi/mem.clj +++ b/src/clj/coffi/mem.clj @@ -264,59 +264,59 @@ "The [[MemoryLayout]] for a native pointer in [[native-endian]] [[ByteOrder]]." CLinker/C_POINTER) -(def short-size +(def ^long short-size "The size in bytes of a c-sized short." (.byteSize short-layout)) -(def int-size +(def ^long int-size "The size in bytes of a c-sized int." (.byteSize int-layout)) -(def long-size +(def ^long long-size "The size in bytes of a c-sized long." (.byteSize long-layout)) -(def long-long-size +(def ^long long-long-size "The size in bytes of a c-sized long long." (.byteSize long-long-layout)) -(def float-size +(def ^long float-size "The size in bytes of a c-sized float." (.byteSize float-layout)) -(def double-size +(def ^long double-size "The size in bytes of a c-sized double." (.byteSize double-layout)) -(def pointer-size +(def ^long pointer-size "The size in bytes of a c-sized pointer." (.byteSize pointer-layout)) -(def short-alignment +(def ^long short-alignment "The alignment in bytes of a c-sized short." (.byteAlignment short-layout)) -(def int-alignment +(def ^long int-alignment "The alignment in bytes of a c-sized int." (.byteAlignment int-layout)) -(def long-alignment +(def ^long long-alignment "The alignment in bytes of a c-sized long." (.byteAlignment long-layout)) -(def long-long-alignment +(def ^long long-long-alignment "The alignment in bytes of a c-sized long long." (.byteAlignment long-long-layout)) -(def float-alignment +(def ^long float-alignment "The alignment in bytes of a c-sized float." (.byteAlignment float-layout)) -(def double-alignment +(def ^long double-alignment "The alignment in bytes of a c-sized double." (.byteAlignment double-layout)) -(def pointer-alignment +(def ^long pointer-alignment "The alignment in bytes of a c-sized pointer." (.byteAlignment pointer-layout)) From 48a2685f363855e87d9e6689648885a825cf8c55 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Wed, 19 Jan 2022 11:01:52 -0600 Subject: [PATCH 26/33] Update changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index f09ed29..2f3551f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ All notable changes to this project will be documented in this file. This change ## [Unreleased] ### Added +- Constants for size and alignment of primitive types - Support for non-native byte orders of primitive types - Functions for reading and writing primitive types (e.g. `coffi.mem/read-float`, `coffi.mem/write-long`, etc.) - Layout objects may now be passed to `coffi.mem/size-of` and `coffi.mem/align-of` From f7e50630cc06f39b32a521f9eb4e6163f5e3c935 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Wed, 19 Jan 2022 11:19:12 -0600 Subject: [PATCH 27/33] Fix bug where non-native endian values were needlessly serialized --- src/clj/coffi/ffi.clj | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/clj/coffi/ffi.clj b/src/clj/coffi/ffi.clj index 3862ce4..dd29161 100644 --- a/src/clj/coffi/ffi.clj +++ b/src/clj/coffi/ffi.clj @@ -288,8 +288,8 @@ `(mem/serialize ~sym ~type-sym ~scope) (and (mem/primitive? type) - (not (#{::mem/pointer} type))) - (list (primitive-cast-sym type) sym) + (not (#{::mem/pointer} (mem/primitive-type type)))) + (list (primitive-cast-sym (mem/primitive-type type)) sym) (#{::mem/pointer} type) nil From 90c125fb627f45433802e37b3ff6f17774fd32a9 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Wed, 19 Jan 2022 11:34:57 -0600 Subject: [PATCH 28/33] Fix bug where pointer types were not deserialized in wrapper --- src/clj/coffi/ffi.clj | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/clj/coffi/ffi.clj b/src/clj/coffi/ffi.clj index dd29161..061ff3b 100644 --- a/src/clj/coffi/ffi.clj +++ b/src/clj/coffi/ffi.clj @@ -347,8 +347,9 @@ `(mem/deserialize-from ~expr ~ret-type-sym)) deserialize-ret (fn [expr] (cond - (or (mem/primitive? ret-type) - (#{::mem/void} ret-type)) + (and (or (mem/primitive? ret-type) + (#{::mem/void} ret-type)) + (not (#{::mem/pointer} (mem/primitive-type ret-type)))) expr (mem/primitive-type ret-type) From ab9179b1260faec1b290347be8e6e7c7152639d4 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Sun, 23 Jan 2022 20:17:12 -0600 Subject: [PATCH 29/33] Remove unneeded line in changelog --- CHANGELOG.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2f3551f..675da29 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,7 +24,6 @@ All notable changes to this project will be documented in this file. This change ### Fixed - Non-primitive arguments on upcalls would generate invalid bytecode with `nil` instructions - ## [0.2.259] - 2021-10-16 ### Fixed - Long and double arguments to upcalls failed to compile in some cases From 09b819528d3447576f909dd9b4e12d15a3f99564 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Sun, 23 Jan 2022 20:17:20 -0600 Subject: [PATCH 30/33] Bump minor version of project --- build.clj | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build.clj b/build.clj index d4f2ea4..c0df6d7 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.3.%s" (b/git-count-revs nil))) +(def version (format "0.4.%s" (b/git-count-revs nil))) (def resource-dirs ["resources/"]) From 4d9bdfd7151c1d41250738795632068b38078c41 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Sun, 23 Jan 2022 20:18:58 -0600 Subject: [PATCH 31/33] Update changelog for release --- CHANGELOG.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 675da29..4a46187 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.4.341] - 2022-01-23 ### Added - Constants for size and alignment of primitive types - Support for non-native byte orders of primitive types @@ -91,7 +91,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.3.298...HEAD +[0.4.341]: https://github.com/IGJoshua/coffi/compare/v0.3.298...v0.4.341 [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 From 2477483910ac4f6b987abd89fa93dbe75abf72dc Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Sun, 23 Jan 2022 20:20:11 -0600 Subject: [PATCH 32/33] Update codox documentation --- deps.edn | 2 +- docs/coffi.ffi.html | 18 ++++++------- docs/coffi.layout.html | 4 +-- docs/coffi.mem.html | 60 ++++++++++++++++++++++++++---------------- docs/index.html | 2 +- 5 files changed, 50 insertions(+), 36 deletions(-) diff --git a/deps.edn b/deps.edn index c3c604b..be56f5b 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.3.298" + :version "v0.4.341" :description "A Foreign Function Interface in Clojure for JDK 17." :source-paths ["src/clj"] :output-path "docs" diff --git a/docs/coffi.ffi.html b/docs/coffi.ffi.html index 4301514..2d0f7c3 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.layout.html b/docs/coffi.layout.html index 5daf5ef..302f3c0 100644 --- a/docs/coffi.layout.html +++ b/docs/coffi.layout.html @@ -1,4 +1,4 @@ -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 +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 c34767b..08465a6 100644 --- a/docs/coffi.mem.html +++ b/docs/coffi.mem.html @@ -1,37 +1,51 @@ -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

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.

+

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

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

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

char-layout

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

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.

+

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

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

(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

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-long-alignment

The alignment in bytes of a c-sized long long.

view source

long-long-layout

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

view source

long-long-size

The size in bytes of a c-sized long long.

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?

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

(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

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

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
\ No newline at end of file diff --git a/docs/index.html b/docs/index.html index 7381afb..dcd979b 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1,3 +1,3 @@ -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 +coffi v0.4.341

Project

Namespaces

coffi v0.4.341

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 From 3dd948425ae1b09645b493855065d46664c0bfe9 Mon Sep 17 00:00:00 2001 From: Joshua Suskalo Date: Sun, 23 Jan 2022 20:22:20 -0600 Subject: [PATCH 33/33] Update version in the readme --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 80aa22f..9a94b2d 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.3.298"} -io.github.IGJoshua/coffi {:git/tag "v0.3.298" :git/sha "1bbb8a7"} +org.suskalo/coffi {:mvn/version "0.4.341"} +io.github.IGJoshua/coffi {:git/tag "v0.4.341" :git/sha "09b8195"} ``` If you use this library as a git dependency, you will need to prepare the