Time Methods

Introduction

The Lua language does not provide a native high-resolution time function.

These supplementary time-based methods are provided for convenience and compatibility.

These methods are accessed via the “n2.n2svcd” module:

    local n2svcd = require "n2.n2svcd"

.wait [Asynchronous]

This method sets a timer and hands control back to the LogicApp. When the timer expires the Lua script will be resumed.

The wait method takes the following parameters.

Example:

    n2svcd.wait (5)

The wait method returns nil.

.progress [Asynchronous]

This method sets a timer and hands control back to the LogicApp.

The script will be resumed when either:

a. The timer expires, or b. When the Service or any Agent receives an inbound message.

Note that this method will immediately return in the case where the Service or any Agent already has a pending progress notification to report because it has already previously received a message which has not yet been reported as a progress notification.

This is an important mechanism when a service script is using multiple asynchronous protocol interactions and cannot guarantee which one will occur first. This method can be used to wait until at least one asynchronous message is received, and can then determine how to proceed.

Note that:

• When returning from the progress method, all service/agent pending progess notification flags are cleared.
• Calling any service action will clear the service pending progress notification flag.
• Calling any agent action will clear the agent’s pending progress notification flag.

Note also that some Agents or Services may receive intermediate “for-information” messages, for example the REST Client Agent which may receive REST-C-SENT messages confirming message delivery. These will be reported as “progress”, although the Lua script may certainly consider these to be uninteresting.

The progress method takes the following parameters.

Example:

    local progress = n2svcd.progress (1.5)
    if (progress[tcap_agent.AGENT_KEY]) then
      ...
    end

The progress method returns nil if the timer expires without any pending progress notification.

The progress method returns a table if it returns one or more pending progress notifications are returned. The key values of the table are the service key or the agent key. The table values are the number 1.

• The service key for any service is the fixed value *.
• The agent key for each agent is defined in the documentation for that agent.

.time [Synchronous]

The time method takes no parameters.

The time method returns a floating point “epoch” seconds.

This is more efficient and easier to use than the gettimeofday methods, since time deltas can be computed with a simple subtraction or addition.

    local start_time = n2svcd.time ()

    -- Processing occurs here.

    local end_time = n2svcd.time ()
    local elapsed_seconds = end_time - start_time

    if (elapsed_seconds > 0.5) then
        error ("Processing too slow.  Aborting script!")
    end

.gettimeofday [Synchronous]

The get_time_of_day method takes no parameters.

The get_time_of_day method returns a two-element Lua list.

    local tod = n2svcd.gettimeofday ()
    n2svcd.debug ("NOW = %d.%d", tod[1], tod[2])

.get_time_of_day [Synchronous]

The get_time_of_day method is a minor variant which returns a Lua table with named attributes.

    local tod = n2svcd.get_time_of_day ()
    n2svcd.debug ("NOW = %d.%d", tod.seconds, tod.microseconds)

.tv_interval [Pure Lua]

The tv_interval method accepts either one or two two-element Lua lists as returned from gettimeofday.

The tv_interval method returns the floating-point number difference in seconds between the times represented by from and to. If the from time is later than the to time then the result will be negative.

    local from = n2svcd.gettimeofday ()
    n2svcd.wait (3.5)
    local to = n2svcd.gettimeofday ()
    n2svcd.debug ("ELAPSED = %f", n2svcd.tv_interval (from, to))