Namespace l2dbus.Watch
L2DBUS Watch
This section describes a L2DBUS Watch class which represents a file descriptor that can be monitored for activity.
On Linux platforms this can include sockets, pipes, files, and anything that provides a poll-able descriptor. Internally, L2DBUS monitors the file-descriptor associated with a Connection to detect when new messages are available to be received. Client applications can use this same mechanism to monitor activity on various descriptors themselves.
While a Watch 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 it is disabled again. This behavior facilitates the creation of non-referenced watches that will continue to trigger as long as they remain enabled.
Functions
new (dispatcher, fd, events, handler, userToken) |
Tables
EventTable | The EventTable provides an indication of what events are signaled on a given file-descriptor. |
Constants
READ | |
WRITE | |
ERROR | |
HANGUP |
Watch
getDescriptor (watch) | |
events (watch) | |
setEvents (watch, events) | |
isEnabled (watch) | |
setEnable (watch, option) | |
data (watch) | |
setData (watch, userToken) |
Functions
- new (dispatcher, fd, events, handler, userToken)
-
Creates a new Watch.
Creates a new Watch with an associated handler that is called whenever one of the specified events is signaled on the provided file descriptor. By default a Watch is created disabled and needs to be explicitly enabled in order to be armed.
The Watch handler has a signature of the form:
function onWatch(watch, evTable, userToken)
Where:
- watch - The L2DBUS Watch instance
- evTable - An table of signaled events. See EventTable.
- userToken - A value specified by the client when the watch is created.
The handler does not have to return anything but should exit quickly to minimize interruptions to the Dispatcher main loop.
Parameters:
- dispatcher userdata The dispatcher with which to associate the Watch.
- fd number or userdata The file descriptor to watch. This can be either a Lua file (e.g. userdata wrapping the actual file descriptor) or the raw integral file descriptor received from the operating system that is pollable.
- events number or string The events (READ, WRITE, ERROR, HANGUP) which should be monitored. If the parameter is a Lua number then it is assumed to be a bitmask of the previous constants OR'ed together. If it is a string then the letters r (READ), w (WRITE), e (ERROR), and h (HANGUP) are expected to indicate the events to watch.
- handler func The watch handler that's called when a timeout expires.
- userToken optional any User data that will be passed to the Watch handler when it's called. Can be any Lua value.
Returns:
-
userdata
The userdata object representing the Watch.
Tables
- EventTable
-
The EventTable provides an indication of what events are signaled on
a given file-descriptor. The evMask field is a bitwise OR of a
combination of the following constants: READ, WRITE, ERROR, and
HANGUP. There are also discrete fields in the table for each event type
and these will be set to true or false depending on whether they are
signaled.
Fields:
- evMask (number) The actual event mask of signaled events.
- READ (bool) Set to true if the read event is signaled.
- WRITE (bool) Set to true if the write event is signaled.
- ERROR (bool) Set to true if the error event is signaled.
- HANGUP (bool) Set to true if the hangup event is signaled.
Constants
- READ
- The bitmask for file-descriptor read event.
- WRITE
- The bitmask for file-descriptor write event.
- ERROR
- The bitmask for file-descriptor error event.
- HANGUP
- The bitmask for file-descriptor hangup event.
Watch
- getDescriptor (watch)
-
Returns the underlying file descriptor being watched.
Parameters:
- watch userdata The watch monitoring the file descriptor.
Returns:
-
number
Returns the underlying OS file descriptor being monitored.
- events (watch)
-
Returns the events being monitored on the file descriptor.
Parameters:
- watch userdata The watch for which the events are returned.
Returns:
-
table
Returns an EventTable indicating the events that
are being monitored.
- setEvents (watch, events)
-
Sets the events that the Watch should monitor.
Parameters:
- watch userdata The watch to set the events to monitor.
- events number or string The events (READ, WRITE, ERROR, HANGUP) which should be monitored. If the parameter is a Lua number then it is assumed to be a bitmask of the previous constants OR'ed together. If it is a string then the letters r (READ), w (WRITE), e (ERROR), and h (HANGUP) are expected to indicate the events to watch.
- isEnabled (watch)
-
Returns whether the specified watch is enabled to monitor events.
Parameters:
- watch userdata The watch to see if it's enabled.
Returns:
-
bool
Returns true if it's enabled, false otherwise.
- setEnable (watch, option)
-
Sets whether the watch should be enabled or disabled from monitoring the associated file descriptor.
Parameters:
- watch userdata The watch to configure.
- option bool Set to true to enable the watch, false to disable it.
- data (watch)
-
Returns the user specified data associated with the watch.
Parameters:
- watch userdata The watch to get the user data.
Returns:
-
any
Returns the user data associated with the watch.
- setData (watch, userToken)
-
Sets the user specific data passed to the watch handler.
Parameters:
- watch userdata The watch to set the user data.
- userToken any The user specific data to associate with the watch.