event library provides functions for understanding an event and the environment in which it was raised as well as actions for sending events.
There are three categories of event functions.
For historical reasons, some of these are Web-centric. The following functions are available:
event:env()- returns information about the event's environment. The function takes an argument that determines what will be returned:
caller -return the URL of the Web page on which the event is firing (assumes an event in the
ip -return the IP number of the endpoint (client).
referer -return the URL of the referring page to the caller (assumes a web event).
title -return the page title of the calling page.
- txn_id - return the transaction ID of this ruleset evaluation.
event:attr() -returns a specific event attribute. The function takes the name of the attribute to be returned as its sole argument.
event:attrs() -returns all the event attributes as a map.
event:channel()- returns information about the event channel. The function takes an argument that determines what is returned:
id- returns the event channel identifier.
The event library supports sending events to event channels.
event:send(<subscription_map>, <domain>, <type>)
<type> are expressions that evaluate to strings. These arguments are optional. If they are not present, the values with keys
_type from the subscription map will be used.
A subscription map is any map that contains an event channel identifier (identified by the key
cid) or an event signal URL (identified by the key
esl). The other key-value pairs in the map are optional. The following code sample shows a subscription map:
Given the preceding subscription map declaration, we could send a
notification:status event to the event channel identified by the CID in the map as follows:
If the subscription map contains both a CID and an ESL, the ESL is used to send the event.
Event attributes can be specified in the optional action parameter
attrs. To send a
notification:status event with the attributes priority and subject, we would modify the preceding example as follows:
Of course, the arguments and parameters of an action can be calculated.
If the ESL or CID have non-standard keys in the subscription map, you can use the parameters
esl_key to give the key name:
The default behavior of send() is to use the Sky event protocol in asynchronous mode. To force synchronous event processing, add the attribute
_async with value 0 to the attributes.
Results are only available for synchronous mode events. In general, you shouldn't be relying on results from sending an event. Rather, the recommended pattern is to have the receiving event network communicate by sending an event to the original sender. However, it is often useful to know whether or not the
send() succeeded. To support this, the system will raise a
system:send_complete event when all threads have completed. The event has a single attribute called
send_results that contains an array of the results of the individual sends. Each member of the array has the following structure:
You can use a rule like the following listen for the system event and loop over the results:
Obviously, you probably don't want to merely print the status out, but rather check it and do something if it is not 200.
A common pattern when sending events is to loop over the subscribers and then raise an explicit event when done. The on final guard condition is used to ensure the explicit event is only raised once.
The difference between raising an explicit event
on final and using the system generated
system:send_complete event shown above might not be obvious.
The primary difference is that the explicit event does have access to result information, including status. But, both the explicit event shown in the preceding code and the
system:send_complete event will cause any rules that are selected based on the respective events to be scheduled. Similarly neither will cause rules to be run before
send() is complete since parallel
send() actions must all complete before the rule they are in can complete.
The blog post Federating Personal Clouds shows an example using