uncomplicate.commons.core — uncomplicate/commons 0.16.1

Core Uncomplicate functions useful across all projects.

Projects that use native libraries and FFI typically need to dispose resources properly. To make this uniform, the typical resource managers need to implement the Releaseable protocol. Clients can then use the following functions to manage resources: [[release]] releaseable?, with-release, let-release.

It is often the case that you need an access to a mutable resource, but you want to protect the object's resource from destruction. For such cases (and other cases when this might be useful) there is a Viewable protocol. The [[view]] function should return a 'portal' to the object whose [[release]] implementation does nothing to the underlying resource.

For cases where you'd like to have the ability to inspect an object for various internal detail, but don't want to clutter its interface with many additional functions not related to the domain itself, implement the Info protocol. The [[info]] method returns a hash-map of all available information, or, if provided with a key, only the specific property related to that key.

Objects that manage data of certain size can implement protocols Entries and Bytes. Use the following functions to query for the data properties: size, sizeof, and bytesize.

The following functions might be useful from time to time when dealing with primitive types.

types, double-fn, long-fn, wrap-byte wrap-short wrap-int wrap-longwrap-floatwrap-double, Mappable, [[map]], [[unmap]].

Please refer to the tests folder, and to the source of other Uncomplicate projects to see how the functions from this namespace can be useful in various ways.

Bytes clj protocol

Object that has size in bytes.

bytesize* clj

(bytesize* this)

The size of this object's data in bytes.

bytesize clj

(bytesize x)

The size of x's data in bytes.

double-fn clj macro

(double-fn f)

Wraps a function into a primitive type-annotated function (to satisfy the compiler in some cases).

Entries clj protocol

Object that holds data that has total size in number of entries and size of one entry in bytes.

size* clj

(size* this)

Number of entries in data.

sizeof* clj

(sizeof* entry)

Size of one data entry in bytes.

Info clj protocol

Object that can provide detailed information maps.

info clj

(info this)

(info this info-type)

Provide all available information, or, spicific information if the corresponding info-type key is provided.

let-release clj macro

(let-release bindings & body)

Binds Releasable elements to symbols (like let does), evaluates body, and, if any exception occures, releases the resources held by the bindings. The bindings can also be deeply sequential (see examples) - they should be released properly.

Example:

(let-release [devs (devices (first (platforms)))
              dev (first devs)
              ctx (context devs)
              queue (command-queue ctx dev)]
  (info dev)
  (info queue))

long-fn clj macro

(long-fn f)

Wraps a function into a primitive type-annotated function (to satisfy the compiler in some cases).

Mappable clj protocol

Objects whose memory can be mapped or unmapped.

mmap clj

(mmap this)

(mmap this flags)

Map this object.

unmap clj

(unmap this mapped)

Unmap this object.

Releaseable clj protocol

Objects that hold resources that can be released after use. For OpenCL objects, releasing means decrementing the reference count of the object. Pointers call JavaCPP deallocators, Vectors and matrices call free!, etc. The errors should be signalled by throwing an exception rather than by the return value.

release clj

(release this)

Releases all resources held by this object.

releaseable? clj

(releaseable? this)

Checks whether this is releaseable (in terms of Releaseable protocol).

size clj

(size x)

The size of x's data in number of entries.

sizeof clj

(sizeof x)

The size of one data entry of x's data in bytes.

types clj

Available mappings from keywords to Java primitive types.

Viewable clj protocol

Attach a default dense structure to the raw data of x. x can be anything that implements Viewable, such as DirectByteBuffer, Pointer, vector, matrix, tensor, Java object etc. The default implementation just returns the object itself. Changes to the resulting object can affect the source x, even the parts of data that might not be accessible by x. Use with caution! Typically creates a new instance that reuses the master's data, but releasing a view should never release the master data. Many code examples are available throughout Uncomplicate libraries.

view clj

(view this)

Views this through new managing instance.

with-release clj macro

(with-release bindings & body)

Binds Releasable elements to symbols (like let does), evaluates body, and eventually releases the resources held by the bindings. The bindings can also be deeply sequential (see examples) - they should be released properly.

Example:

(with-release [devs (devices (first (platforms)))
               dev (first devs)
               ctx (context devs)
               queue (command-queue ctx dev)]
  (info dev)
  (info queue))

wrap-byte clj

(wrap-byte x)

Wraps a long number with a primitive byte array

wrap-double clj

(wrap-double x)

Wraps a double number with a primitive double array

wrap-float clj

(wrap-float x)

Wraps a double number with a primitive float array

wrap-int clj

(wrap-int x)

Wraps a long number with a primitive int array

wrap-long clj

(wrap-long x)

Wraps a long number with a primitive long array

wrap-short clj

(wrap-short x)

Wraps a long number with a primitive short array