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.
show-trapped-errors
If you have hidden trapped errors they can be toggled back to being
showed again using this function.
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 |
|
|
((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
|
|
|
((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) ")"
|
|
|
((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
|
|
|
((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 (
|
|
|
((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
|
|
|
((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-
|
|
|
((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
|
|
|
((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
|
|
|
((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
|
|
|
((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)
|
|
|
((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
|
|
|
((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)))
|
|
|
((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
|
|
|
((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.")) (
|
|
|
((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
|
|
|
((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
|
|
|
((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
|
|
|
((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))
|
|
|
((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)
|
|
|
((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))
|
|
|
((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
|
|
|
((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
|
|
|
((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
|
|
|
((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
|
|
|
((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
|
|
|
((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
|
|
|
((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
|
|
|
((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))
|
|
|
((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
|
|
|
((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
|
|
|
((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
|
|
|
((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)))
|
|
local-env-get
local-env-get can be used to reify, turn into value, the
local environment.
| 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.
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.
is-always-gc
The is-always-gc predicate is true if LBM is built with
the LBM_ALWAYS_GC debug flag.
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.
mem-longest-free
mem-longest-free returns the length in words of the
longest consecutive sequence of free words in the LBM memory.
mem-size
mem-size returns the size of the LBM memory.
lbm-heap-state
lbm-heap-state can be used to query information about
heap usage.
| Example | Result |
(lbm-heap-state 'get-heap-size)
|
|
(lbm-heap-state 'get-heap-bytes)
|
|
(lbm-heap-state 'get-num-alloc-cells)
|
|
(lbm-heap-state 'get-num-alloc-arrays)
|
|
(lbm-heap-state 'get-gc-num)
|
|
(lbm-heap-state 'get-gc-num-marked)
|
|
(lbm-heap-state 'get-gc-num-recovered-cells)
|
|
(lbm-heap-state 'get-gc-num-recovered-arrays)
|
|
(lbm-heap-state 'get-gc-num-least-free)
|
|
(lbm-heap-state 'get-gc-num-last-free)
|
|
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.
Symbol table
symtab-size
symtab-size returns the size of the symbol table in
bytes.
symtab-size-flash
symtab-size-flash returns the size in bytes of the
portion of the symbol table that is stored in flash.
symtab-size-names
symtab-size-names returns the size in bytes of the
string names stored in the symbol table.
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)
|
|
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)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
("hello world" (1 2 3) apa)
|
Version
lbm-version
lbm-version returns the version of the lbm runtime
system.
is-64bit
is-64bit returns true if a 64bit version of lbm is
running.
word-size
word-size returns 4 on 32bit LBM and 8 on 64bits.
This document was generated by LispBM version 0.34.2