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 |
|
|
((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) (render-program-disp-gif-p
|
|
|
((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) (str-merge-list closure (strings) (match strings (nil [0])
|
|
|
((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
|
|
|
((render closure (rend ss) (match ss (nil t) (((? x) ? xs) (progn (render-it rend x) (render rend xs))) ((? x) (print "RENDER ERROR: " x))) nil) (code-raw closure (c) (list (quote code-raw) c) nil))
|
|
|
((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) (pretty-aligned-on-top closure (n cs) (match cs (nil [0]) (((? x) ? xs)
|
|
|
((pretty closure (toplevel ind c) (if (and toplevel (list? c)) (pretty-toplevel-list c) (pretty-ind ind c)) nil))
|
|
|
((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) (disp-render-mac
|
|
|
((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-png-table closure (rend img colors c) (progn (rend "<table>\n")
|
|
|
((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) (frame-i . 0))
|
|
|
((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) (table closure (heade
|
|
|
((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) (render-code-res-raw-pairs closur
|
|
|
((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) (rende
|
|
|
((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-examples closure (c) (list (quote code-examples) c) nil))
|
|
|
((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) (end) (glob-yeet))
|
|
|
((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) (s+ closure (s ss) (cons s ss) nil) (eval-animation closure (gif c frames) (progn (setq frame-i 0) (setq
|
|
|
((word newline (section 3 "word-size" ((para ("`word-size` returns 4 on 32bit LBM and 8 on 64bits.")) (code ((word-size))) nil)) newline hline) (ref-entry closure (str strings-or-tags) (let ((tags (and (rest-args 0) strings-or-tags)) (strings (or (rest-ar
|
|
|
((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) (pretty-toplevel-li
|
|
|
((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) (render-code-res-pairs closur
|
|
|
((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) (info para ("This document w
|
|
|
((memory-size newline (section 3 "mem-size" ((para ("`mem-size` returns the size of the LBM memory.")) (code ((mem-size))) nil)) newline hline) (para closure (str) (list (quote para) str) nil) (bullet closure (ss) (verb (map (lambda (x) (str-merge " - "
|
|
|
((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
|
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)
|
((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) (str-merge-list closure (strings) (match strings (nil [0])
|
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.36.0