coffi.mem

Functions for managing native allocations, memory sessions, 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.

When writing code that manipulates a segment, it’s best practice to use with-acquired on the segment-session in order to ensure it won’t be released during its manipulation.

add-close-action!

(add-close-action! session action)

Adds a 0-arity function to be run when the session closes.

address-of

(address-of addressable)

Gets the address of a given segment.

This value can be used as an argument to functions which take a pointer.

address?

(address? addr)

Checks if an object is a memory address.

nil is considered an address.

align-of

(align-of type)

The alignment in bytes of the given type.

alloc

(alloc size)(alloc size session)(alloc size alignment session)

Allocates size bytes.

If a session is provided, the allocation will be reclaimed when it is closed.

alloc-instance

(alloc-instance type)(alloc-instance type session)

Allocates a memory segment for the given type.

alloc-with

(alloc-with allocator size)(alloc-with allocator size alignment)

Allocates size bytes using the allocator.

as-segment

(as-segment address size)(as-segment address size session)

Dereferences an address into a memory segment associated with the session.

big-endian

The big-endian ByteOrder.

See little-endian, native-endian.

byte-layout

The MemoryLayout for a byte in native-endian ByteOrder.

c-layout

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

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

clone-segment

(clone-segment segment)(clone-segment segment session)

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

connected-scope

deprecated

(connected-scope)

Constructs a new scope to reclaim all connected resources at once.

The scope 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 scope cannot be closed, and therefore should not be created in a with-open clause.

connected-session

(connected-session)

Constructs a new memory session to reclaim all connected resources at once.

The session 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 session cannot be closed, and therefore should not be created in a with-open clause.

copy-segment

(copy-segment dest src)

Copies the content to dest from src.

Returns dest.

defalias

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

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

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

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*.

Implementations of this should be inside a with-acquired block for the the segment’s session if they perform multiple memory operations.

double-alignment

The alignment in bytes of a c-sized double.

double-layout

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

double-size

The size in bytes of a c-sized double.

float-alignment

The alignment in bytes of a c-sized float.

float-layout

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

float-size

The size in bytes of a c-sized float.

global-scope

deprecated

(global-scope)

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

This scope 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.

global-session

(global-session)

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

This session 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

The alignment in bytes of a c-sized int.

int-layout

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

int-size

The size in bytes of a c-sized int.

java-layout

(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

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

little-endian

The little-endian ByteOrder.

See big-endian, native-endian

long-alignment

The alignment in bytes of a c-sized long.

long-layout

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

long-size

The size in bytes of a c-sized long.

native-endian

The ByteOrder for the native endianness of the current hardware.

See big-endian, little-endian.

null?

(null? addr)

Checks if a memory address is null.

pointer-alignment

The alignment in bytes of a c-sized pointer.

pointer-layout

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

pointer-size

The size in bytes of a c-sized pointer.

primitive-type

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

A set of all primitive types.

primitive?

(primitive? type)

A predicate to determine if a given type is primitive.

read-address

(read-address segment)(read-address segment offset)

Reads a MemoryAddress from the segment, at an optional offset.

read-byte

(read-byte segment)(read-byte segment offset)

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

read-char

(read-char segment)(read-char segment offset)

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

read-double

(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

(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

(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

(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

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

scope-allocator

deprecated

(scope-allocator scope)

Constructs a segment allocator from the given scope.

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.

segment-scope

deprecated

(segment-scope segment)

Gets the scope used to construct the segment.

segment-session

(segment-session segment)

Gets the memory session used to construct the segment.

seq-of

(seq-of type segment)

Constructs a lazy sequence of type elements deserialized from segment.

serialize

(serialize obj type)(serialize obj type session)

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*

multimethod

Constructs a serialized version of the obj and returns it.

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

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

serialize-into

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 session, 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.

Implementations of this should be inside a with-acquired block for the session if they perform multiple memory operations.

session-allocator

(session-allocator session)

Constructs a segment allocator from the given session.

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.

shared-scope

deprecated

(shared-scope)

Constructs a new shared scope.

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

shared-session

(shared-session)(shared-session cleaner)

Constructs a new shared memory session.

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

short-alignment

The alignment in bytes of a c-sized short.

short-layout

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

short-size

The size in bytes of a c-sized short.

size-of

(size-of type)

The size in bytes of the given type.

slice

(slice segment offset)(slice segment offset size)

Get a slice over the segment with the given offset.

slice-into

(slice-into address segment)(slice-into address segment size)

Get a slice into the segment starting at the address.

slice-segments

(slice-segments segment size)

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

stack-scope

deprecated

(stack-scope)

Constructs a new scope for use only in this thread.

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

stack-session

(stack-session)(stack-session cleaner)

Constructs a new session for use only in this thread.

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

with-acquired

macro

(with-acquired sessions & body)

Acquires one or more sessions until the body completes.

This is only necessary to do on shared sessions, however if you are operating on an arbitrary passed session, it is best practice to wrap code that interacts with it wrapped in this.

with-offset

(with-offset address offset)

Get a new address offset from the old address.

write-address

(write-address segment value)(write-address segment offset value)

Writes a MemoryAddress to the segment, at an optional offset.

write-byte

(write-byte segment value)(write-byte segment offset value)

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

write-char

(write-char segment value)(write-char segment offset value)

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

write-double

(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

(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

(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

(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

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