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);

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 "src/common/libutil/log.h"

int main (int argc, char **argv)
{
    flux_t *h;
    flux_msg_t *msg;
    const char *topic;

    if (!(h = flux_open (NULL, 0)))
        log_err_exit ("flux_open");
    if (flux_event_subscribe (h, "heartbeat.pulse") < 0)
        log_err_exit ("flux_event_subscribe");
    if (!(msg = flux_recv (h, FLUX_MATCH_EVENT, 0)))
        log_err_exit ("flux_recv");
    if (flux_msg_get_topic (msg, &topic) < 0)
        log_err_exit ("flux_msg_get_topic");
    printf ("Event: %s\n", topic);
    if (flux_event_unsubscribe (h, "heartbeat.pulse") < 0)
        log_err_exit ("flux_event_unsubscribe");
    flux_msg_destroy (msg);
    flux_close (h);
    return (0);
}