flux_event_subscribe(3)
SYNOPSIS
#include <flux/core.h>
int flux_event_subscribe (flux_t *h, const char *topic);
int flux_event_unsubscribe (flux_t *h, const char *topic);
Link with -lflux-core.
DESCRIPTION
Flux events are broadcast across the session, but are only delivered to handles that subscribe to them by topic. Topic strings consist of one or more words separated by periods, interpreted as a hierarchical name space.
flux_event_subscribe()
requests that event messages matching topic
be delivered via flux_recv(3). A match consists of a string comparison
of the event topic and the subscription topic, up to the length of the
subscription topic. Thus "foo." matches events with topics "foo.bar"
and "foo.baz", and "" matches all events. This matching algorithm
is inherited from ZeroMQ. Globs or regular expressions are not allowed
in subscriptions, and the period delimiter is included in the comparison.
flux_event_unsubscribe()
unsubscribes to a topic. The topic
argument must exactly match that provided to flux_event_subscribe()
.
Duplicate subscriptions are allowed in the subscription list but will not result in multiple deliveries of a given message. Each duplicate subscription requires a separate unsubscribe.
It is not necessary to remove subscriptions with flux_event_unsubscribe()
prior to calling flux_close(3).
RETURN VALUE
These functions return 0 on success. On error, -1 is returned, and errno is set appropriately.
ERRORS
- EINVAL
Some arguments were invalid.
- ENOMEM
Out of memory.
EXAMPLES
This example opens the Flux broker, subscribes to heartbeat messages, displays one, then quits.
#include <flux/core.h>
#include "die.h"
int main (int argc, char **argv)
{
flux_t *h;
flux_msg_t *msg;
const char *topic;
if (!(h = flux_open (NULL, 0)))
die ("could not connect to broker");
if (flux_event_subscribe (h, "heartbeat.pulse") < 0)
die ("error subscribing to heartbeat");
if (!(msg = flux_recv (h, FLUX_MATCH_EVENT, 0)))
die ("message receive error");
if (flux_msg_get_topic (msg, &topic) < 0)
die ("error decoding message");
printf ("Event: %s\n", topic);
(void)flux_event_unsubscribe (h, "heartbeat.pulse");
flux_msg_destroy (msg);
flux_close (h);
return (0);
}
RESOURCES
Flux: http://flux-framework.org
Flux RFC: https://flux-framework.readthedocs.io/projects/flux-rfc
Issue Tracker: https://github.com/flux-framework/flux-core/issues