This is a minimal union in coffi. If the :dispatch keyword argument is not passed, then the union cannot be serialized, as coffi would not know which type to serialize the values as. In the example with a tagged union, a dispatch function was not provided because the type was only used for the native layout.
This is a minimal union in coffi. If the :dispatch keyword argument is not passed, then the union cannot be serialized, as coffi would not know which type to serialize the values as. In the example with a tagged union, a dispatch function was not provided because the type was only used for the native layout.
In addition to a dispatch function, when serializing a union an extract function may also be provided. In the case of the value in the tagged union from before, it could be represented for serialization purposes like so:
[::mem/union
#{::mem/int ::mem/c-string}
diff --git a/docs/articles/03-Builtin-Types.md b/docs/articles/03-Builtin-Types.md
index 7b9ecdd..5de1e29 100644
--- a/docs/articles/03-Builtin-Types.md
+++ b/docs/articles/03-Builtin-Types.md
@@ -26,8 +26,9 @@ without external information.
This is a minimal union in coffi. If the `:dispatch` keyword argument is not
passed, then the union cannot be serialized, as coffi would not know which type
-to serialize the values as. In the example with a tagged union, a dispatch
-function was not provided because the type was only used for the native layout.
+to serialize the values as. In [the example with a tagged
+union](04-Custom-Types.md#tagged-union), a dispatch function was not provided
+because the type was only used for the native layout.
In addition to a dispatch function, when serializing a union an extract function
may also be provided. In the case of the value in the tagged union from before,
diff --git a/docs/coffi.ffi.html b/docs/coffi.ffi.html
index c133e8f..a46fe82 100644
--- a/docs/coffi.ffi.html
+++ b/docs/coffi.ffi.html
@@ -4,38 +4,38 @@
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.
-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.
+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.
-defconst
macro
(defconst symbol docstring? symbol-or-addr type)Defines a var named by symbol to be the value of the given type from symbol-or-addr.
-defvar
macro
(defvar symbol docstring? symbol-or-addr type)Defines a var named by symbol to be a reference to the native memory from symbol-or-addr.
-ensure-symbol
(ensure-symbol symbol-or-addr)Returns the argument if it is a MemorySegment, otherwise calls find-symbol on it.
-freset!
(freset! static-var newval)Sets the value of static-var to newval, running it through serialize.
-fswap!
(fswap! static-var f & args)Non-atomically runs the function f over the value stored in static-var.
+defconst
macro
(defconst symbol docstring? symbol-or-addr type)Defines a var named by symbol to be the value of the given type from symbol-or-addr.
+defvar
macro
(defvar symbol docstring? symbol-or-addr type)Defines a var named by symbol to be a reference to the native memory from symbol-or-addr.
+ensure-symbol
(ensure-symbol symbol-or-addr)Returns the argument if it is a MemorySegment, otherwise calls find-symbol on it.
+freset!
(freset! static-var newval)Sets the value of static-var to newval, running it through serialize.
+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.
-load-system-library
(load-system-library libname)Loads the library named libname from the system’s load path.
-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.
+load-system-library
(load-system-library libname)Loads the library named libname from the system’s load path.
+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.
-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.
-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.
-make-varargs-factory
(make-varargs-factory symbol required-args ret)Returns a function for constructing downcalls with additional types for arguments.
+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.
+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.
+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.
-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.
-reify-symbolspec
multimethod
Takes a spec for a symbol reference and returns a live value for that type.
-static-variable
(static-variable symbol-or-addr type)Constructs a reference to a mutable value stored in symbol-or-addr.
+reify-symbolspec
multimethod
Takes a spec for a symbol reference and returns a live value for that type.
+static-variable
(static-variable symbol-or-addr type)static-variable-segment
(static-variable-segment static-var)Gets the backing MemorySegment from static-var.
+static-variable-segment
(static-variable-segment static-var)Gets the backing MemorySegment from static-var.
This is primarily useful when you need to pass the static variable’s address to a native function which takes an Addressable.
-vacfn-factory
(vacfn-factory symbol required-args ret)Constructs a varargs factory to call the native function referenced by symbol.
+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.
-