==========================
flux_msg_handler_create(3)
==========================

.. default-domain:: c

SYNOPSIS
========

.. code-block:: c

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

   flux_watcher_t *flux_get_handle_watcher(flux_t *h)

Link with :command:`-lflux-core`.

DESCRIPTION
===========

:func:`flux_msg_handler_create` registers :var:`callback` to be invoked when
a message meeting :var:`match` criteria, as described in :man3:`flux_msg_cmp`,
is received on Flux broker handle :var:`h`.

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

The handle :var:`h` is monitored for FLUX_POLLIN events on the
:type:`flux_reactor_t` associated with the handle as described in
:man3:`flux_set_reactor`.  This internal "handle watcher" is started when the
first message handler is started, and stopped when the last message handler
is stopped.  The handle watcher may be directly accessed with
:func:`flux_get_handle_watcher`.

Messages arriving on :var:`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
   :var:`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 :man3:`flux_msg_cmp` 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
   (:var:`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 :man3:`flux_msg_cmp` returns true. If there is no
   match, the response is discarded.

FLUX_MSGTYPE_EVENT
   Events are delivered to *all* matching message handlers.

:func:`flux_msg_handler_destroy` destroys a handler, after internally
stopping it.

The message handler defaults to the role of FLUX_ROLE_OWNER.  See
:func:`flux_msg_handler_allow_rolemask` to adjust the rolemask.


CAVEATS
=======

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

Requests are only routed if the handle has registered a matching service
with :man3:`flux_service_register`, or for broker modules only, the service
matches the module name.

Events are only routed if the topic matches a subscription registered
with :man3:`flux_event_subscribe`.


RETURN VALUE
============

:func:`flux_msg_handler_create` returns a :type:`flux_msg_handler_t` object on
success.  On error, NULL is returned, and :var:`errno` is set appropriately.


ERRORS
======

ENOMEM
   Out of memory.


RESOURCES
=========

.. include:: common/resources.rst


SEE ALSO
========

:man3:`flux_get_reactor`, :man3:`flux_reactor_run`, :man3:`flux_msg_cmp`,
:man3:`flux_msg_handler_allow_rolemask`