The tulip.pkg.pubsub module exports the pubsub package.
#Dependencies
#Configuration
- allowed_channels: array of string = if set, only those channels
will be allowed.
- get_connection: function = if set, used to get the long-running
connection used to listen for notifications (and re-connect if
connection is lost). Defaults to App:db().
- error_handler: function = if set, called whenever an error occurs
in the background coroutine that dispatches notifications. It is
called with the current xpgsql connection, a number that increments
with each failure (first call is 1), a (possibly nil) error message
and the get_connection function.
If the function returns nil, the coroutine is terminated and
pubsub notifications will stop being emitted. Otherwise, it can
return a connection and an optional integer, and if so the
connection will be used instead of the old connection, and the
number will be used as new value for the failure count (e.g.
return 0 to reset). By default, a function that calls
get_connection to get a new connection, and fails permanently
(i.e. returns nil) after 3 calls.
- listeners: table = if set, key is the channel and value is an
array of functions to register as listeners for that channel.
#API Extensions
Registering this package provides the following method and field extensions.
#ok, err = App:pubsub(chan, fconn[, msg])
Publishes a notification on a channel if msg is provided, or subscribes to
notifications on a channel.
Args:
- chan: string = the pubsub channel
- fconn: function|connection|nil = either a function to register
as handler for that channel, or an optional database
connection to use to publish msg. The handler function receives
a Notification object as argument with a channel and payload
field. It also has a terminate method to terminate the
pubsub notification coroutine, mostly for tests.
- msg: table|nil = the payload of the notification to publish.
Returns:
- ok: boolean = true on success
- err: Error|nil = error message if ok is falsy
#true = Notification:terminate()
Terminates the subscription to the channel that generated this
Notification.
Returns:
- true = always returns true
#Notification.channel: string
The name of the channel that received this Notification.
#Notification.payload: table
The JSON-decoded payload that was sent with the Notification.
Back to index