File Intercom.lua
Functions
Intercom:broadcast (msg, lifetime) | Broadcast a messsage. |
Intercom:createReply (msg) | Optional method to initialize a fresh message for replying. The other possibility is just to reuse the received message for replying. |
Intercom:listen (method, object, fromList, ival) | Listen to messages from specified plugins, to me. |
Intercom:listenForBroadcast (method, object, fromList, ival) | Listen to broadcast messages from specified plugins, to anyone. |
Intercom:new (t) | Constructor for new instance. |
Intercom:newClass (t) | Constructor for extending class. |
Intercom:sendAndReceive (msg, to, tmo, fromName) | Send message to specified plugin and wait for reply. |
Intercom:sendMessage (msg, to) | Send message to destination (unsolicited-inbox), and do not expect nor wait for reply. |
Intercom:sendReply (msg, to) | Send message that is the reply to an inbound (unsolicited "command" message). |
Intercom:stopBroadcastListening (object) | Stop broadcast listener tied to specified object. |
Intercom:stopListening (object) | Stop listener tied to specified object. |
Functions
- Intercom:broadcast (msg, lifetime)
-
Broadcast a messsage.
Parameters:
-
msg
: (table, required) message to be broadcast. -
lifetime
: (number, optional) lifetime in seconds, else defaults to whatever was initialized when intercom object created (e.g. 10 seconds).
Usage:
message will exist for specified time for any broadcast listeners to hear, then it's deleted (by sender - listeners just make note to not reprocess).
broadcast messages do not warrant replies, but receiver is free to send message to broadcaster when broadcast message is received...
-
- Intercom:createReply (msg)
-
Optional method to initialize a fresh message for replying.
The other possibility is just to reuse the received message for replying.Parameters:
-
msg
:
-
- Intercom:listen (method, object, fromList, ival)
-
Listen to messages from specified plugins, to me.
Parameters:
-
method
: (function, required) callback function - must be method. -
object
: (Class instance object, optional) object containing callback method. - must not be closed object, or must contain __seen member table. -
fromList
: (table as set, default = accept from anyone including self) keys are plugin ids from who unsolicited messages will be accepted, values must evaluate to boolean true. -
ival
: (number, optional) polling interval, else accept default.
Usage:
returns immediately after starting task, which runs until shutdown.
object may be nil, and method may be function, as long as plugin will never try to stop listening.
-
- Intercom:listenForBroadcast (method, object, fromList, ival)
-
Listen to broadcast messages from specified plugins, to anyone.
Parameters:
-
method
: (function, required) callback function - must be method. -
object
: (Class instance object, optional) object containing callback method. - must not be closed object, or must contain __seen member table. -
fromList
: (table as set, default = accept from anyone including self) keys are plugin ids from who unsolicited messages will be accepted, values must evaluate to boolean true. -
ival
: (number, optional) polling interval, else accept default.
Usage:
returns immediately after starting task, which runs until shutdown.
-
- Intercom:new (t)
-
Constructor for new instance.
Parameters:
-
t
: (table) initial object members, all optional, including:
dir (string, default=catalog dir) path to root of messaging dirs.
pollingInterval (number, default=.1) seconds between polling for incoming messages and/or replies.
- faster means more responsive but more disk wear. Default is .1 second - seems a nice balanced value.
- you can go down to .01 second (windows base clock frequency), for ultra-fast messaging,
- or up to a half second if speed is not a concern, to save disk wear.
broadcastLifetime (number, default=10) seconds for broadcast messages to last before they're assumed to have been heard, and are cleaned up.
addlNames (array of strings, default={}) names of additional plugin entities to be communicating via the intercom, e.g. "Background" (corresponding from-address {pluginId}.Background).
-
- Intercom:newClass (t)
-
Constructor for extending class.
Parameters:
-
t
:
-
- Intercom:sendAndReceive (msg, to, tmo, fromName)
-
Send message to specified plugin and wait for reply.
Parameters:
-
msg
: -
to
: -
tmo
: -
fromName
:
Usage:
must be called from a task.
Return values:
- reply (table) or nil if no reply
- errm (string) error message if no reply.
-
- Intercom:sendMessage (msg, to)
-
Send message to destination (unsolicited-inbox), and do not expect nor wait for reply.
Parameters:
-
msg
: (table, required) 'name' is only required member, but 'content' may be nice... -
to
: (string, required) destination plugin id.
Usage:
Not for internal use - use private methods instead.
Return values:
- status (boolean) true => sent.
- message (string) error message if not sent.
-
- Intercom:sendReply (msg, to)
-
Send message that is the reply to an inbound (unsolicited "command" message).
Parameters:
-
msg
: (table, required) 'name' is only required member, but 'content' may be nice... -
to
: (string, required) destination plugin id - often msg.from
Usage:
Maybe best to recompute message content, then resend original message (since it already has some members assigned as needed) - but its your call...
presently throws error if problems sending, but that may change - note: need not be called from task, although typically is.
-
- Intercom:stopBroadcastListening (object)
-
Stop broadcast listener tied to specified object.
Parameters:
-
object
: Must be same object as passed to listen-for-broadcast function.
-
- Intercom:stopListening (object)
-
Stop listener tied to specified object.
Parameters:
-
object
: Must be same object as passed to listen function.
-