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.

Parameter Type Description
seconds Number The number of seconds to wait.

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:

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.

Parameter Type Description
seconds Number The number of seconds to wait.

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.

.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.

Parameter Type Description
[1] Integer The total number of Epoch seconds.
[2] Integer The microseconds associated with our number of Epoch seconds.
    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.

Parameter Type Description
seconds Integer The total number of Epoch seconds.
microseconds Integer The microseconds associated with our number of Epoch seconds.
    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.

Parameter Type Description
from Two-Element Integer List [Required] The start time of the interval.
to Two-Element Integer List The end time of the interval.
(Default: The current time "now")

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))