wren/manual_src/pages/api/sysinfo.html

{# retoor <retoor@molodetz.nl> #}
{% extends 'page.html' %}

{% set page_title = "sysinfo" %}
{% set breadcrumb = [{"url": "api/index.html", "title": "API Reference"}, {"title": "sysinfo"}] %}
{% set prev_page = {"url": "api/subprocess.html", "title": "subprocess"} %}
{% set next_page = {"url": "api/tempfile.html", "title": "tempfile"} %}

{% block article %}
                <h1>sysinfo</h1>

                <p>The <code>sysinfo</code> module provides system information including CPU details, memory usage, uptime, and network interfaces. All values are retrieved from libuv.</p>

                <pre><code>import "sysinfo" for SysInfo</code></pre>

                <div class="toc">
                    <h4>On This Page</h4>
                    <ul>
                        <li><a href="#sysinfo-class">SysInfo Class</a></li>
                        <li><a href="#examples">Examples</a></li>
                    </ul>
                </div>

                <h2 id="sysinfo-class">SysInfo Class</h2>

                <div class="class-header">
                    <h3>SysInfo</h3>
                    <p>System information properties</p>
                </div>

                <h3>Static Properties</h3>

                <div class="method-signature">
                    <span class="method-name">SysInfo.cpuInfo</span> &#8594; <span class="type">List</span>
                </div>
                <p>Returns a list of maps containing CPU information. Each map includes <code>model</code>, <code>speed</code>, and <code>times</code> (with <code>user</code>, <code>nice</code>, <code>sys</code>, <code>idle</code>, <code>irq</code>).</p>
                <pre><code>var cpus = SysInfo.cpuInfo
for (cpu in cpus) {
    System.print("Model: %(cpu["model"])")
    System.print("Speed: %(cpu["speed"]) MHz")
}</code></pre>

                <div class="method-signature">
                    <span class="method-name">SysInfo.cpuCount</span> &#8594; <span class="type">Num</span>
                </div>
                <p>Returns the number of CPUs/cores available on the system.</p>
                <pre><code>System.print("CPU count: %(SysInfo.cpuCount)")</code></pre>

                <div class="method-signature">
                    <span class="method-name">SysInfo.loadAverage</span> &#8594; <span class="type">List</span>
                </div>
                <p>Returns the system load averages as a list of three numbers: 1-minute, 5-minute, and 15-minute averages. On Windows, returns <code>[0, 0, 0]</code>.</p>
                <pre><code>var load = SysInfo.loadAverage
System.print("Load: %(load[0]) %(load[1]) %(load[2])")</code></pre>

                <div class="method-signature">
                    <span class="method-name">SysInfo.totalMemory</span> &#8594; <span class="type">Num</span>
                </div>
                <p>Returns the total system memory in bytes.</p>
                <pre><code>var totalMB = SysInfo.totalMemory / 1024 / 1024
System.print("Total memory: %(totalMB) MB")</code></pre>

                <div class="method-signature">
                    <span class="method-name">SysInfo.freeMemory</span> &#8594; <span class="type">Num</span>
                </div>
                <p>Returns the free system memory in bytes.</p>
                <pre><code>var freeMB = SysInfo.freeMemory / 1024 / 1024
System.print("Free memory: %(freeMB) MB")</code></pre>

                <div class="method-signature">
                    <span class="method-name">SysInfo.uptime</span> &#8594; <span class="type">Num</span>
                </div>
                <p>Returns the system uptime in seconds.</p>
                <pre><code>var hours = (SysInfo.uptime / 3600).floor
System.print("Uptime: %(hours) hours")</code></pre>

                <div class="method-signature">
                    <span class="method-name">SysInfo.hostname</span> &#8594; <span class="type">String</span>
                </div>
                <p>Returns the system hostname.</p>
                <pre><code>System.print("Hostname: %(SysInfo.hostname)")</code></pre>

                <div class="method-signature">
                    <span class="method-name">SysInfo.networkInterfaces</span> &#8594; <span class="type">Map</span>
                </div>
                <p>Returns a map of network interfaces. Each key is an interface name, and each value is a list of address maps containing <code>address</code>, <code>netmask</code>, <code>family</code> (IPv4 or IPv6), <code>internal</code>, and <code>mac</code>.</p>
                <pre><code>var interfaces = SysInfo.networkInterfaces
for (name in interfaces.keys) {
    System.print("Interface: %(name)")
    for (addr in interfaces[name]) {
        System.print("  %(addr["family"]): %(addr["address"])")
    }
}</code></pre>

                <div class="method-signature">
                    <span class="method-name">SysInfo.hrtime</span> &#8594; <span class="type">Num</span>
                </div>
                <p>Returns a high-resolution time value in nanoseconds. Useful for precise timing measurements.</p>
                <pre><code>var start = SysInfo.hrtime
// ... do some work ...
var elapsed = SysInfo.hrtime - start
System.print("Elapsed: %(elapsed / 1000000) ms")</code></pre>

                <div class="method-signature">
                    <span class="method-name">SysInfo.residentMemory</span> &#8594; <span class="type">Num</span>
                </div>
                <p>Returns the resident set size (RSS) of the current process in bytes.</p>
                <pre><code>var rssMB = SysInfo.residentMemory / 1024 / 1024
System.print("Process RSS: %(rssMB) MB")</code></pre>

                <div class="method-signature">
                    <span class="method-name">SysInfo.constrainedMemory</span> &#8594; <span class="type">Num</span>
                </div>
                <p>Returns the memory limit for the process in bytes (e.g., cgroup limit). Returns 0 if no limit is set.</p>
                <pre><code>var limit = SysInfo.constrainedMemory
if (limit > 0) {
    System.print("Memory limit: %(limit / 1024 / 1024) MB")
} else {
    System.print("No memory limit set")
}</code></pre>

                <h2 id="examples">Examples</h2>

                <h3>System Overview</h3>
                <pre><code>import "sysinfo" for SysInfo

System.print("=== System Information ===")
System.print("Hostname: %(SysInfo.hostname)")
System.print("CPUs: %(SysInfo.cpuCount)")
System.print("")

System.print("=== Memory ===")
var totalGB = (SysInfo.totalMemory / 1024 / 1024 / 1024 * 100).floor / 100
var freeGB = (SysInfo.freeMemory / 1024 / 1024 / 1024 * 100).floor / 100
var usedPercent = ((1 - SysInfo.freeMemory / SysInfo.totalMemory) * 100).floor
System.print("Total: %(totalGB) GB")
System.print("Free: %(freeGB) GB")
System.print("Used: %(usedPercent)\%")
System.print("")

System.print("=== Load Average ===")
var load = SysInfo.loadAverage
System.print("1 min:  %(load[0])")
System.print("5 min:  %(load[1])")
System.print("15 min: %(load[2])")
System.print("")

System.print("=== Uptime ===")
var uptime = SysInfo.uptime
var days = (uptime / 86400).floor
var hours = ((uptime % 86400) / 3600).floor
var minutes = ((uptime % 3600) / 60).floor
System.print("%(days) days, %(hours) hours, %(minutes) minutes")</code></pre>

                <h3>CPU Information</h3>
                <pre><code>import "sysinfo" for SysInfo

var cpus = SysInfo.cpuInfo
System.print("CPU Information:")
System.print("================")

var i = 0
for (cpu in cpus) {
    System.print("CPU %(i): %(cpu["model"])")
    System.print("  Speed: %(cpu["speed"]) MHz")
    var times = cpu["times"]
    var total = times["user"] + times["nice"] + times["sys"] + times["idle"] + times["irq"]
    var idle = (times["idle"] / total * 100).floor
    System.print("  Idle: %(idle)\%")
    i = i + 1
}</code></pre>

                <h3>Network Interfaces</h3>
                <pre><code>import "sysinfo" for SysInfo

var interfaces = SysInfo.networkInterfaces

System.print("Network Interfaces:")
System.print("===================")

for (name in interfaces.keys) {
    var addrs = interfaces[name]
    System.print("%(name):")
    for (addr in addrs) {
        if (!addr["internal"]) {
            System.print("  %(addr["family"]): %(addr["address"])")
            if (addr["mac"] != "00:00:00:00:00:00") {
                System.print("  MAC: %(addr["mac"])")
            }
        }
    }
}</code></pre>

                <h3>Performance Timing</h3>
                <pre><code>import "sysinfo" for SysInfo

var measure = Fn.new { |name, fn|
    var start = SysInfo.hrtime
    fn.call()
    var elapsed = SysInfo.hrtime - start
    System.print("%(name): %(elapsed / 1000000) ms")
}

measure.call("String concatenation") {
    var s = ""
    for (i in 0...1000) {
        s = s + "x"
    }
}

measure.call("List operations") {
    var list = []
    for (i in 0...10000) {
        list.add(i)
    }
}</code></pre>

                <h3>Memory Monitoring</h3>
                <pre><code>import "sysinfo" for SysInfo
import "timer" for Timer

System.print("Memory Monitor (press Ctrl+C to stop)")
System.print("=====================================")

while (true) {
    var totalMB = (SysInfo.totalMemory / 1024 / 1024).floor
    var freeMB = (SysInfo.freeMemory / 1024 / 1024).floor
    var rssMB = (SysInfo.residentMemory / 1024 / 1024).floor
    var usedPercent = ((1 - SysInfo.freeMemory / SysInfo.totalMemory) * 100).floor

    System.print("System: %(freeMB)/%(totalMB) MB free (%(usedPercent)\% used) | Process RSS: %(rssMB) MB")
    Timer.sleep(1000)
}</code></pre>

                <div class="admonition note">
                    <div class="admonition-title">Note</div>
                    <p>Load average values are not available on Windows and will return <code>[0, 0, 0]</code>.</p>
                </div>

                <div class="admonition tip">
                    <div class="admonition-title">Tip</div>
                    <p>Use <code>SysInfo.hrtime</code> for precise performance measurements. It provides nanosecond resolution and is not affected by system clock adjustments.</p>
                </div>
{% endblock %}