tur/forms/unsafe

(unsafe body ...)

run code that uses the unsafe builtins.

Evaluates the body forms in order and returns the last one's value. Inside it, the builtins on this page and calls to #fx{Unsafe} functions are allowed. The block discharges the Unsafe effect: a function whose unsafe code is all inside (unsafe ...) has no Unsafe in its row, so a safe wrapper over an unsafe primitive is an ordinary function to its callers. A function annotated #fx{Unsafe} gets the same permission for its whole body, and its callers need a block of their own.

Lints: an empty block warns; a block of more than 20 forms warns (change the limit with --lint-unsafe-max-lines=N); --lint-unsafe also warns on a nested block.

(unsafe (+ 1 2))  ; => 3

(raw-malloc [size :int] :ptr<void>)

allocate uninitialized memory.

C's malloc. Release the block with raw-free. The result is move-typed; see the module notes.

(let [p (raw-malloc 8)] (ptr-write p 42) (let [v (ptr-deref p)] (raw-free p) v))  ; => 42

(raw-free [p :ptr<void>] :nil)

release memory from raw-malloc or raw-realloc.

C's free. A null pointer is a no-op; freeing anything else twice is undefined behaviour.

(let [p (raw-malloc 8)] (raw-free p))

(raw-realloc [p :ptr<void> size :int] :ptr<void>)

resize a block, keeping its contents.

C's realloc: the block may move, so use the returned pointer and not p.

(let [p (raw-realloc (raw-malloc 8) 64)] (array-set-unchecked p 7 3) (let [v (array-get-unchecked p 7)] (raw-free p) v))  ; => 3

(raw-memcpy [dest :ptr<void> src :ptr<void> n :int] :nil)

copy bytes between two blocks.

C's memcpy: the blocks must not overlap.

(let [p (raw-malloc 8) q (raw-malloc 8)] (ptr-write p 1234) (raw-memcpy q p 8) (let [v (ptr-deref q)] (raw-free p) (raw-free q) v))  ; => 1234

(raw-memset [dest :ptr<void> byte :int n :int] :nil)

fill bytes with one value.

C's memset: the low 8 bits of byte are written to each of the n bytes at dest.

(let [p (raw-malloc 16)] (raw-memset p 0 16) (let [v (array-get-unchecked p 1)] (raw-free p) v))  ; => 0

(ptr-deref [p :ptr<void>] :int)

read the 8-byte word a pointer points at.

*(int64_t *)p. The word is returned as an int, whatever was stored.

(let [x 41] (ptr-deref (ptr-of x)))  ; => 41

(ptr-write [p :ptr<void> value :int] :nil)

store an 8-byte word through a pointer.

*(int64_t *)p = value.

(let [p (raw-malloc 8)] (ptr-write p 7) (let [v (ptr-deref p)] (raw-free p) v))  ; => 7

(ptr-add [p :ptr<void> n :int] :ptr<void>)

advance a pointer by a number of BYTES.

(char *)p + n: the offset is in bytes, not words -- the second word of a block is (ptr-add p 8).

(let [p (raw-malloc 16)] (ptr-write (ptr-add p 8) 7) (let [v (array-get-unchecked p 1)] (raw-free p) v))  ; => 7

(ptr-sub [p :ptr<void> n :int] :ptr<void>)

move a pointer back by a number of BYTES.

(char *)p - n.

(let [p (raw-malloc 16)] (ptr-write p 5) (let [v (ptr-deref (ptr-sub (ptr-add p 8) 8))] (raw-free p) v))  ; => 5

(ptr-null? [p :ptr<void>] :bool)

is a pointer null?

(let [p (raw-malloc 8)] (let [n (ptr-null? p)] (raw-free p) n))  ; => false

(ptr-of [x :T] :ptr<void>)

the address of a value.

C's &. The pointer is good only while the value's storage is live -- the address of a local is dangling once its scope ends.

(let [x 41] (ptr-deref (ptr-of x)))  ; => 41

(array-get-unchecked [p :ptr<void> i :int] :int)

read word i of a block, with no bounds check.

((int64_t *)p)[i]: the index counts 8-byte words, not bytes.

(let [p (raw-malloc 24)] (array-set-unchecked p 2 99) (let [v (array-get-unchecked p 2)] (raw-free p) v))  ; => 99

(array-set-unchecked [p :ptr<void> i :int value :int] :nil)

write word i of a block, with no bounds check.

((int64_t *)p)[i] = value.

(let [p (raw-malloc 24)] (array-set-unchecked p 0 1) (let [v (ptr-deref p)] (raw-free p) v))  ; => 1

(unsafe-cast x type)

a C cast to int.

(int64_t)x. The target type is required but not read yet: the result is always an int, converted as C converts (a float truncates, true is 1).

(unsafe-cast true :int)  ; => 1

(reinterpret x type)

reinterpret a value's bits as another type.

The same bit copy as transmute: the target type must have the same size as x's, checked at compile time, and the result has the target type. Nothing is converted -- (reinterpret 1.5 :int) is 1.5's IEEE-754 bit pattern, not 1.

(reinterpret 1.5 :int)  ; => 4609434218613702656

(transmute x type)

reinterpret a value's bits as another type.

The target type must have the same size as x's, checked at compile time ((transmute (:: 1 :int32) :int) is an error), and the result has the target type. The bits are copied, not converted: (transmute 1.5 :int) is 4609434218613702656, and transmute back to :float gives 1.5. float->bits / bits->float (tur/bits) are the same copy outside an unsafe block. For the NUMBER, use unsafe-cast or float->int.

(transmute 4609434218613702656 :float)  ; => 1.5

(c-call f args ...)

call a C function declared with extern-c.

The function must be in scope from an extern-c declaration. The result is typed int, whatever the declaration says; calling the extern-c name directly keeps its declared types and needs no (unsafe ...).

(extern-c labs [x : int] : int)
(unsafe (c-call labs -5))  ; prints 5

(dlopen [path :cstr] :ptr<void>)

load a shared library at run time.

POSIX dlopen(path, RTLD_LAZY). Look symbols up with dlsym and call them through call-ptr; see ffi-guide. Needs the FFI capability under a sandboxed interpreter.

(let [h (dlopen "libm.so.6")] (let [ok (not (ptr-null? h))] (dlclose h) ok))  ; => true  ; doctest: needs libm.so.6 (Linux)

(dlsym [h :ptr<void> name :cstr] :ptr<void>)

look a symbol up in a loaded library.

POSIX dlsym.

(let [h (dlopen "libm.so.6")] (let [ok (not (ptr-null? (dlsym h "cos")))] (dlclose h) ok))  ; => true  ; doctest: needs libm.so.6 (Linux)

(dlclose [h :ptr<void>] :int)

release a library handle from dlopen.

POSIX dlclose. Addresses from dlsym on it may be invalid afterwards.

(dlclose (dlopen "libm.so.6"))  ; => 0  ; doctest: needs libm.so.6 (Linux)