Finish updating README to not refer to sessions

This commit is contained in:
Joshua Suskalo 2024-10-01 13:54:23 -04:00
parent 928b0f42c8
commit 7970c7e221
No known key found for this signature in database
GPG key ID: 9B6BA586EFF1B9F0

View file

@ -638,14 +638,18 @@ As an example, when wrapping a function that returns an array of big-endian
floats, the following code might be used. floats, the following code might be used.
``` clojure ``` clojure
;; int returns_float_array(float **arr)
(def ^:private returns-float-array* (ffi/make-downcall "returns_float_array" [::mem/pointer] ::mem/int)) (def ^:private returns-float-array* (ffi/make-downcall "returns_float_array" [::mem/pointer] ::mem/int))
;; void releases_float_array(float *arr)
(def ^:private release-floats* (ffi/make-downcall "releases_float_array" [::mem/pointer] ::mem/void)) (def ^:private release-floats* (ffi/make-downcall "releases_float_array" [::mem/pointer] ::mem/void))
(defn returns-float-array (defn returns-float-array
[] []
(with-open [session (mem/stack-session)] (with-open [arena (mem/confined-arena)]
(let [out-floats (mem/alloc mem/pointer-size session) ;; float *out_floats;
num-floats (function-handle (mem/address-of out-floats)) ;; int num_floats = returns_float_array(&out_floats);
(let [out-floats (mem/alloc mem/pointer-size arena)
num-floats (returns-float-array* (mem/address-of out-floats))
floats-addr (mem/read-address out-floats) floats-addr (mem/read-address out-floats)
floats-slice (mem/slice-global floats-addr (unchecked-multiply-int mem/float-size num-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, ;; Using a try/finally to perform an operation when the stack frame exits,
@ -660,7 +664,7 @@ floats, the following code might be used.
mem/big-endian)) mem/big-endian))
(unchecked-inc-int index)))) (unchecked-inc-int index))))
(finally (finally
(release-floats floats-addr)))))) (release-floats* floats-addr))))))
``` ```
The above code manually performs all memory operations rather than relying on The above code manually performs all memory operations rather than relying on
@ -714,6 +718,8 @@ the multimethod `reify-symbolspec`, although it's recommended that for any
library authors who do so, namespaced keywords be used to name types. library authors who do so, namespaced keywords be used to name types.
## Alternatives ## Alternatives
**ALTERNATIVES INFORMATION IS OUT OF DATE. THE LINKS ARE FINE, BUT DESCRIPTIONS WILL BE UPDATED AT A LATER DATE.**
This library is not the only Clojure library providing access to native code. In This library is not the only Clojure library providing access to native code. In
addition the following libraries exist: addition the following libraries exist:
@ -743,7 +749,7 @@ appealing, as they have a smaller API surface area and it's easier to wrap
functions. functions.
### Benchmarks ### Benchmarks
**BENCHMARKS FOR COFFI AND DTYPE-NEXT ARE BASED ON AN OLD VERSION. NEW BENCHMARKS WILL BE CREATED WHEN PANAMA COMES OUT OF PREVIEW** **BENCHMARKS FOR COFFI AND DTYPE-NEXT ARE BASED ON AN OLD VERSION. NEW BENCHMARKS WILL BE CREATED SOON.**
An additional consideration when thinking about alternatives is the performance An additional consideration when thinking about alternatives is the performance
of each available option. It's an established fact that JNA (used by all three of each available option. It's an established fact that JNA (used by all three
@ -1135,24 +1141,6 @@ These features are planned for future releases.
- Mapped memory - Mapped memory
- Helper macros for custom serde implementations for composite data types - Helper macros for custom serde implementations for composite data types
### Future JDKs
The purpose of coffi is to provide a wrapper for published versions of Project
Panama, starting with JDK 17. As new JDKs are released, coffi will be ported to
the newer versions of Panama. Version `0.4.341` is the last version compatible
with JDK 17. Version `0.5.357` is the last version compatible with JDK 18.
Version `0.6.409` is the latest version compatible with JDK 19. Bugfixes, and
potential backports of newer coffi features may be found on the `jdk17-lts`
branch. Development of new features and fixes as well as support for new Panama
idioms and features will continue with focus only on the latest JDK. If a
particular feature is not specific to the newer JDK, PRs backporting it to
versions of coffi supporting Java 17 will likely be accepted.
### 1.0 Release
Because the feature that coffi wraps in the JDK is in preview as of JDK 19,
coffi itself will not be released in a 1.0.x version until the feature becomes a
core part of the JDK, likely before or during the next LTS release, Java 21, in
September 2023.
## License ## License
Copyright © 2023 Joshua Suskalo Copyright © 2023 Joshua Suskalo