coffi.mem — org.suskalo/coffi 1.0.486

Functions for managing native allocations, memory arenas, and (de)serialization.

For any new type to be implemented, three multimethods must be overriden, but which three depends on the native representation of the type.

If the native representation of the type is a primitive (whether or not other data beyond the primitive is associated with it, as e.g. a pointer), then primitive-type must be overriden to return which primitive type it is serialized as, then serialize* and deserialize* should be overriden.

If the native representation of the type is a composite type, like a union, struct, or array, then c-layout must be overriden to return the native layout of the type, and serialize-into and deserialize-from should be overriden to allow marshaling values of the type into and out of memory segments.

address-of clj

(address-of addressable)

Gets the address of a given segment as a number.

address? clj

(address? addr)

Checks if an object is a memory address.

nil is considered an address.

align-of clj

(align-of type)

The alignment in bytes of the given type.

alloc clj

(alloc size)

(alloc size arena)

(alloc size alignment arena)

Allocates size bytes.

If an arena is provided, the allocation will be reclaimed when it is closed.

alloc-instance clj

(alloc-instance type)

(alloc-instance type arena)

Allocates a memory segment for the given type.

alloc-with clj

(alloc-with allocator size)

(alloc-with allocator size alignment)

Allocates size bytes using the allocator.

arena-allocator clj

(arena-allocator arena)

Constructs a [[SegmentAllocator]] from the given [[Arena]].

This is primarily used when working with unwrapped downcall functions. When a downcall function returns a non-primitive type, it must be provided with an allocator.

as-segment clj

(as-segment address)

(as-segment address size)

(as-segment address size arena)

(as-segment address size arena cleanup)

Dereferences an address into a memory segment associated with the arena (default global).

auto-arena clj

(auto-arena)

Constructs a new memory arena that is managed by the garbage collector.

The arena may be shared across threads, and all resources created with it will be cleaned up at the same time, when all references have been collected.

This type of arena cannot be closed, and therefore should not be created in a [[with-open]] clause.

big-endian clj

The big-endian [[ByteOrder]].

See little-endian, native-endian.

byte-layout clj

The [[MemoryLayout]] for a byte in native-endian [[ByteOrder]].

c-layout clj multimethod

Gets the layout object for a given type.

If a type is primitive it will return the appropriate primitive layout (see [[c-prim-layout]]).

Otherwise, it should return a [[GroupLayout]] for the given type.

char-layout clj

The [[MemoryLayout]] for a c-sized char in native-endian [[ByteOrder]].

clone-segment clj

(clone-segment segment)

(clone-segment segment arena)

Clones the content of segment into a new segment of the same size.

confined-arena clj

(confined-arena)

Constructs a new arena for use only in this thread.

The memory allocated within this arena is cheap to allocate, like a native stack.

The memory allocated within this arena will be cleared once it is closed, so it is usually a good idea to create it in a [[with-open]] clause.

copy-segment clj

(copy-segment dest src)

Copies the content to dest from src.

Returns dest.

defalias clj macro

(defalias new-type aliased-type)

Defines a type alias from new-type to aliased-type.

This creates needed serialization and deserialization implementations for the aliased type.

deserialize clj

(deserialize obj type)

Deserializes an arbitrary type.

For types which have a primitive representation, this deserializes the primitive representation. For types which do not, this deserializes out of a segment.

deserialize* clj multimethod

Deserializes a primitive object into a Clojure data structure.

This is intended for use with types that are returned as a primitive but which need additional processing before they can be returned.

deserialize-from clj multimethod

Deserializes the given segment into a Clojure data structure.

For types that serialize to primitives, a default implementation will deserialize the primitive before calling deserialize*.

double-alignment clj

The alignment in bytes of a c-sized double.

double-layout clj

The [[MemoryLayout]] for a c-sized double in native-endian [[ByteOrder]].

double-size clj

The size in bytes of a c-sized double.

float-alignment clj

The alignment in bytes of a c-sized float.

float-layout clj

The [[MemoryLayout]] for a c-sized float in native-endian [[ByteOrder]].

float-size clj

The size in bytes of a c-sized float.

global-arena clj

(global-arena)

Constructs the global arena, which will never reclaim its resources.

This arena may be shared across threads, but is intended mainly in cases where memory is allocated with alloc but is either never freed or whose management is relinquished to a native library, such as when returned from a callback.

int-alignment clj

The alignment in bytes of a c-sized int.

int-layout clj

The [[MemoryLayout]] for a c-sized int in native-endian [[ByteOrder]].

int-size clj

The size in bytes of a c-sized int.

java-layout clj

(java-layout type)

Gets the Java class to an argument of this type for a method handle.

If a type serializes to a primitive it returns return a Java primitive type. Otherwise, it returns [[MemorySegment]].

java-prim-layout clj

Map of primitive type names to the Java types for a method handle.

little-endian clj

The little-endian [[ByteOrder]].

See big-endian, native-endian

long-alignment clj

The alignment in bytes of a c-sized long.

long-layout clj

The [[MemoryLayout]] for a c-sized long in native-endian [[ByteOrder]].

long-size clj

The size in bytes of a c-sized long.

native-endian clj

The [[ByteOrder]] for the native endianness of the current hardware.

See big-endian, little-endian.

null clj

The NULL pointer object.

While this object is safe to pass to functions which serialize to a pointer, it's generally encouraged to simply pass nil. This value primarily exists to make it easier to write custom types with a primitive pointer representation.

null? clj

(null? addr)

Checks if a memory address is null.

pointer-alignment clj

The alignment in bytes of a c-sized pointer.

pointer-layout clj

The [[MemoryLayout]] for a native pointer in native-endian [[ByteOrder]].

pointer-size clj

The size in bytes of a c-sized pointer.

primitive-type clj multimethod

Gets the primitive type that is used to pass as an argument for the type.

This is for objects which are passed to native functions as primitive types, but which need additional logic to be performed during serialization and deserialization.

Implementations of this method should take into account that type arguments may not always be evaluated before passing to this function.

Returns nil for any type which does not have a primitive representation.

primitive-types clj

A set of all primitive types.

primitive? clj

(primitive? type)

A predicate to determine if a given type is primitive.

read-address clj

(read-address segment)

(read-address segment offset)

Reads an address from the segment, at an optional offset, wrapped in a [[MemorySegment]].

read-byte clj

(read-byte segment)

(read-byte segment offset)

Reads a [[byte]] from the segment, at an optional offset.

read-char clj

(read-char segment)

(read-char segment offset)

Reads a [[char]] from the segment, at an optional offset.

read-double clj

(read-double segment)

(read-double segment offset)

(read-double segment offset byte-order)

Reads a [[double]] from the segment, at an optional offset.

If byte-order is not provided, it defaults to native-endian.

read-float clj

(read-float segment)

(read-float segment offset)

(read-float segment offset byte-order)

Reads a [[float]] from the segment, at an optional offset.

If byte-order is not provided, it defaults to native-endian.

read-int clj

(read-int segment)

(read-int segment offset)

(read-int segment offset byte-order)

Reads a [[int]] from the segment, at an optional offset.

If byte-order is not provided, it defaults to native-endian.

read-long clj

(read-long segment)

(read-long segment offset)

(read-long segment offset byte-order)

Reads a [[long]] from the segment, at an optional offset.

If byte-order is not provided, it defaults to native-endian.

read-short clj

(read-short segment)

(read-short segment offset)

(read-short segment offset byte-order)

Reads a [[short]] from the segment, at an optional offset.

If byte-order is not provided, it defaults to native-endian.

reinterpret clj

(reinterpret segment size)

(reinterpret segment size arena)

(reinterpret segment size arena cleanup)

Reinterprets the segment as having the passed size.

If arena is passed, the scope of the segment is associated with the arena, as well as its access constraints. If cleanup is passed, it will be a 1-argument function of a fresh memory segment backed by the same memory as the returned segment which should perform any required cleanup operations. It will be called when the arena is closed.

seq-of clj

(seq-of type segment)

Constructs a lazy sequence of type elements deserialized from segment.

serialize clj

(serialize obj type)

(serialize obj type arena)

Serializes an arbitrary type.

For types which have a primitive representation, this serializes into that representation. For types which do not, it allocates a new segment and serializes into that.

serialize* clj multimethod

Constructs a serialized version of the obj and returns it.

Any new allocations made during the serialization should be tied to the given arena, except in extenuating circumstances.

This method should only be implemented for types that serialize to primitives.

serialize-into clj multimethod

Writes a serialized version of the obj to the given segment.

Any new allocations made during the serialization should be tied to the given arena, except in extenuating circumstances.

This method should be implemented for any type which does not override c-layout.

For any other type, this will serialize it as serialize* before writing the result value into the segment.

shared-arena clj

(shared-arena)

Constructs a new shared memory arena.

This arena can be shared across threads and memory allocated in it will only be cleaned up once any thread accessing the arena closes it.

short-alignment clj

The alignment in bytes of a c-sized short.

short-layout clj

The [[MemoryLayout]] for a c-sized short in native-endian [[ByteOrder]].

short-size clj

The size in bytes of a c-sized short.

size-of clj

(size-of type)

The size in bytes of the given type.

slice clj

(slice segment offset)

(slice segment offset size)

Get a slice over the segment with the given offset.

slice-segments clj

(slice-segments segment size)

Constructs a lazy seq of size-length memory segments, sliced from segment.

write-address clj

(write-address segment value)

(write-address segment offset value)

Writes the address of the [[MemorySegment]] value to the segment, at an optional offset.

write-byte clj

(write-byte segment value)

(write-byte segment offset value)

Writes a [[byte]] to the segment, at an optional offset.

write-char clj

(write-char segment value)

(write-char segment offset value)

Writes a [[char]] to the segment, at an optional offset.

write-double clj

(write-double segment value)

(write-double segment offset value)

(write-double segment offset byte-order value)

Writes a [[double]] to the segment, at an optional offset.

If byte-order is not provided, it defaults to native-endian.

write-float clj

(write-float segment value)

(write-float segment offset value)

(write-float segment offset byte-order value)

Writes a [[float]] to the segment, at an optional offset.

If byte-order is not provided, it defaults to native-endian.

write-int clj

(write-int segment value)

(write-int segment offset value)

(write-int segment offset byte-order value)

Writes a [[int]] to the segment, at an optional offset.

If byte-order is not provided, it defaults to native-endian.

write-long clj

(write-long segment value)

(write-long segment offset value)

(write-long segment offset byte-order value)

Writes a [[long]] to the segment, at an optional offset.

If byte-order is not provided, it defaults to native-endian.

write-short clj

(write-short segment value)

(write-short segment offset value)

(write-short segment offset byte-order value)

Writes a [[short]] to the segment, at an optional offset.

If byte-order is not provided, it defaults to native-endian.