uncomplicate.clojure-cpp — org.uncomplicate/clojure-cpp 0.3.0

ClojureCPP is a Clojure library for integrating C/C++ based libraries available through JavaCPP. It is much more than a wrapper around JavaCPP that hides Java interop. It enables you to use JavaCPP's Pointer-based infrastucture the Clojure way; exposing what is absolutely necessary, automating whatever boilerplate that can be automated under the hood, and protecting yourself from shooting yourself in the foot with memory leaks and segmentation faults as much as possible (95%? 89%? who knows, but not 100%). You still have to be careful, because you're stepping outside the JVM, but you'll write a lot less code, your code will fit nicely with the rest of Clojure code in your program, and you will do the wrong thing less often.

The center piece of this library is JavaCPP's Pointer class. Almost all JavaCPP interop methods accept subclasses of Pointer as arguments (along with good old Java primitives such as int or double). Very often, these pointers are pointers to off-heap primitive memory blocks that are not managed by your JVM, which are managed by classes such as DoublePointer or FloatPointer. That is because many C libraries use the respective arrays. Some libraries define their own structs; these are typically represented as specialized Pointer sublasses by JavaCPP. Typical examples would be CUDA or MKL wrappers. You can explore ClojureCUDA and Neanderthal code for real-world examples of how to deal with these if you need to create a new wrapper for a new library. Fortunately, if someone else has already done the integration, you might even write code without thinking much outside of Clojure. Depending of your grasp of the basics of C and/or C++, it still might be a good idea to read some introduction to JavaCPP.

Note that ClojureCPP is well integrated into Clojure and Uncomplicate family of libraries, which means that lots of functionality is integrated into general functions such as release, size, bytesize, sizeof from uncomplicate.commons, or fmap, fmap!, fold, op from uncomplicate.fluokitten, or similar polymorphic functions. Ideally, you'll prefer these over fiddling with lower-level ClojureCPP-specific code (when possible).

Here's a loose grouping of ClojureCPP functions:

• System functions give you some insight int o the overall system, memory, and allocations: physical-bytes, available-physical-bytes, max-physical-bytes, total-physical-bytes, tracked-bytes, max-tracked-bytes and pointers-count.

• Constructors. The pointers that you'll use throughout your code are explicitly created by these constructors. Alternatively, you'll work with pointers returned by custom functions from many of C libraries available through JavaCPP (such as CUDA etc.). You'll use these functions a lot. pointer, [[pointer-pointer]], [[byte-pointer]], [[keyword-pointer]], [[string-pointer]], [[bool-pointer]], [[bool-pointer]], [[clong-pointer]], [[size-t-pointer]], [[char-pointer]], [[short-pointer]], [[int-pointer]], [[long-pointer]], [[float-pointer]], [[double-pointer]], and [[function-pointer]].

• Memory allocation functions with standard C counterparts (you typically don't have to use these unless you're writing low-level stuff): malloc!, calloc!, realloc!, free!, memcmp, memcpy!, memmove!, memset!, and zero!.

• General pointer features:

pointer-type, pointer-class, and type-pointer are convenience mappings between keywords representing primitive types, built-in pointer classes, and pointer constructor functions, so you can, for example, use :float or Float instead if importing FloatPointer. That also helps in integration with other systems without coupling with JavaCPP types.

The following functions give you an insight into the properties of the pointer at hand. Most of the time, these properties are set by other functions to their right values, but sometimes you want to see details or even set something yourself (but be careful of papercuts!). address, null?, capacity, capacity!, limit, limit!, position, position!,

• This group of functions do some pointer arithmetic, type casts, or type conversions: get-pointer, safe, safe2, ptr*, ptr, ptr2, float-ptr*, float-ptr, float-ptr2, double-ptr*, double-ptr, double-ptr2, long-ptr*, long-ptr, long-ptr2, int-ptr*, int-ptr, int-ptr2, short-ptr*, short-ptr, short-ptr2, short-ptr*, short-ptr, short-ptr2, byte-ptr*, byte-ptr, byte-ptr2, size-t-ptr*, size-t-ptr, size-t-ptr2, clong-ptr*, clong-ptr, clong-ptr2, bool-ptr*, bool-ptr, bool-ptr2, char-ptr*, char-ptr, and char-ptr2.

• Java and Clojure conversions to Java buffers or Clojure vectors and sequences: as-byte-buffer, as-buffer, [[pointer-vec]], pointer-seq,

• Polymorphic access to data in memory blocks managed by a pointer: [[get!]], [[put!]], [[get-entry!]], [[put-entry!]], and [[fill!]]

• Raw access to bytes from a BytePointer: get-keyword, put-keyword!, get-string, put-string!, get-pointer-value, [[put-pointer-value]], get-unsigned, put-unsigned!, get-bool, put-bool!, get-char, put-char!, get-int, put-int!, get-short, put-short!, get-long, put-long!, get-byte, put-byte!, get-short, put-short!, get-double, put-double!, get-float, put-float!, and get-string-bytes.

Please read JavaCPP javadoc for more internal details when necessary. Also, getting familiar with common C library functions can be very helpful.

Please check out uncomplicate.clojure-cpp-test for examples of how to use these functions!

Accessor clj protocol

fill! clj

(fill! pointer value)

Sets all elements in pointer's memory block to value.

get! clj

(get! pointer dst!)

(get! pointer dst! offset length)

Copies data from pointer's memory block into dst, which is typically a Java array.

get-entry clj

(get-entry pointer)

(get-entry pointer i)

Gets the value at index i in pointer's memory block.

put! clj

(put! pointer! src)

(put! pointer! src offset length)

Copies data from a Java array or a Clojure sequence src to this pointer's memory block.

put-entry! clj

(put-entry! pointer value)

(put-entry! pointer i value)

Puts value into pointer's memory block at index i.

address clj

(address p)

Returns the address of pointer p

as-buffer clj

(as-buffer p)

as-byte-buffer clj

(as-byte-buffer p)

Returns a ByteBuffer representation of a pointer.

available-physical-bytes clj

(available-physical-bytes)

Amount of physical memory that is available (free) from the operating system. Returns 0 if this amount can't be determined.

bool-ptr clj

(bool-ptr p)

(bool-ptr p i)

Checks pointer p for safety with safe and casts it into BoolPointer. Does not actually convert p into BoolPointer!. It just does the type cast to satisfy Clojure's compiler. Useful when metadata for avoiding reflection is not easily added in code, such as in macros.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block. It DOES actually require p to be a BoolPointer!.

Prefer this method to bool-ptr* in places when NULL pointer can cause harm. Prefer this method to bool-ptr2 in places when nil is not allowed.

bool-ptr* clj

(bool-ptr* p)

(bool-ptr* p i)

Casts pointer p into BoolPointer. Useful when metadata for avoiding reflection is not easily added in code, such as in macros. Does not actually convert p into BoolPointer!. It just does the type cast to satisfy Clojure's compiler.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block.

Prefer this method to bool-ptr in places when you only care about satisfying the compiler, and don't care about NULL pointers.

bool-ptr2 clj

(bool-ptr2 p)

(bool-ptr2 p i)

Checks pointer p for safety with safe2 and casts it into BoolPointer. Does not actually convert p into BoolPointer!. It just does the type cast to satisfy Clojure's compiler. Useful when metadata for avoiding reflection is not easily added in code, such as in macros.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block. It DOES actually require p to be a BoolPointer!.

Prefer this method to bool-ptr* in places when NULL pointer can cause harm. Prefer this method to bool-ptr in places when nil is acceptable.

byte-ptr clj

(byte-ptr p)

(byte-ptr p i)

Checks pointer p for safety with safe and casts it into BytePointer. Does not actually convert p into BytePointer!. It just does the type cast to satisfy Clojure's compiler. Useful when metadata for avoiding reflection is not easily added in code, such as in macros.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block. It DOES actually convert p into BytePointer!.

Prefer this method to byte-ptr* in places when NULL pointer can cause harm. Prefer this method to byte-ptr2 in places when nil is not allowed.

byte-ptr* clj

(byte-ptr* p)

(byte-ptr* p i)

Casts pointer p into BytePointer. Useful when metadata for avoiding reflection is not easily added in code, such as in macros. Does not actually convert p into BytePointer!. It just does the type cast to satisfy Clojure's compiler.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block.

Prefer this method to byte-ptr in places when you only care about satisfying the compiler, and don't care about NULL pointers.

byte-ptr2 clj

(byte-ptr2 p)

(byte-ptr2 p i)

Checks pointer p for safety with safe2 and casts it into BytePointer. Does not actually convert p into BytePointer!. It just does the type cast to satisfy Clojure's compiler. Useful when metadata for avoiding reflection is not easily added in code, such as in macros.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block. It DOES actually convert p into BytePointer!.

Prefer this method to byte-ptr* in places when NULL pointer can cause harm. Prefer this method to byte-ptr in places when nil is acceptable.

calloc! clj

(calloc! n element-size)

Allocated a memory block of n elements each taking element-size bytes, and initializes it to 0. An alternative to malloc!.

(int-pointer (calloc! 2 8)) => {:address "0x7fd5b87596a0", :type :int, :position 0, :limit 2, :capacity 2, :entries (0 0)}

capacity clj

(capacity p)

Returns the capacity of p, as number of bytes if p is just a Pointer, or in number of elements, if p is one of typed pointers such as DoublePointer or IntPointer.

capacity! clj

(capacity! p n)

Sets the capacity of p, as number of bytes if p is just a Pointer, or in number of elements, if p is one of typed pointers such as DoublePointer or IntPointer. If n is negative, sets the capacity to 0. Be warned that setting capacity to an arbitrarily large number can crash your program, or, worse, Heisenbugs.

char-ptr clj

(char-ptr p)

(char-ptr p i)

Checks pointer p for safety with safe and casts it into CharPointer. Does not actually convert p into CharPointer!. It just does the type cast to satisfy Clojure's compiler. Useful when metadata for avoiding reflection is not easily added in code, such as in macros.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block. It DOES actually require p to be a CharPointer!.

Prefer this method to char-ptr* in places when NULL pointer can cause harm. Prefer this method to char-ptr2 in places when nil is not allowed.

char-ptr* clj

(char-ptr* p)

(char-ptr* p i)

Casts pointer p into CharPointer. Useful when metadata for avoiding reflection is not easily added in code, such as in macros. Does not actually convert p into CharPointer!. It just does the type cast to satisfy Clojure's compiler.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block.

Prefer this method to char-ptr in places when you only care about satisfying the compiler, and don't care about NULL pointers.

char-ptr2 clj

(char-ptr2 p)

(char-ptr2 p i)

Checks pointer p for safety with safe2 and casts it into CharPointer. Does not actually convert p into CharPointer!. It just does the type cast to satisfy Clojure's compiler. Useful when metadata for avoiding reflection is not easily added in code, such as in macros.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block. It DOES actually require p to be a CharPointer!.

Prefer this method to char-ptr* in places when NULL pointer can cause harm. Prefer this method to char-ptr in places when nil is acceptable.

clong-ptr clj

(clong-ptr p)

(clong-ptr p i)

Checks pointer p for safety with safe and casts it into CLongPointer. Does not actually convert p into CLongPointer!. It just does the type cast to satisfy Clojure's compiler. Useful when metadata for avoiding reflection is not easily added in code, such as in macros.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block. It DOES actually convert p into CLongPointer!.

Prefer this method to clong-ptr* in places when NULL pointer can cause harm. Prefer this method to clong-ptr2 in places when nil is not allowed.

clong-ptr* clj

(clong-ptr* p)

(clong-ptr* p i)

Casts pointer p into CLongPointer. Useful when metadata for avoiding reflection is not easily added in code, such as in macros. Does not actually convert p into CLongPointer!. It just does the type cast to satisfy Clojure's compiler.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block.

Prefer this method to clong-ptr in places when you only care about satisfying the compiler, and don't care about NULL pointers.

clong-ptr2 clj

(clong-ptr2 p)

(clong-ptr2 p i)

Checks pointer p for safety with safe2 and casts it into CLongPointer. Does not actually convert p into CLongPointer!. It just does the type cast to satisfy Clojure's compiler. Useful when metadata for avoiding reflection is not easily added in code, such as in macros.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block. It DOES actually convert p into CLongPointer!.

Prefer this method to clong-ptr* in places when NULL pointer can cause harm. Prefer this method to clong-ptr in places when nil is acceptable.

double-ptr clj

(double-ptr p)

(double-ptr p i)

Checks pointer p for safety with safe and casts it into DoublePointer. Does not actually convert p into DoublePointer!. It just does the type cast to satisfy Clojure's compiler. Useful when metadata for avoiding reflection is not easily added in code, such as in macros.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block. It DOES actually require p to be a DoublePointer!.

Prefer this method to double-ptr* in places when NULL pointer can cause harm. Prefer this method to double-ptr2 in places when nil is not allowed.

double-ptr* clj

(double-ptr* p)

(double-ptr* p i)

Casts pointer p into DoublePointer. Useful when metadata for avoiding reflection is not easily added in code, such as in macros. Does not actually convert p into DoublePointer!. It just does the type cast to satisfy Clojure's compiler.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block.

Prefer this method to double-ptr in places when you only care about satisfying the compiler, and don't care about NULL pointers.

double-ptr2 clj

(double-ptr2 p)

(double-ptr2 p i)

Checks pointer p for safety with safe2 and casts it into DoublePointer. Does not actually convert p into DoublePointer!. It just does the type cast to satisfy Clojure's compiler. Useful when metadata for avoiding reflection is not easily added in code, such as in macros.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block. It DOES actually require p to be a DoublePointer!.

Prefer this method to double-ptr* in places when NULL pointer can cause harm. Prefer this method to double-ptr in places when nil is acceptable.

float-ptr clj

(float-ptr p)

(float-ptr p i)

Checks pointer p for safety with safe and casts it into FloatPointer. Does not actually convert p into FloatPointer!. It just does the type cast to satisfy Clojure's compiler. Useful when metadata for avoiding reflection is not easily added in code, such as in macros.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block. It DOES actually require p to be a FloatPointer!.

Prefer this method to float-ptr* in places when NULL pointer can cause harm. Prefer this method to float-ptr2 in places when nil is not allowed.

float-ptr* clj

(float-ptr* p)

(float-ptr* p i)

Casts pointer p into FloatPointer. Useful when metadata for avoiding reflection is not easily added in code, such as in macros. Does not actually convert p into FloatPointer!. It just does the type cast to satisfy Clojure's compiler.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block.

Prefer this method to float-ptr in places when you only care about satisfying the compiler, and don't care about NULL pointers.

float-ptr2 clj

(float-ptr2 p)

(float-ptr2 p i)

Checks pointer p for safety with safe2 and casts it into FloatPointer. Does not actually convert p into FloatPointer!. It just does the type cast to satisfy Clojure's compiler. Useful when metadata for avoiding reflection is not easily added in code, such as in macros.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block. It DOES actually require p to be a FloatPointer!.

Prefer this method to float-ptr* in places when NULL pointer can cause harm. Prefer this method to float-ptr in places when nil is acceptable.

free! clj

(free! p)

Deallocates the memory block that was allocated by calloc!, malloc!, or realloc!. Although typically attempting to free a wrong block may hard crash your program, this function has protections against most of common errors, such as trying to free an already de-allocated block, or calling free after a careless pointer arithmetic. But there's always a way to shoot oneself in the foot, so please be careful with this. Returns a NULL pointer (not nil!).

get-bool clj

(get-bool p)

(get-bool p i)

Gets the bool value at index i in BytePointer's memory block.

get-byte clj

(get-byte p)

(get-byte p i)

Gets the byte value at index i in BytePointer's memory block.

get-char clj

(get-char p)

(get-char p i)

Gets the char value at index i in BytePointer's memory block.

get-double clj

(get-double p)

(get-double p i)

Gets the double value at index i in BytePointer's memory block.

get-float clj

(get-float p)

(get-float p i)

Gets the float value at index i in BytePointer's memory block.

get-int clj

(get-int p)

(get-int p i)

Gets the integer value at index i in BytePointer's memory block.

get-keyword clj

(get-keyword p)

(get-keyword p charset)

Converts a BytePointer's memory block to keyword.

get-long clj

(get-long p)

(get-long p i)

Gets the long value at index i in BytePointer's memory block.

get-pointer clj

(get-pointer p)

(get-pointer p i)

(get-pointer p type i)

Returns a new pointer that manages the memory block managed by p, starting from element i, bounded by capacity (capacity p). If provided with pointer's type, coerces the pointer to it (please see pointer-class for available types). This is useful when you need to change some of pointer's properties in parts of code, but leave the original pointer unchanged. Please be careful: although negative values of i can be used normally as you go back and forth through a memory block, it is your responsibility to make sure that you do not overstep into the territory outside the originally allocated array. ClojureCPP doesn't have a way to do this for you.

get-pointer-value clj

(get-pointer-value p)

(get-pointer-value p i)

Gets a Pointer as the value at index i in BytePointer's memory block.

get-short clj

(get-short p)

(get-short p i)

Gets the short value at index i in BytePointer's memory block.

get-string clj

(get-string p)

(get-string p charset)

Converts a BytePointer's memory block to string.

get-string-bytes clj

(get-string-bytes p)

Assuming that p contains a null-terminated string, returns its byte representation in a byte array.

get-unsigned clj

(get-unsigned p)

(get-unsigned p i)

Gets a Pointer as the value at index i in BytePointer's memory block.

int-ptr clj

(int-ptr p)

(int-ptr p i)

Checks pointer p for safety with safe and casts it into IntPointer. Does not actually convert p into IntPointer!. It just does the type cast to satisfy Clojure's compiler. Useful when metadata for avoiding reflection is not easily added in code, such as in macros.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block. It DOES actually convert p into IntPointer!.

Prefer this method to int-ptr* in places when NULL pointer can cause harm. Prefer this method to int-ptr2 in places when nil is not allowed.

int-ptr* clj

(int-ptr* p)

(int-ptr* p i)

Casts pointer p into IntPointer. Useful when metadata for avoiding reflection is not easily added in code, such as in macros. Does not actually convert p into IntPointer!. It just does the type cast to satisfy Clojure's compiler.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block.

Prefer this method to int-ptr in places when you only care about satisfying the compiler, and don't care about NULL pointers.

int-ptr2 clj

(int-ptr2 p)

(int-ptr2 p i)

Checks pointer p for safety with safe2 and casts it into IntPointer. Does not actually convert p into IntPointer!. It just does the type cast to satisfy Clojure's compiler. Useful when metadata for avoiding reflection is not easily added in code, such as in macros.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block. It DOES actually convert p into IntPointer!.

Prefer this method to int-ptr* in places when NULL pointer can cause harm. Prefer this method to int-ptr in places when nil is acceptable.

limit clj

(limit p)

Returns the limit of p, as number of bytes if p is just a Pointer, or in number of elements, if p is one of typed pointers such as DoublePointer or IntPointer.

limit! clj

(limit! p n)

Sets the limit of p, as number of bytes if p is just a Pointer, or in number of elements, if p is one of typed pointers such as DoublePointer or IntPointer. If n is negative, or larger than the available capacity, throws IllegalArgumentexception.

long-ptr clj

(long-ptr p)

(long-ptr p i)

Checks pointer p for safety with safe and casts it into LongPointer. Does not actually convert p into LongPointer!. It just does the type cast to satisfy Clojure's compiler. Useful when metadata for avoiding reflection is not easily added in code, such as in macros.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block. It DOES actually require p to be a LongPointer!.

Prefer this method to long-ptr* in places when NULL pointer can cause harm. Prefer this method to long-ptr2 in places when nil is not allowed.

long-ptr* clj

(long-ptr* p)

(long-ptr* p i)

Casts pointer p into LongPointer. Useful when metadata for avoiding reflection is not easily added in code, such as in macros. Does not actually convert p into LongPointer!. It just does the type cast to satisfy Clojure's compiler.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block.

Prefer this method to long-ptr in places when you only care about satisfying the compiler, and don't care about NULL pointers.

long-ptr2 clj

(long-ptr2 p)

(long-ptr2 p i)

Checks pointer p for safety with safe2 and casts it into LongPointer. Does not actually convert p into LongPointer!. It just does the type cast to satisfy Clojure's compiler. Useful when metadata for avoiding reflection is not easily added in code, such as in macros.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block. It DOES actually require p to be a LongPointer!.

Prefer this method to long-ptr* in places when NULL pointer can cause harm. Prefer this method to long-ptr in places when nil is acceptable.

malloc! clj

(malloc! byte-size)

Allocates the byte-size bytes of memory and returns a Pointer that manages it. The memory block allocated by malloc! has to be explicitly freed by free!. Calling release has no effect because no deallocator has been attached. It is very important to keep in mind that malloc! does NOT initialize the memory block. The danger is that often values could be 0, and this may trick you into believing that they typically will be initialized! In general, the memory block contains garbage, and must be explicitly initialized if your program relies on the values being 0 after allocation. If called with a negative number, returns nil.

Prefer creating a pointer with (int-pointer 8) instead of with (int-pointer (malloc! 8)), unless you have a specific reason to do otherwise. This returns a fully configured, but still uninitialized, pointer that has a deallocator.

max-physical-bytes clj

(max-physical-bytes)

The maximum amount of physical memory that should (could?) be used.

max-tracked-bytes clj

(max-tracked-bytes)

The maximum amount of memory allowed to be tracked by JavaCPP deallocators.

memcmp clj

(memcmp p1 p2)

(memcmp p1 p2 byte-size)

Compares the first byte-size bytes of p1 and p2. Returns a long integer, not a boolean! The result is as follows: zero: byte-size bytes are equal negative: p1 is less than p2 positive: p2 is less than p1

If byte-size is not within bounds of p1 and p2, throws IndexOutOfBoundsException.

(memcmp (byte-pointer [1 2 3]) (byte-pointer [1 1 4]) 3) => 1

memcpy! clj

(memcpy! src dst)

(memcpy! src dst byte-size)

Copies byte-size bytes from src to dst, nad returns dst. If byte-size is not within bounds of src and dst, throws IndexOutOfBoundsException.

memmove! clj

(memmove! src dst)

(memmove! src dst byte-size)

Copies byte-size bytes from src to dst, and returns dst. A safer alternative to memcpy! in cases when src and dst contain overlapping memory blocks. If byte-size is not within bounds of src and dst, throws IndexOutOfBoundsException.

memset! clj

(memset! dst value byte-size)

Sets byte-size bytes of dst to value, and returns dst. If byte-size is not within bounds of src and dst, throws IndexOutOfBoundsException.

null? clj

(null? p)

Checks whether p points is nil or a NULL pointer. Typically, the NULL pointer is a pointer that has not yet been allocated (by malloc!, calloc!, or pointer constructors) or has been deallocated or freed.

physical-bytes clj

(physical-bytes)

(physical-bytes max-size)

Amount of non-shared physical memory currently used by the process. If provided with max-size, may return an approximate value, between real physical bytes and max-size, saving some processing time. Returns 0 if this amount can't be determined.

pointer clj

(pointer x)

(pointer x i)

Coerces x to appropriate Pointer subclass, with position indicated by index i. The exact behavior is polymorphic per pointer type. If the argument is already a pointer, it just gets returned without change.

Most common Clojure and Java collections are supported out of the box, with following characteristics regarding the new pointer's memory block:

• The contents of a Java array is copied into new pointer's memory block, with no further connection between the two.
• The contents of a java.nio.Buffer is copied into new pointer's memory block, with no further connection between the two.
• The contents of a direct java.nio.Buffer is referenced by the pointer's memory, and each change is reflected in both.
• The contents of a clojure sequence is copied into new pointer's memory block, with no further connection between the two.

Custom classes are free to define they own way of converting to pointers by implementing the [[pointer*]] methods of the [[PointerCreator]] protocol.

pointer-class clj

A mapping of Java number types and related keywords to appropriate JavaCPP pointer types. (pointer-class :float) => FloatPointer

pointer-seq clj

(pointer-seq p)

Creates a lazy seq of this pointer's elements. Similar to clojure.core/seq.

pointer-type clj

A mapping of JavaCPP pointer types to appropriate keywords. (pointer-type FloatPointer) => :float

pointers-count clj

(pointers-count)

Number of pointers currently tracked by JavaCPP deallocators.

PointerVec clj protocol

pointer-vec clj

(pointer-vec this)

Returns a vector representation of elements in pointer's memory block, taking into account pointer's type

position clj

(position p)

Returns the position where p begins, as number of bytes if p is just a Pointer, or in number of elements, if p is one of typed pointers such as DoublePointer or IntPointer.

position! clj

(position! p n)

Sets the position where p begins, as number of bytes if p is just a Pointer, or in number of elements, if p is one of typed pointers such as DoublePointer or IntPointer. If n is negative, or larger than the available capacity, throws IllegalArgumentexception.

ptr clj

(ptr p)

(ptr p i)

Checks pointer p for safety with safe and casts it into Pointer. Useful when metadata for avoiding reflection is not easily added in code, such as in macros. If provided with index i, behaves like get-pointer.

Please be careful: although negative values of i can be used normally as you go back and forth through a memory block, it is your responsibility to make sure that you do not overstep into the territory outside the originally allocated array. ClojureCPP doesn't have a way to do this for you.

ptr* clj

(ptr* p)

(ptr* p i)

Casts pointer p into Pointer. Useful when metadata for avoiding reflection is not easily added in code, such as in macros. If provided with index i, behaves like get-pointer.

ptr2 clj

(ptr2 p)

(ptr2 p i)

Checks pointer p for safety with safe2 and casts it into Pointer. Useful when metadata for avoiding reflection is not easily added in code, such as in macros. If provided with index i, behaves like get-pointer.

Please be careful: although negative values of i can be used normally as you go back and forth through a memory block, it is your responsibility to make sure that you do not overstep into the territory outside the originally allocated array. ClojureCPP doesn't have a way to do this for you.

put-bool! clj

(put-bool! p i x)

Puts bool value x at index i in BytePointer's memory block.

put-byte! clj

(put-byte! p i x)

Puts byte value x at index i in BytePointer's memory block.

put-char! clj

(put-char! p i x)

Puts char value x at index i in BytePointer's memory block.

put-double! clj

(put-double! p i x)

Puts double value x at index i in BytePointer's memory block.

put-float! clj

(put-float! p i x)

Puts float value x at index i in BytePointer's memory block.

put-int! clj

(put-int! p i x)

Puts char value x at index i in BytePointer's memory block.

put-keyword! clj

(put-keyword! p k charset)

Puts keyword value k using charset in BytePointer's memory block.

put-long! clj

(put-long! p i x)

Puts long value x at index i in BytePointer's memory block.

put-pointer-value! clj

(put-pointer-value! p i x)

Puts Pointer ``x at index i in BytePointer's memory block.

put-short! clj

(put-short! p i x)

Puts short value x at index i in BytePointer's memory block.

put-string! clj

(put-string! p s charset)

Puts string value s using charset in BytePointer's memory block.

put-unsigned! clj

(put-unsigned! p i x)

Puts unsigned long value x at index i in BytePointer's memory block.

realloc! clj

(realloc! p byte-size)

Attempts to resize a memory block previously created by malloc! or calloc!.

safe clj

(safe p)

If pointer p is neither nil nor NULL, returns p. Otherwise, throws an IllegalArgumentexception.

safe2 clj

(safe2 p)

If pointer p is not NULL, returns p. Otherwise, throws an IllegalArgumentexception.

short-ptr clj

(short-ptr p)

(short-ptr p i)

Checks pointer p for safety with safe and casts it into ShortPointer. Does not actually convert p into ShortPointer!. It just does the type cast to satisfy Clojure's compiler. Useful when metadata for avoiding reflection is not easily added in code, such as in macros.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block. It DOES actually convert p into ShortPointer!.

Prefer this method to short-ptr* in places when NULL pointer can cause harm. Prefer this method to short-ptr2 in places when nil is not allowed.

short-ptr* clj

(short-ptr* p)

(short-ptr* p i)

Casts pointer p into ShortPointer. Useful when metadata for avoiding reflection is not easily added in code, such as in macros. Does not actually convert p into ShortPointer!. It just does the type cast to satisfy Clojure's compiler.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block.

Prefer this method to short-ptr in places when you only care about satisfying the compiler, and don't care about NULL pointers.

short-ptr2 clj

(short-ptr2 p)

(short-ptr2 p i)

Checks pointer p for safety with safe2 and casts it into ShortPointer. Does not actually convert p into ShortPointer!. It just does the type cast to satisfy Clojure's compiler. Useful when metadata for avoiding reflection is not easily added in code, such as in macros.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block. It DOES actually convert p into ShortPointer!.

Prefer this method to short-ptr* in places when NULL pointer can cause harm. Prefer this method to short-ptr in places when nil is acceptable.

size-t-ptr clj

(size-t-ptr p)

(size-t-ptr p i)

Checks pointer p for safety with safe and casts it into SizeTPointer. Does not actually convert p into SizeTPointer!. It just does the type cast to satisfy Clojure's compiler. Useful when metadata for avoiding reflection is not easily added in code, such as in macros.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block. It DOES actually convert p into SizeTPointer!.

Prefer this method to size-t-ptr* in places when NULL pointer can cause harm. Prefer this method to size-t-ptr2 in places when nil is not allowed.

size-t-ptr* clj

(size-t-ptr* p)

(size-t-ptr* p i)

Casts pointer p into SizeTPointer. Useful when metadata for avoiding reflection is not easily added in code, such as in macros. Does not actually convert p into SizeTPointer!. It just does the type cast to satisfy Clojure's compiler.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block.

Prefer this method to size-t-ptr in places when you only care about satisfying the compiler, and don't care about NULL pointers.

size-t-ptr2 clj

(size-t-ptr2 p)

(size-t-ptr2 p i)

Checks pointer p for safety with safe2 and casts it into SizeTPointer. Does not actually convert p into SizeTPointer!. It just does the type cast to satisfy Clojure's compiler. Useful when metadata for avoiding reflection is not easily added in code, such as in macros.

If provided with index i, behaves like get-pointer. Negative i is allowed, but bee careful to stay within the original memory block. It DOES actually require p to be a SizeTPointer!.

Prefer this method to size-t-ptr* in places when NULL pointer can cause harm. Prefer this method to size-t-ptr in places when nil is acceptable.

total-physical-bytes clj

(total-physical-bytes)

The total amount of memory physically installed in the machine. The amount of physical-bytes can't be larger than this value. Returns 0 if the amount can't be determined.

tracked-bytes clj

(tracked-bytes)

The amount of memory currently tracked by JavaCPP deallocators.

type-pointer clj

(type-pointer t)

Returns the appropriate constructor for the pointer of type t, such as [[float-pointer]] for :float or float.

TypedPointerCreator clj protocol

clong-pointer clj

(clong-pointer this)

Converts an object into CLongPointer.

bool-pointer clj

(bool-pointer this)

Converts an object into BoolPointer.

pointer-pointer clj

(pointer-pointer this)

(pointer-pointer this charset)

Converts an object into PointerPointer.

double-pointer clj

(double-pointer this)

Converts an object into DoublePointer.

string-pointer clj

(string-pointer this)

(string-pointer this charset)

Converts an object into StringPointer.

function-pointer clj

(function-pointer this)

Converts an object into FunctionPointer.

short-pointer clj

(short-pointer this)

Converts an object into ShortPointer.

float-pointer clj

(float-pointer this)

Converts an object into FloatPointer.

char-pointer clj

(char-pointer this)

Converts an object into CharPointer.

long-pointer clj

(long-pointer this)

Converts an object into LongPointer.

size-t-pointer clj

(size-t-pointer this)

Converts an object into SizeTPointer.

byte-pointer clj

(byte-pointer this)

(byte-pointer this charset)

Converts an object into BytePointer.

int-pointer clj

(int-pointer this)

Converts an object into IntPointer.

keyword-pointer clj

(keyword-pointer this)

(keyword-pointer this charset)

Converts an object into KeywordPointer.

zero! clj

(zero! p)

Initializes all elements in the memory block managed by p to zero.