flux_msg_handler_create(3)

SYNOPSIS

#include <flux/core.h>

typedef void (*flux_msg_handler_f)(flux_t *h,
                                   flux_msg_handler_t *mh,
                                   const flux_msg_t *msg,
                                   void *arg);

flux_msg_handler_t *flux_msg_handler_create (
                                   flux_t *h,
                                   const struct flux_match match,
                                   flux_msg_handler_f callback,
                                   void *arg);

void flux_msg_handler_destroy (flux_msg_handler_t *mh);

void flux_msg_handler_start (flux_msg_handler_t *mh);

void flux_msg_handler_stop (flux_msg_handler_t *mh);

Link with -lflux-core.

DESCRIPTION

flux_msg_handler_create() registers callback to be invoked when a message meeting match criteria, as described in flux_msg_cmp(3), is received on Flux broker handle h.

The message handler must be started with flux_msg_handler_start() in order to receive messages. Conversely, flux_msg_handler_stop() causes the message handler to stop receiving messages. Starting and stopping are idempotent operations.

The handle h is monitored for FLUX_POLLIN events on the flux_reactor_t associated with the handle as described in flux_set_reactor(3). This internal "handle watcher" is started when the first message handler is started, and stopped when the last message handler is stopped.

Messages arriving on h are internally read and dispatched to matching message handlers. If multiple handlers match the message, the following rules apply:

FLUX_MSGTYPE_REQUEST: Requests are first delivered to a message handler whose match.topic_glob is set to an exact string match of the message topic glob. The most recently registered of these takes precedence. If an exact match is unavailable, the message is delivered to the most recently registered message handler for which flux_msg_cmp(3) returns true. If there is no match, an ENOSYS response is automatically generated by the dispatcher.
FLUX_MSGTYPE_RESPONSE: Responses are first delivered to a matching RPC response handler (match.matchtag != FLUX_MATCHTAG_NONE). If an RPC response handler does not match, responses are delivered to the most recently registered message handler for which flux_msg_cmp(3) returns true. If there is no match, the response is discarded.
FLUX_MSGTYPE_EVENT: Events are delivered to all matching message handlers.

flux_msg_handler_destroy() destroys a handler, after internally stopping it.

CAVEATS

Although it is possible to register a message handler in a given flux_t handle for any topic string, flux-broker(1) does not automatically route matching requests or events to the handle.

Requests are only routed if the handle has registered a matching service with flux_service_register(3), or for broker modules only, the service matches the module name.

Events are only routed if the topic matches a subscription registered with flux_event_subscribe(3).

RETURN VALUE

flux_msg_handler_create() returns a flux_msg_handler_t object on success. On error, NULL is returned, and errno is set appropriately.

ERRORS

ENOMEM: Out of memory.

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