flux_recv(3)

SYNOPSIS

#include <flux/core.h>

flux_msg_t *flux_recv (flux_t *h,
                       struct flux_match match,
                       int flags);

Link with -lflux-core.

DESCRIPTION

flux_recv() receives a message using the Flux Message broker, previously opened with flux_open(3) on handle h. The message should eventually be destroyed with flux_msg_destroy(3).

match is a message match structure which limits which messages can be received.

struct flux_match {
    int typemask;      // bitmask of matching message types
    uint32_t matchtag; // matchtag
    char *topic_glob;  // glob matching topic string
};

The following initializers are available for match:

FLUX_MATCH_ANY: Match any message.
FLUX_MATCH_EVENT: Match any event message.

For additional details on how to use match, see flux_msg_cmp(3).

flags is the logical "or" of zero or more of the following flags:

FLUX_O_TRACE: Dumps msg to stderr.
FLUX_O_NONBLOCK: If unable to receive a matching message, return an error rather than block.

Internally, flags are the logical "or" of flags and the flags provided to flux_open(3) when the handle was created.

Messages that do not meet match criteria, are requeued with flux_requeue(3) for later consumption.

RETURN VALUE

flux_recv() returns a message on success. On error, NULL is returned, and errno is set appropriately.

ERRORS

ENOSYS: Handle has no recv operation.
EINVAL: Some arguments were invalid.
EAGAIN: FLUX_O_NONBLOCK was selected and flux_recv() would block.

EXAMPLES

This example opens the Flux broker and displays event messages as they arrive.

#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, "") < 0)
        die ("could not subscribe to all events");
    for (;;) {
        if ((msg = flux_recv (h, FLUX_MATCH_EVENT, 0)))
            die ("receive error");
        if (flux_msg_get_topic (msg, &topic) < 0)
            die ("message decode error");
        printf ("Event: %s\n", topic);
        flux_msg_destroy (msg);
    }
    flux_close (h);
    return (0);
}