6.46.2 Allocating and freeing memory

The following bindings are exported by the libraries (vicare) and (vicare system $foreign) and reexported by the library (vicare ffi).

Function: malloc number-of-bytes

Function: guarded-malloc number-of-bytes

Interface to the C function malloc(), (libc)malloc. Allocate a block of memory number-of-bytes wide; number-of-bytes must be an exact integer in the range of the C language type size_t. If successful return a pointer object; if allocation fails raise a non–continuable exception with components: &who, &message, &out-of-memory-error.

Memory allocated by malloc must be released by free; memory allocated by guarded-malloc is automatically released whenever the returned pointer object is garbage collected.

Function: realloc memory number-of-bytes

Function: guarded-realloc memory number-of-bytes

Interface to the C function realloc(), (libc)realloc. Reallocate the block of memory referenced by memory to the new size number-of-bytes.

memory must be a pointer object or memory-block instance.

number-of-bytes must be an exact integer in the range of the C language type size_t.

If successful: mutate the pointer in memory to reference the new memory block and return memory itself; when memory is a memory-block: mutate the size field to number-of-bytes. If reallocation fails raise a non–continuable exception with components: &who, &message, &out-of-memory-error and leave untouched both memory and its referenced memory.

Memory allocated by realloc must be released by free, unless memory was already scheduled to be removed by the garbage collector; when guarded-realloc is used:

• When memory is a pointer object: the allocated memory is automatically released whenever the returned pointer object is garbage collected. If memory was already scheduled to be removed by the garbage collector: we should use realloc not guarded-realloc.
• When memory is an instance of memory-block: the allocated memory is automatically released by the garbage collector only if memory-block was built by make-memory-block/guarded.

Function: calloc number-of-elements element-size

Function: guarded-calloc number-of-elements element-size

Interface to the C function calloc(), (libc)calloc. Allocate and clear to zero a block of memory capable of holding number-of-elements each element-size wide; both the arguments must be exact integers in the range of the C language type size_t. If successful return a pointer object; if allocation fails raise a non–continuable exception with components: &who, &message, &out-of-memory-error.

Memory allocated by calloc must be released by free; memory allocated by guarded-calloc is automatically released whenever the returned pointer object is garbage collected.

Function: free memory

Release the memory referenced by memory, which must be either a pointer object returned by malloc(), realloc(), calloc() or a similar system procedure or an instance of memory-block. The pointer object in memory is mutated to reference the NULL pointer; when memory is a memory-block: the size field is also reset to zero.

If memory allocated by a guarding function is released by free: Vicare will not try to automatically release the old memory again.

If the pointer in memory is NULL nothing happens.

Function: with-local-storage lengths proc

Call proc with arguments being pointers to memory blocks allocated just for the dynamic extent of proc. The number and size of the memory blocks is determined by lengths, which must be a vector of non–negative fixnums.

NOTE We must not let control flow go through a call to with-local-storage with an escaping continuation.

#!r6rs
(import (rnrs)
  (prefix (vicare ffi) ffi.))

;; no allocated memory
(let ((a 1) (b 2))
  (ffi.with-local-storage '#()
    (lambda ()
      (+ a b 4))))
⇒ 7

;; allocate a single block of 4 bytes
(let ((a 1) (b 2))
  (ffi.with-local-storage '#(4)
    (lambda (&int32)
      (ffi.pointer-set-c-sint32! &int32 0 4)
      (+ a b (ffi.pointer-ref-c-sint32 &int32 0)))))
⇒ 7

;; allocate two blocks of 4 and 8 bytes
(let ((a 1) (b 2))
  (ffi.with-local-storage '#(4 8)
    (lambda (&int32 &int64)
      (ffi.pointer-set-c-sint32! &int32 0 4)
      (ffi.pointer-set-c-sint64! &int64 0 8)
      (+ a b
         (ffi.pointer-ref-c-sint32 &int32 0)
         (ffi.pointer-ref-c-sint64 &int64 0)))))
⇒ 15

The memory blocks are actually allocated on the stack of Vicare’s runtime.