L2DBUS

• Index

Contents

• Functions
• Tables
• Constants
• Watch

Namespaces

• l2dbus.Connection
• l2dbus.Dbus
• l2dbus.DbusTypes
• l2dbus.Dispatcher
• l2dbus.Int64
• l2dbus.Interface
• l2dbus.Introspection
• l2dbus.Match
• l2dbus.Message
• l2dbus.PendingCall
• l2dbus.ServiceObject
• l2dbus.Timeout
• l2dbus.Trace
• l2dbus.Uint64
• l2dbus.Watch

Modules

• l2dbus
• l2dbus-ev
• l2dbus-glib
• l2dbus.msgbusctrl
• l2dbus.proxyctrl
• l2dbus.service
• l2dbus.validate
• l2dbus.xml

Topics

• 01-introduction.md

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.