flux_event_publish(3)

SYNOPSIS

#include <flux/core.h>
flux_future_t *flux_event_publish (flux_t *h,
                                   const char *topic, int flags,
                                   const char *s);
flux_future_t *flux_event_publish_pack (flux_t *h,
                                        const char *topic, int flags,
                                        const char *fmt, ...);
flux_future_t *flux_event_publish_raw (flux_t *h,
                                       const char *topic, int flags,
                                       const void *data, int len);
int flux_event_publish_get_seq (flux_future_t *f, int *seq);

DESCRIPTION

flux_event_publish() sends an event message with topic string topic, flags as described below, and optional payload s, a NULL-terminated string, or NULL indicating no payload. The returned future is fulfilled once the event is accepted by the broker and assigned a global sequence number.

flux_event_publish_pack() is similar, except the JSON payload is constructed using json_pack() style arguments (see below).

flux_event_publish_raw() is similar, except the payload is raw data of length len.

flux_event_publish_get_seq() may be used to retrieve the sequence number assigned to the message once the future is fulfilled.

CONFIRMATION SEMANTICS

All Flux events are "open loop" in the sense that publishers get no confirmation that subscribers have received a message. However, the above functions do confirm, upon fulfillment of the returned future, that the published event has been received by the broker and assigned a global sequence number.

Gaps in the sequence trigger the logging of errors currently, and in the future will trigger recovery of lost events, so these confirmations do indicate that Flux's best effort at event propagation is under way.

If this level of confirmation is not required, one may encode an event message directly using flux_event_encode(3) and related functions and send it directly with flux_send(3).

FLAGS

The flags argument in the above functions must be zero, or the logical OR of the following values:

FLUX_MSGFLAG_PRIVATE
Indicates that the event should only be visible to the instance owner and the sender.

ENCODING JSON PAYLOADS

Flux API functions that are based on Jansson's json_pack() accept the following tokens in their format string. The type in parenthesis denotes the resulting JSON type, and the type in brackets (if any) denotes the C type that is expected as the corresponding argument or arguments.

s (string)['const char *']
Convert a null terminated UTF-8 string to a JSON string.
s# (string)['const char *', 'int']
Convert a UTF-8 buffer of a given length to a JSON string.
s% (string)['const char *', 'size_t']
Like s# but the length argument is of type size_t.
+ ['const char *']
Like s, but concatenate to the previous string. Only valid after a string.
+# ['const char *', 'int']
Like s#, but concatenate to the previous string. Only valid after a string.
+% ['const char *', 'size_t']
Like +#, but the length argument is of type size_t.
n (null)
Output a JSON null value. No argument is consumed.
b (boolean)['int']
Convert a C int to JSON boolean value. Zero is converted to false and non-zero to true.
i (integer)['int']
Convert a C int to JSON integer.
I (integer)['int64_t']
Convert a C int64_t to JSON integer. Note: Jansson expects a json_int_t here without committing to a size, but Flux guarantees that this is a 64-bit integer.
f (real)['double']
Convert a C double to JSON real.
o (any value)['json_t *']
Output any given JSON value as-is. If the value is added to an array or object, the reference to the value passed to o is stolen by the container.
O (any value)['json_t *']
Like o, but the argument's reference count is incremented. This is useful if you pack into an array or object and want to keep the reference for the JSON value consumed by O to yourself.
[fmt] (array)
Build an array with contents from the inner format string. fmt may contain objects and arrays, i.e. recursive value building is supported.
{fmt} (object)
Build an object with contents from the inner format string fmt. The first, third, etc. format specifier represent a key, and must be a string as object keys are always strings. The second, fourth, etc. format specifier represent a value. Any value may be an object or array, i.e. recursive value building is supported.

Whitespace, : (colon) and , (comma) are ignored.

These descriptions came from the Jansson 2.6 manual.

See also: Jansson API: Building Values

RETURN VALUE

These functions return a future on success. On error, NULL is returned, and errno is set appropriately.

ERRORS

EINVAL
Some arguments were invalid.
ENOMEM
Out of memory.
EPROTO
A protocol error was encountered.

SEE ALSO

flux_event_decode(3), flux_event_subscribe(3)