Common LUA Globals

Introduction

The following global variables are pre-loaded for all LUA Service scripts.

In the case where a Lua instance is cached and re-used, the global variables listed here will be initialized every time.

Variable Type Description
TRACE_LEVEL 0 - 3 An integer value indicating if tracel-level debugging is currently enabled.
0 = none, 1 = DEBUG, 2 = DUMP, 3 = SPAM.
This can be used to avoid needless computation overhead when tracing is not activated.
CHAIN_COUNT Integer The number of times that this processing has chained to a follow-on script.
The initial value for this counter is 0.
SCRIPT_KEY String The key used by the loader to identify which LUA script content to execute.
SCRIPT_MTIME Number The modification time (epoch) of the script which was loaded to return this LUA.
APPLICATION_IDX Integer The index of the n2svcd application which is executing this LUA.
APPLICATION_NAME String The name of the n2svcd application which is executing this LUA.
APPLICATION_PID Integer The process ID of the n2svcd application which is executing this LUA.
SERVICE_MODULE String The class of the LuaService module which initiated this LUA.
LOADER_MODULE String The class of the LuaLoader module which loaded this LUA.
REQUIRE_LIST List of Table The list of internally-satisfiable require modules given to the LuaLoader to be used in conjunction with this script name. Most Loaders will not provide any require modules, in which case this global variable will be nil.
[] Table Anonymous table.
.name String The module name which will be internally satisfied by a require.
.lua_chunk String The LUA content (compiled or non-compiled) which satisfies the require.
.version Integer An associated version number provided by the loader logic.
INSTANCE_IDX Hex String The instance_idx of the LuaInstance currently executing this LUA.

In addition, each definition may define service-specific global Lua constants to be set in the environment of every Lua script initiated by that service. See the Lua Services configuration within the LogicApp.

Unreliable Global Variables

Note that when the same script definition is to be executed more than once, the LogicApp will typically cache and re-use the Lua context from previous executions. This is for efficiency, since it avoids the overhead of re-compiling the code, re-loading modules, and re-building the Lua runtime stack.

Scenarios where re-use of Lua context will occur:

When re-using a Lua context in any of these case, old Lua global variables retain their value between executions of that same script, unless they are explicitly re-set.

The following two types of Lua globals are reliable, i.e. their value is reset for each execution:

a. The Common Lua Global variables (listed in the table above) are set for each execution.
b. Custom service globals are set for each execution.

All other Lua global variables are unreliable, and will “leak” between script executions. This includes modules loaded using require (see below).

Scripts must be aware of this, and must take it into consideration when using Lua globals.

Modules Loaded by “require”

Note that any module definition loaded by the Lua require mechanism is actually a global table variable, even though it is referenced by a local handle.

For example:

    local n2svcd = require "n2.n2svcd"

    local handler = function (rest)
        if (n2svcd.myvar == nil) then
            print ("INIT")
            n2svcd.myvar = true
        end
    end

    return n2svcd.handler (handler)

Because n2svcd is a local variable, you might expect that n2svcd.myvar will be uninitialised each time the script is run. However, it is important to understand the require function caches all loaded modules in a global buffer and will return a reference to a cached global table.

This means that when a Lua context is re-used, any module object returned by require will be the same module object which was used by any previous use of that Lua context, and any modifications made by the previous script execution will still be in effect. I.e. in the example given, if the Lua context for the script was cached and re-used, the second script run would not print “INIT”.