luciano/coffi
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update readme to use session rather than scope

Browse source
This commit is contained in:
Joshua Suskalo 2022-11-29 13:41:55 -06:00
parent 65c7544cc7
commit 12b7661295
No known key found for this signature in database
GPG key ID: 9B6BA586EFF1B9F0
1 changed files with 15 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

30
README.md
View file

@ -426,8 +426,8 @@ serialize to primitives.
```clojure ```clojure
(defmethod mem/serialize* ::vector (defmethod mem/serialize* ::vector
[obj _type scope] [obj _type session]
(mem/address-of (mem/serialize obj [::mem/array ::mem/float 3] scope))) (mem/address-of (mem/serialize obj [::mem/array ::mem/float 3] session)))
(defmethod mem/deserialize* ::vector (defmethod mem/deserialize* ::vector
[addr _type] [addr _type]
@ -436,9 +436,9 @@ serialize to primitives.
``` ```
The `slice-global` function allows you to take an address without an associated The `slice-global` function allows you to take an address without an associated
scope and get a memory segment which can be deserialized. session and get a memory segment which can be deserialized.
In cases like this where we don't know the scope of the pointer, we could use In cases like this where we don't know the session of the pointer, we could use
`add-close-action!` to ensure it's freed. For example if a `free-vector!` `add-close-action!` to ensure it's freed. For example if a `free-vector!`
function that takes a pointer exists, we could use this: function that takes a pointer exists, we could use this:
@ -446,14 +446,14 @@ function that takes a pointer exists, we could use this:
(defcfn returns-vector (defcfn returns-vector
"returns_vector" [] ::mem/pointer "returns_vector" [] ::mem/pointer
native-fn native-fn
[scope] [session]
(let [ret-ptr (native-fn)] (let [ret-ptr (native-fn)]
(add-close-action! scope #(free-vector! ret-ptr)) (add-close-action! session #(free-vector! ret-ptr))
(deserialize ret-ptr ::vector))) (deserialize ret-ptr ::vector)))
``` ```
This function takes a scope and returns the deserialized vector, and it will This function takes a session and returns the deserialized vector, and it will
free the pointer when the scope closes. free the pointer when the session closes.
#### Tagged Union #### Tagged Union
For the tagged union type, we will represent the value as a vector of a keyword For the tagged union type, we will represent the value as a vector of a keyword
@ -505,7 +505,7 @@ deserialize the value into and out of memory segments. This is accomplished with
(map first)))) (map first))))
(defmethod mem/serialize-into ::tagged-union (defmethod mem/serialize-into ::tagged-union
[obj [_tagged-union tags type-map] segment scope] [obj [_tagged-union tags type-map] segment session]
(mem/serialize-into (mem/serialize-into
{:tag (item-index tags (first obj)) {:tag (item-index tags (first obj))
:value (second obj)} :value (second obj)}
@ -513,7 +513,7 @@ deserialize the value into and out of memory segments. This is accomplished with
[[:tag ::mem/long] [[:tag ::mem/long]
[:value (get type-map (first obj))]]] [:value (get type-map (first obj))]]]
segment segment
scope)) session))
``` ```
This serialization method is rather simple, it just turns the vector value into This serialization method is rather simple, it just turns the vector value into
@ -570,7 +570,7 @@ it could be represented for serialization purposes like so:
This union however would not include the tag when serialized. This union however would not include the tag when serialized.
If a union is deserialized, then all that coffi does is to allocate a new If a union is deserialized, then all that coffi does is to allocate a new
segment of the appropriate size with an implicit scope so that it may later be segment of the appropriate size with an implicit session so that it may later be
garbage collected, and copies the data from the source segment into it. It's up garbage collected, and copies the data from the source segment into it. It's up
to the user to call `deserialize-from` on that segment with the appropriate to the user to call `deserialize-from` on that segment with the appropriate
type. type.
@ -599,8 +599,8 @@ from the `java.lang.foreign` package.
In addition, when a raw handle returns a composite type represented with a In addition, when a raw handle returns a composite type represented with a
`MemorySegment`, it requires an additional first argument, a `SegmentAllocator`, `MemorySegment`, it requires an additional first argument, a `SegmentAllocator`,
which can be acquired with `scope-allocator` to get one associated with a which can be acquired with `session-allocator` to get one associated with a
specific scope. The returned value will live until that scope is released. specific session. The returned value will live until that session is released.
In addition, function types can be specified as being raw, in the following In addition, function types can be specified as being raw, in the following
manner: manner:
@ -640,8 +640,8 @@ floats, the following code might be used.
(defn returns-float-array (defn returns-float-array
[] []
(with-open [scope (mem/stack-scope)] (with-open [session (mem/stack-session)]
(let [out-floats (mem/alloc mem/pointer-size scope) (let [out-floats (mem/alloc mem/pointer-size session)
num-floats (function-handle (mem/address-of out-floats)) num-floats (function-handle (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))]