Namespace l2dbus.Timeout
L2DBUS Timeout
This section describes a L2DBUS Timeout class.
The L2DBUS Timeout class exposes methods that provide for the creation of timeouts, enabling/disabling timeouts, and setting the repetition rate. Although normally used internally by L2DBUS, timeouts are useful for creating functions that will be called periodically in the future. Timeouts are driven (and dispatched) from the Dispatcher main loop so the run method must be called frequently in order to trigger timeout callbacks. As a result, the timeouts may not be a highly accurate timing mechanism depending on how much time is spent in these timer callback routines. The timeout callback should not block the thread of execution or the L2DBUS dispatch loop will block as well. Every effort should be made to exit the timeout handler quickly.
While a Timeout is enabled a strong reference will be kept to it regardless of whether is referenced by the client code. This means that it is not eligible for garbage collection (GC) by the Lua VM. The strong reference will be maintained until the first timeout occurs. At the point, if the timeout remains enabled and is not configured to repeat then the strong reference will be dropped. If the timeout is enabled and repeatable then the strong reference is always maintained. This behavior facilitates the creation of non-referenced timeouts that will continue to trigger as long as they remain enabled and configured to repeat. It also supports the concept of a one-shot timeout that will automatically be reclaimed by the GC after firing once (when it's not set to repeat) when no external references are maintained.
Functions
| new (dispatcher, interval, repeat, handler, userToken) |
Timeout
| isEnabled (timeout) | |
| setEnable (timeout, option) | |
| interval (timeout) | |
| setInterval (timeout, interval) | |
| repeats (timeout) | |
| setRepeat (timeout, option) | |
| data (timeout) | |
| setData (timeout, userToken) |
Functions
- new (dispatcher, interval, repeat, handler, userToken)
-
Creates a new Timeout.
Creates a new Timeout with an associated handler that can be called (possibly repeatedly) as the timeout expires. A newly created Timeout is disabled by default and must explicitly be enabled in order to arm it. A handler (callback) is associated with a timeout and it is called when the timeout expires. The signature of the handler has the form:
function onTimeout(timeout, userToken)Where:
- timeout - The L2DBUS Timeout instance
- userToken - A value specified by the user when the timeout was created.
The handler does not have to return anything but should exit quickly to minimize interruption to the Dispatcher main loop.
Parameters:
- dispatcher userdata The dispatcher with which to associate the Timeout.
- interval number The amount of time (in millisecond) before the timeout will expire.
- repeat bool Set to true if the the timeout should reset after expiring (and starta agin) or false if it should only fire once.
- handler func The timeout handler that's called when a timeout expires.
- userToken optional any User data that will be passed to the Timeout handler when it's called. Can be any Lua value.
Returns:
-
userdata
The userdata object representing the Timeout.
Timeout
- isEnabled (timeout)
-
Tests to determine whether the timeout is enabled.
Parameters:
- timeout userdata The timeout to test.
Returns:
-
bool
Returns true if the timeout is enabled and false
otherwise.
- setEnable (timeout, option)
-
Enables or disables a timeout.
Internally a strong reference to an enabled timeout will be maintained until it triggers and then it will be further maintained if set to repeat. This can prevent the Lua GC from reclaiming a timeout that is enabled and set to repeat. By default a newly created timeout is disabled and must explicitly be enabled in order to activate it.
Parameters:
- timeout userdata The timeout to set.
- option bool Set to true to enable the timeout or false to disable it.
- interval (timeout)
-
Returns the timeout interval (in milliseconds).
Parameters:
- timeout userdata The timeout to get the interval.
Returns:
-
number
Returns the timeout interval in milliseconds.
- setInterval (timeout, interval)
-
Sets the timeout interval.
The timeout interval must be a positive number and specifies the number of milliseconds before the timeout expires.
Parameters:
- timeout userdata The timeout to set the interval.
- interval number The interval of the timeout (in milliseconds).
- repeats (timeout)
-
Returns whether or not the timeout is configured to repeatedly fire.
Parameters:
- timeout userdata The timeout to determine if it repeats.
Returns:
-
bool
Returns true if the timeout is configured to repeat and
false otherwise.
- setRepeat (timeout, option)
-
Configures the timeout to repeat or not.
If the timeout is set to repeat then it will reset after firing and begin counting down to the next timeout period.
Parameters:
- timeout userdata The timeout to set the repeat option.
- option bool Set to true to enable the timeout to repeatedly fire or false so that it fires only once.
- data (timeout)
-
Returns the user specified data associated with the timeout.
Parameters:
- timeout userdata The timeout to get the user data.
Returns:
-
any
Returns the user data associated with the timeout.
- setData (timeout, userToken)
-
Sets the user specific data passed to the timeout handler.
Parameters:
- timeout userdata The timeout to set the user data.
- userToken any The user specific data to associate with the timeout.