← Back to Reference Manual Index
Core LispBM
Runtimeref
# LispBM Runtime Extensions Reference Manual

The runtime extensions, if present, can be either compiled in a minimal or a full mode. In the minimal mode only set-eval-quota is present. Minimal mode is the default when compiling LBM. To get the full mode the -DFULL_RTS_LIB flag must be used when compiling.

Errors

hide-trapped-error

The default behavior is to print error messages even if the error is trapped. Trapped errors can be hidden by calling this function at the beginning of a program.

Example Result
(hide-trapped-error)
t

show-trapped-errors

If you have hidden trapped errors they can be toggled back to being showed again using this function.

Example Result
(show-trapped-error)
t

Environments

env-get

env-get can be used to reify, turn into value, parts of the global environment. The global environment is stored as a hashtable and an index into this hashtable is used to extract the bindings stored under that hash.

Example Result
(env-get 0)
((chapter-environments section 2 "Environments" ((newline (section 3 "env-get" ((para ("`env-get` can be used to reify, turn into value, parts of the global environment." "The global environment is stored as a hashtable and an index into this hashtable" "i
(env-get 1)
((symbol-table-size newline (section 3 "symtab-size" ((para ("`symtab-size` returns the size of the symbol table in bytes.")) (code ((symtab-size))) nil)) newline hline) (code-entry-ref closure (code) (str-merge "[`" code "`](#" (or (rest-args 0) code) ")"
(env-get 2)
((symbol-table-size-flash newline (section 3 "symtab-size-flash" ((para ("`symtab-size-flash` returns the size in bytes of the portion of the symbol table" "that is stored in flash.")) (code ((symtab-size-flash))) nil)) newline hline) (intersperse closure 
(env-get 3)
((symbol-table-size-names newline (section 3 "symtab-size-names" ((para ("`symtab-size-names` returns the size in bytes of the string names stored in" "the symbol table.")) (code ((symtab-size-names))) nil)) newline hline) (bullet closure (ss) (verb (map (
(env-get 4)
((symbol-table-size-names-flash newline (section 3 "symtab-size-names-flash" ((para ("`symtab-size-names` returns the size in bytes of the string names stored in" "the symbol table in flash.")) (code ((symtab-size-names-flash))) nil)) newline hline) (set-p
(env-get 5)
((chapter-symboltable section 2 "Symbol table" ((newline (section 3 "symtab-size" ((para ("`symtab-size` returns the size of the symbol table in bytes.")) (code ((symtab-size))) nil)) newline hline) (newline (section 3 "symtab-size-flash" ((para ("`symtab-
(env-get 6)
((version newline (section 3 "lbm-version" ((para ("`lbm-version` returns the version of the lbm runtime system.")) (code ((lbm-version))) nil)) newline hline) (code-raw closure (c) (list (quote code-raw) c) nil) (render-program-disp-res-pairs closure (ren
(env-get 7)
((endian newline (section 3 "lbm-endian" ((para ("`lbm-endian` returns the endianness of the system lbm is running on.")) (code ((lbm-endian))) nil)) newline hline) (defun macro (name args body) (me-defun name args body)) (render-code-raw-table closure (re
(env-get 8)
((arch newline (section 3 "is-64bit" ((para ("`is-64bit` returns true if a 64bit version of lbm is running.")) (code ((is-64bit))) nil)) newline hline) (code-png closure (img colors c) (list (quote code-png) img colors c) nil) (pretty-ind closure (n c) (ma
(env-get 9)
((word newline (section 3 "word-size" ((para ("`word-size` returns 4 on 32bit LBM  and 8 on 64bits.")) (code ((word-size))) nil)) newline hline) (render-code-res-pairs closure (rend cs) (match cs (nil t) (((? x) ? xs) (let ((x-str (if (is-read-eval-txt x) 
(env-get 10)
((chapter-versioning section 2 "Version" ((newline (section 3 "lbm-version" ((para ("`lbm-version` returns the version of the lbm runtime system.")) (code ((lbm-version))) nil)) newline hline) (newline (section 3 "is-64bit" ((para ("`is-64bit` returns true
(env-get 11)
((hide-em newline (section 3 "hide-trapped-error" ((para ("The default behavior is to print error messages even if the error is trapped." "Trapped errors can be hidden by calling this function at the beginning of a program.")) (code ((hide-trapped-error)))
(env-get 12)
((show-em newline (section 3 "show-trapped-errors" ((para ("If you have hidden trapped errors they can be toggled back to being showed again" "using this function.")) (code ((show-trapped-error))) nil)) newline hline) (chapter-scheduling section 2 "Schedul
(env-get 13)
((chapter-errors section 2 "Errors" ((newline (section 3 "hide-trapped-error" ((para ("The default behavior is to print error messages even if the error is trapped." "Trapped errors can be hidden by calling this function at the beginning of a program.")) (
(env-get 14)
((manual (section 1 "LispBM Runtime Extensions Reference Manual" ((para ("The runtime extensions, if present, can be either compiled" "in a minimal or a full mode." "In the minimal mode only `set-eval-quota` is present." "Minimal mode is the default when c
(env-get 15)
((render-manual closure nil (let ((h (fopen "runtimeref.md" "w")) (r (lambda (s) (fwrite-str h s)))) (progn (gc) (var t0 (systime)) (render r manual) (print "Runtime reference manual was generated in " (secs-since t0) " seconds"))) nil) (program-gif closur
(env-get 16)
((chapter-threads section 2 "Threads" ((newline (section 3 "mailbox-get" ((para ("`mailbox-get` returns the mailbox contents of a thread as a list." "The form of a `mailbox-get` expression is `(mailbox-get pid)`." "Note that `mailbox-get` does **NOT** empt
(env-get 17)
((num-free newline (section 3 "mem-num-free" ((para ("`mem-num-free` returns the number of free words in the LBM memory." "This is the memory where arrays and strings are stored.")) (code ((mem-num-free))) nil)) newline hline))
(env-get 18)
((longest-free newline (section 3 "mem-longest-free" ((para ("`mem-longest-free` returns the length in words of the longest" "consecutive sequence of free words in the LBM memory.")) (code ((mem-num-free))) nil)) newline hline) (table closure (header data)
(env-get 19)
((memory-size newline (section 3 "mem-size" ((para ("`mem-size` returns the size of the LBM memory.")) (code ((mem-size))) nil)) newline hline) (semantic-step closure (c1 c2 prop) (list (quote semantic-step) c1 c2 prop) nil))
(env-get 20)
((heap-state newline (section 3 "lbm-heap-state" ((para ("`lbm-heap-state` can be used to query information about heap usage.")) (code ((lbm-heap-state (quote get-heap-size)) (lbm-heap-state (quote get-heap-bytes)) (lbm-heap-state (quote get-num-alloc-cell
(env-get 21)
((chapter-memory section 2 "Memory" ((newline (section 3 "mem-num-free" ((para ("`mem-num-free` returns the number of free words in the LBM memory." "This is the memory where arrays and strings are stored.")) (code ((mem-num-free))) nil)) newline hline) (n
(env-get 22)
((gc-stack newline (section 3 "set-gc-stack-size" ((para ("With `set-gc-stack-size` you can change the size of the stack used for heap traversal" "by the garbage collector.")) (code ((set-gc-stack-size 100))) nil)) newline hline) (png-count . 0) (pretty-al
(env-get 23)
((gc-is-always-gc newline (section 3 "is-always-gc" ((para ("The `is-always-gc` predicate is true if LBM is built with the LBM_ALWAYS_GC debug flag.")) (code ((is-always-gc))) nil)) newline hline) (pic-prefix . [0]) (str-merge-list closure (strings) (match
(env-get 24)
((chapter-gc section 2 "GC" ((newline (section 3 "set-gc-stack-size" ((para ("With `set-gc-stack-size` you can change the size of the stack used for heap traversal" "by the garbage collector.")) (code ((set-gc-stack-size 100))) nil)) newline hline) (newlin
(env-get 25)
((environment-get newline (section 3 "env-get" ((para ("`env-get` can be used to reify, turn into value, parts of the global environment." "The global environment is stored as a hashtable and an index into this hashtable" "is used to extract the bindings s
(env-get 26)
((environment-set newline (section 3 "env-set" ((para ("`env-set` destructively sets an entry in the global environment hashtable.")) (program (((if (eq (env-get 1) nil) (env-set 1 (list (quote (a . 75))))) (env-get 1)))) (para ("Note that in the example c
(env-get 27)
((end) (render-code-table closure (rend c) (progn (rend "<table>\n") (rend "<tr>\n") (rend "<td> Example </td> <td> Result </td>\n") (rend "</tr>\n") (render-code-res-pairs rend c) (rend "</table>\n\n")) nil) (frame-max . 0))
(env-get 28)
((environment-drop newline (section 3 "env-drop" ((para ("drop a binding from an environment.")) (code ((env-drop (quote a) (quote ((a . 10) (b . 20) (c . 30)))))) nil)) newline hline) (s+ closure (s ss) (cons s ss) nil) (render-it closure (rend ss) (match
(env-get 29)
((ref-entry closure (str strings-or-tags) (let ((tags (and (rest-args 0) strings-or-tags)) (strings (or (rest-args 0) strings-or-tags))) (list (quote newline) (if tags (tagged-section 3 str tags strings) (section 3 str strings)) (quote newline) (quote hlin
(env-get 30)
((local-environment-get newline (section 3 "local-env-get" ((para ("`local-env-get` can be used to reify, turn into value, the local environment.")) (code ((local-env-get))) (program (((let ((a 50)) (local-env-get))))) nil)) newline hline) (render closure 
(env-get 31)
((global-environment-size newline (section 3 "global-env-size" ((para ("Get the size (in number of bindings) of the global env.")) (code ((global-env-size))) nil)) newline hline) (render-code-disp-pairs closure (rend cs) (match cs (nil t) (((? x) ? xs) (le

env-set

env-set destructively sets an entry in the global environment hashtable.

Example Result
(if (eq (env-get 1) nil) (env-set 1 (list '(a . 75))))
(env-get 1)
((symbol-table-size newline (section 3 "symtab-size" ((para ("`symtab-size` returns the size of the symbol table in bytes.")) (code ((symtab-size))) nil)) newline hline) (code-entry-ref closure (code) (str-merge "[`" code "`](#" (or (rest-args 0) code) ")"

Note that in the example code above there is no guarantee that the symbol a actually hashes to index 1 in the environment table. So a is most likely impossible to look up from this environment. The use case for env-set and env-get are rather that they are together. Use env-get to extract index i from the table, then modify it in some way and end by using env-set to the same index i.


env-drop

drop a binding from an environment.

Example Result
(env-drop 'a '((a . 10) (b . 20) (c . 30)))
((b . 20) (c . 30))

local-env-get

local-env-get can be used to reify, turn into value, the local environment.

Example Result
(local-env-get)
nil
Example Result
(let ((a 50))
     (local-env-get))
((a . 50) (res-str . $placeholder) (res (a . 50) (res-str . $placeholder) (res (a . 50) (res-str . $placeholder) (res (a . 50) (res-str . $placeholder) (res (a . 50) (res-str . $placeholder) (res (a . 50) (res-str . $placeholder) (res (a . 50) (res-str . $

global-env-size

Get the size (in number of bindings) of the global env.

Example Result
(global-env-size)
104u

GC

set-gc-stack-size

With set-gc-stack-size you can change the size of the stack used for heap traversal by the garbage collector.

Example Result
(set-gc-stack-size 100)
t

is-always-gc

The is-always-gc predicate is true if LBM is built with the LBM_ALWAYS_GC debug flag.

Example Result
(is-always-gc)
nil

Memory

mem-num-free

mem-num-free returns the number of free words in the LBM memory. This is the memory where arrays and strings are stored.

Example Result
(mem-num-free)
254925

mem-longest-free

mem-longest-free returns the length in words of the longest consecutive sequence of free words in the LBM memory.

Example Result
(mem-num-free)
254861

mem-size

mem-size returns the size of the LBM memory.

Example Result
(mem-size)
262144

lbm-heap-state

lbm-heap-state can be used to query information about heap usage.

Example Result
(lbm-heap-state 'get-heap-size)
100000u
(lbm-heap-state 'get-heap-bytes)
800000u
(lbm-heap-state 'get-num-alloc-cells)
13803u
(lbm-heap-state 'get-num-alloc-arrays)
771u
(lbm-heap-state 'get-gc-num)
1u
(lbm-heap-state 'get-gc-num-marked)
4609u
(lbm-heap-state 'get-gc-num-recovered-cells)
95391u
(lbm-heap-state 'get-gc-num-recovered-arrays)
0u
(lbm-heap-state 'get-gc-num-least-free)
95391u
(lbm-heap-state 'get-gc-num-last-free)
95391u

Scheduling

set-eval-quota

set-eval-quota sets the number of evaluation steps that is given to each context when given turn to execute by the round-robin scheduler.

Example Result
(set-eval-quota 30)
t

Symbol table

symtab-size

symtab-size returns the size of the symbol table in bytes.

Example Result
(symtab-size)
0u

symtab-size-flash

symtab-size-flash returns the size in bytes of the portion of the symbol table that is stored in flash.

Example Result
(symtab-size-flash)
2196u

symtab-size-names

symtab-size-names returns the size in bytes of the string names stored in the symbol table.

Example Result
(symtab-size-names)
0u

symtab-size-names-flash

symtab-size-names returns the size in bytes of the string names stored in the symbol table in flash.

Example Result
(symtab-size-names-flash)
2196u

Threads

mailbox-get

mailbox-get returns the mailbox contents of a thread as a list. The form of a mailbox-get expression is (mailbox-get pid). Note that mailbox-get does NOT empty the mailbox.

Example Result
(define f (lambda nil
            (progn 
                (sleep 1)
                (f))))
(closure nil 
  (progn 
      (sleep 1)
      (f))
  nil)
(define pid (spawn f))
14233
(send pid "hello world")
t
(send pid (list 1 2 3))
t
(send pid 'apa)
t
(mailbox-get pid)
("hello world" (1 2 3) apa)

Version

lbm-version

lbm-version returns the version of the lbm runtime system.

Example Result
(lbm-version)
(0 34 2)

is-64bit

is-64bit returns true if a 64bit version of lbm is running.

Example Result
(is-64bit)
nil

word-size

word-size returns 4 on 32bit LBM and 8 on 64bits.

Example Result
(word-size)
4

This document was generated by LispBM version 0.34.2