tech.v3.jna
Simple bindings to the JNA system. Fastest pathway to success is def-jna-fn. Note that the default behavior for malloc has changed; the default resource type is :gc now as opposed to [:stack :gc].
Also, for ease of use when creating derived objects from gc-managed native pointer-based objects see tech.v3.resource/chain-resources.
add-library-path
(add-library-path libname pathtype path)Add a search path. The multimethod (base/find-library pathtype path) is called to expand the pathtype, path into one or more actual paths to attempt. Valid existing pathtypes are
:system - no changes, looks in system paths. :java-library-path - Appends library to all paths in java-library-paths :resource - Uses jna Native/extractFromResourcePath
as-ptr
(as-ptr item)Convert this object to a jna Pointer returning nil if not possible. For a checked conversion see ensure-ptr.
c-library-name
(c-library-name)Get the c library name for your system. This can be used with def-jna-fn to bind to various c library function calls.
char-ptr-ptr->string-vec
(char-ptr-ptr->string-vec num-strings char-ptr-ptr)Decode a char** ptr.
checknil
(checknil value)Check that a thing is a pointer and the integer value is not zero.
clear-library-paths
(clear-library-paths libname)Clear the library search paths for a specific library. Use with care; the default if non found is: :system libname] [:java-library-path libname.
def-jna-fn
macro
(def-jna-fn libname fn-name docstring rettype & argpairs)Define a dynamically bound fn. Upon first call, it will attempt to find the function pointer from libname. Redefinition resets the functions so it will rebind to a location.
rettype- Class return type or nil for void.argpairs- one or more pairs of type [symbol type-coersion] where the symbol is what will be displayed in the function’s docstring and type-coersion is a function that is run at function call time to ensure the type is the exact correct type. If coersion function is wrong and creates the wrong type for the function signature your program will probably crash.
(jna/def-jna-fn (jna/c-library-name) strcpy
"Copy a (hopefully) null terminated string into a pointer. This is a horrible idea."
Pointer
[dest jna/ensure-ptr]
[src jna/ensure-ptr])
find-function
(find-function fn-name libname)Given a function name and a library name, find the function in the library. Returns a com.sun.jna Function object. For a much more user-friendly and higher level pathway see def-jna-fn
malloc
(malloc num-bytes {:keys [resource-type log-level], :or {resource-type #{:gc}}})(malloc num-bytes)Malloc a pointer of Y bytes. Track using both resource context and gc system.
Options:
:resource-type-:track-typein tech.v3.resource with passthrough semantics.:log-level- Defaults to nil - if provided malloc/free call pairs will be logged at this level.
For a much more thorough treatment of native heap data, please see the documentation for dtype-next - native-buffer
malloc-untracked
(malloc-untracked num-bytes)Malloc pointer of Y bytes. Up to caller to call Native/free on result at some point
math-library-name
(math-library-name)Get the c math library name for your system. This can be used with def-jna-fn to bind to various c library function calls.
PToPtr
protocol
members
->ptr-backing-store
(->ptr-backing-store item)Conversion to a jna pointer type that points to the data of the object.
is-jna-ptr-convertible?
(is-jna-ptr-convertible? item)Is this object convertible to a JNA pointer?
ptr-convertible?
(ptr-convertible? item)Is this object pointer convertible via the PToPtr protocol.
register-direct-mapped-class!
(register-direct-mapped-class! libname cls-obj)Register a direct-mapped class with a library. Calling direct-mapped functions dramatically decreases function call overhead and brings it inline with hand-built JNI bindings.
Direct-mapped classes look like normal classes with functions defined with static native attributes.
From libpython-clj:
(com.sun.jna.Native/register DirectMapped library)
reload!
(reload! libname)Reload a shared library. This means that any dynamically bound functions defined via def-jna-fn will load the new library’s functions as they are dynamically found at call time every time. Any direct-mapped classes will need to be rebound via register-direct-mapped-class.
set-loaded-library!
(set-loaded-library! libname native-library)Override the search mechanism and set the native library to X.
size-t
(size-t item)(size-t)Convert item to either an integer or a long depending on the size of size-t.
size-t-compile-time-switch
macro
(size-t-compile-time-switch int-body long-body)Run either int32 based code or int64 based code depending on the runtime size of size-t
string->ptr
(string->ptr data options)(string->ptr data)Convert a string to a pointer. Track the data via the gc; when the Pointer goes out of scope the memory will be freed.
string->ptr-untracked
(string->ptr-untracked data)Convert a string to a pointer. Memory will not be automatically freed.
string->wide-ptr
(string->wide-ptr data options)(string->wide-ptr data)Convert a string into a wchar-t using utf-16. Default resource type is :gc.
unsafe-read-byte
(unsafe-read-byte byte-ary idx)Read a byte from pointer byte-ary at address idx. For bulk access convert the pointer to a tech.v3.datatype.native-buffer/NativeBuffer via:
(tech.v3.datatype.native-buffer/wrap-address
(com.sun.jna.Pointer/nativeValue ptr)
...)
variable-byte-ptr->string
(variable-byte-ptr->string ptr-addr)Convert a c-string into a string