16. Console

This section describe the API to add new console utilities available through hakactl.

The console utilities need to be installed in the folder <install path>/share/haka/console. Those files will automatically be loaded when hakactl console is started.

16.1. List

The List is the main object that is used to return data to the console.

See also

Console User Guide

list.new(name) → List
Returns:
  • List (List) – List class.

Create a new type of list. The returned object can be specialized with fields, formatters...

object List

The return object describe this new list and can be extended with new methods like a basic class.

This class also need some class values:

List.field
Type:table of strings

List of all fields displayed to the user.

List.key
Type:string

Unique key for this list. This key is used when a user call get(). This key must be one known field.

List.field_format
Type:table of formatter

Define which formatter to use when printing the value of the fields. This table associates name with a corresponding formatter.

See also

Formatter

List.field_aggregate
Type:table of aggregator

Define aggregate utilities to use to add a summary line for all instance of this list. It allows for example to add statistics values to compute a global view. This table associates name with a corresponding aggregator.

See also

Aggregator

<List>._data
Type:table of table

Table of table containing each element of this list. It can be used to write custom functions.

<List>:add(data)
Type :table

Add one entry into this list.

<List>:addall(data)
Type :table of table

Add all entries in the data into this list.

16.1.1. Formatter

Formatters are functions that convert the value given as argument into a string that will be printed.

list.formatter.unit

Convert a numeric value into human readable string adding units if needed (k, M, G...).

list.formatter.optional(default)

If the value is nil, replace it by a default value.

16.1.2. Aggregator

Aggregators are functions that compute a value from a list of values.

list.aggregator.add

Sum all values.

list.aggregator.replace(override)

Always replace the value by the given override.

16.2. New function

Adding a new function can be done by adding functions to the table haka.console. This table is the environment provided within the console.

16.2.1. Remote execution

The console code is executed by the hakactl process. It does not have direct access to haka. To be able to interact with it, it is possible to remotely execute some Lua code and get the result.

hakactl.remote(thread, f) → ret
Parameters:
  • thread (string or number) – Thread number, 'any' or 'all'.
  • f (function) – Function to execute remotely.
Returns:
  • ret (table) – Return values.

Execute a Lua function on some haka thread’s remotely. The thread number can be:

  • The thread id.
  • 'all' if the code should be executed on each thread.
  • 'any' if the code should be executed on one thread but the id is not important.

The return value is a table containing the result for each called thread. It will have one element if executed on 1 thread or more.

The data send and received are marshaled, some care need to be taken to transmit minimal data.

16.3. Example

-- This Source Code Form is subject to the terms of the Mozilla Public
-- License, v. 2.0. If a copy of the MPL was not distributed with this
-- file, You can obtain one at http://mozilla.org/MPL/2.0/.

local list = require('list')
local class = require('class')

local EventInfo = list.new('thread_info')

EventInfo.field = {
    'event', 'listener'
}

EventInfo.field_format = {
    ['listener'] = list.formatter.unit,
}

EventInfo.field_aggregate = {
    ['listener'] = list.aggregator.add
}

function console.events()
    local data = hakactl.remote('any', function ()
        return haka.console.events()
    end)

    local info = EventInfo:new()
    info:add(data[1])
    return info
end