Toit
Libraries
bignum
binary
bitmap
ble
bytes
core
crypto
device
ec618
encoding
esp32
expect
fixed-point
flash
font
gpio
i2c
i2s
icons
io
line-wrap
log
math
monitor
net
pulse-counter
reader
reader-writer
rmt
serial
spi
statistics
system
tls
uart
uuid
writer
zlib

Library system

To use this library in your code:

import system
System related functionality.
This module contains functions that provide information about the currently running Toit program, as well as the system itself, such as the platform and architecture. It also provides functions to collect statistics about the system and the current process.

Globals

ARCHITECTURE-ARM
Return value from architecture.
ARCHITECTURE-ARM64
Return value from architecture.
ARCHITECTURE-EC618
Return value from architecture.
ARCHITECTURE-ESP32
Return value from architecture.
ARCHITECTURE-X86
Return value from architecture.
BITS-PER-BYTE
The number of bits per byte.
BITS-PER-WORD
The number of bits per word.
BYTES-PER-WORD
The number of bytes per word.
LINE-TERMINATOR
Returns either "\r\n" or "\n" depending on the underlying platform.
PLATFORM-FREERTOS
Return value from platform.
PLATFORM-LINUX
Return value from platform.
PLATFORM-MACOS
Return value from platform.
PLATFORM-WINDOWS
Return value from platform.

Functions

app-sdk-info -> string
Returns information about who build this application snapshot.
app-sdk-version -> string
Returns the Toit SDK version that generated this application snapshot.
architecture -> string
Returns a string identifying the underlying architecture.
bytes-allocated-delta -> int
Returns the number of bytes allocated, since the last call to this function.
For the first call, returns number of allocated bytes since system start.
Deprecated. This function doesn't nest. Use process-stats instead.
gc-count -> int
Returns the number of garbage collections.
hostname -> string
The hostname of the machine running the program.
hostname= hostname/string -> none
Sets the hostname of the machine running the program.
This operation is not supported on all platforms.
Only new network connections will use the new hostname. Also, some routers may cache the old hostname for a while.
platform -> string
Returns a string identifying the underlying platform.
process-stats --gc/bool=false list/List=(List STATS-LIST-SIZE_) -> List
Collect statistics about the system and the current process.
The gc flag indicates whether a garbage collection should be performed before collecting the stats. This is a fairly expensive operation, so it should be avoided if possible.
Returns an array with stats for the current process.
The stats, listed by index in the array, are:
0. New-space (small collection) GC count for the process
1. Allocated memory on the Toit heap of the process
2. Reserved memory on the Toit heap of the process
3. Process message count
4. Bytes allocated in object heap
5. Group ID
6. Process ID
7. Free memory in the system
8. Largest free area in the system
9. Full GC count for the process (including compacting GCs)
10. Full compacting GC count for the process
The "bytes allocated in the heap" tracks the total number of allocations, but doesn't deduct the sizes of objects that die. It is a way to follow the allocation pressure of the process. It corresponds to the value returned by bytes-allocated-delta.
The "allocated memory" is the combined size of all live objects on the heap.
The "reserved memory" is the size of the heap.
By passing the optional list argument to be filled in, you can avoid causing an allocation, which may interfere with the tracking of allocations. But note that at some point the bytes-allocated number becomes so large that it needs a small allocation of its own.
Examples

print "There have been $(process-stats[STATS-INDEX-GC-COUNT]) GCs for this process"
process-stats --gc/bool=false group/any id/any list/List=(List STATS-LIST-SIZE_) -> List
Variant of process-stats.
Returns an array with stats for the process identified by the group and the id.
program-name -> string
Returns the name of the toit file, image, snapshot, or executable that the current program was run from.
If the program is run by the Toit command line tool, this is the name of the source file passed to the tool.
If the program is run as an executable, this is the name of the executable. In this case it is equivalent to argv[0] in C, or $0 in bash.
May return null if this information is not available.
program-path -> string
Returns the fully resolved path to the toit file, image, or snapshot that the current program was run from.
If the program is run by the Toit command line tool, this is the fully resolved path to the source file passed to the tool, as provided by realpath.
If the program is run as an executable, this is the fully resolved path to the executable.
serial-print-heap-report marker/string="" max-pages/int=0 -> none
tune-memory-use percent/int -> none
Sets the system tradeoff between memory use and speed.
The percent argument is a number between 0 and 100, where 0 means that the system should use as little memory as possible, and 100 means that the system should run as fast as possible.
Host platforms default to high performance, while embedded platforms default to low memory use.
This setting is global, applying to all Toit processes running on the embedded system, and all Toit processes running in a host process.
vm-sdk-info -> string
Returns information about who built this virtual machine.
vm-sdk-model -> string
Returns the Toit SDK model that this virtual machine has been built from.
vm-sdk-version -> string
Returns the Toit SDK version that this virtual machine has been built from.