tech.v3.jna — techascent/tech.jna 4.01

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 clj

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

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

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

(char-ptr-ptr->string-vec num-strings char-ptr-ptr)

Decode a char** ptr.

checknil clj

(checknil value)

Check that a thing is a pointer and the integer value is not zero.

clear-library-paths clj

(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]].

create-ptr-ptr clj

(create-ptr-ptr ptr)

Create a pointer to a pointer.

def-jna-fn clj 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.

ensure-ptr clj

(ensure-ptr item)

Convert thing to pointer or throw exception.

ensure-ptr-ptr clj

(ensure-ptr-ptr item)

Ensure a thing is a ptr-to-a-ptr.

ensure-type clj

(ensure-type item-cls item)

Ensure a thing is derived from item-cls

find-function clj

(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

library-paths clj

(library-paths libname)

Get the current library search paths for a library.

load-library clj

(load-library libname)

Load a library. Returns

malloc clj

(malloc num-bytes)

(malloc num-bytes {:keys [resource-type] :or {resource-type #{:gc}}})

Malloc a pointer of Y bytes. Track using both resource context and gc system.

Options:

• :resource-type - Defaults to :gc. May be one or both of
  • :gc - rely on the garbage collector to let us know when the ptr is no longer reachable by our program.
  • :stack - Must be used within a tech.v3.resource/stack-resource-context and ensures the memory will be freed when the nearest scope has exited.

For a much more thorough treatment of native heap data, please see the documentation for dtype-next.

malloc-untracked clj

(malloc-untracked num-bytes)

Malloc pointer of Y bytes. Up to caller to call Native/free on result at some point

map-shared-library-name clj

(map-shared-library-name libname)

Map a stem to a shared library name in platform specific manner

math-library-name clj

(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 clj protocol

->ptr-backing-store clj

(->ptr-backing-store item)

Conversion to a jna pointer type that points to the data of the object.

is-jna-ptr-convertible? clj

(is-jna-ptr-convertible? item)

Is this object convertible to a JNA pointer?

ptr-convertible? clj

(ptr-convertible? item)

Is this object pointer convertible via the PToPtr protocol.

register-direct-mapped-class! clj

(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! clj

(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! clj

(set-loaded-library! libname native-library)

Override the search mechanism and set the native library to X.

size-t clj

(size-t)

(size-t item)

Convert item to either an integer or a long depending on the size of size-t.

size-t-compile-time-switch clj 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

size-t-ref clj

(size-t-ref)

(size-t-ref item)

Create a reference to a size-t.

size-t-ref-type clj

The runtime reference-by-ptr type of a c size-t

size-t-ref-value clj

(size-t-ref-value ref-obj)

Get the value from a size-t reference.

size-t-type clj

The runtime class type of a c size-t

string->ptr clj

(string->ptr data)

(string->ptr data options)

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 clj

(string->ptr-untracked data)

Convert a string to a pointer. Memory will not be automatically freed.

string->wide-ptr clj

(string->wide-ptr data)

(string->wide-ptr data options)

Convert a string into a wchar-t using utf-16.

unsafe-read-byte clj

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

(variable-byte-ptr->string ptr-addr)

Convert a c-string into a string

wide-ptr->string clj

(wide-ptr->string wide-ptr)

Convert a wchar-t ptr to a java string