Publish and subscribe to a message queue¶
This page describes how KXS processes publish messages to a message queue, and how external clients subscribe to one.
Publish to a message queue¶
Any KXS process can publish to a message queue instance by publishing to the RT stream and topic, as defined by streamIn and topicIn in feed.yaml.
The published message must conform to the expected structure of a message published internally via an RT stream. This structure is a three-element list, which contains the following elements.
| Element | Type | Description | Example |
|---|---|---|---|
| Payload name | Symbol[] |
Must include pl, otherwise it is ignored by the message queue. |
enlist`pl |
| Revision number | Integer[] |
Value can be arbitrary (not used). | enlist 0Ni |
| Payload | Table | A table with two columns: hdr and payload. The payload row contains the arbitrary message payload. |
enlist`hdr`payload!(`ac`rc`ai!(0h;0h;enlist"");1 2 3 4) |
The following example shows how to publish to a message queue instance from a maintenance console.
QN:`Queue1
pub:.ems.pub[`emsint;QN;::]
hdr:`ac`rc`ai!(0h;0h;enlist"")
pub[QN;(enlist`pl;enlist 0Ni;enlist`hdr`payload!(hdr;1 2 3 4)]
Subscribe to a message queue¶
External clients connect to a message queue via registerQueueListener. This call connects the client to the primary message queue and listens for messages from the queue. To disconnect, the client calls unregisterQueueListener.
When a client registers with the message queue, it must provide an acknowledgement mode.
| Name | Value | Description |
|---|---|---|
AUTO |
1 | Acknowledgements are handled by the client automatically. |
CLIENT |
2 | The client is responsible for acknowledging messages in the custom callback function. |
NONE |
3 | No acknowledgement is made. |
In CLIENT mode, messages are acknowledged by invoking ackQueueMessage. This should only be done after the work to process a message has completed.