flux_open(3)

SYNOPSIS

#include <flux/core.h>

flux_t *flux_open (const char *uri, int flags);

flux_t *flux_open_ex (const char *uri,
                      int flags,
                      flux_error_t *error);

void flux_close (flux_t *h);

flux_t *flux_clone (flux_t *h);

int flux_reconnect (flux_t *h);

Link with -lflux-core.

DESCRIPTION

flux_open() and flux_open_ex() create a flux_t handle, used to communicate with the Flux message broker. flux_open_ex() takes an optional pointer to a flux_error_t structure which, when non-NULL, will be used to store any errors which may have otherwise gone to stderr.

The uri scheme (before "://") specifies the "connector" that will be used to establish the connection. The uri path (after "://") is parsed by the connector. If uri is NULL, the value of FLUX_URI is used. If FLUX_URI is not set, a compiled-in default URI is used.

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

FLUX_O_TRACE: Dumps message trace to stderr.
FLUX_O_CLONE: Used internally by flux_clone() (see below).
FLUX_O_MATCHDEBUG: Prints diagnostic to stderr when matchtags are leaked, for example when a streaming RPC is destroyed without receiving a error response as end-of-stream, or a regular RPC is destroyed without being fulfilled at all.
FLUX_O_NONBLOCK: The flux_send(3) and flux_recv(3) functions should never block.
FLUX_O_TEST_NOSUB: Make flux_event_subscribe(3) and flux_event_unsubscribe(3) no-ops. This may be useful in specialized situations with the loop:// connector, where no message handler is available to service subscription RPCs.
FLUX_O_RPCTRACK: Track pending RPCs so that they can receive automatic ECONNRESET failure responses if the broker connection is re-established with flux_reconnect(). Tracking incurs a small overhead. This flag can only be specified with flux_open(), not flux_flags_set(3).

flux_reconnect() may be called from a communications error callback registered with flux_comms_error_set(3). The current connection is closed and a new one is established with a new UUID. Since responses addressed to the old UUID will not be routed to the new connection, RPCs that are pending before flux_reconnect() remain pending indefinitely without FLUX_O_RPCTRACK. After a successful reconnect, the following additional steps may be needed before a client can continue normal operation:

Wait until the broker has entered RUN state by making an RPC to state_machine.wait
Restore service registrations.
Restore event subscriptions.

flux_clone() creates another reference to a flux_t handle that is identical to the original in all respects except that it does not inherit a copy of the original handle's "aux" hash, or its reactor and message dispatcher references. By creating a clone, and calling flux_set_reactor(3) on it, one can create message handlers on the cloned handle that run on a different reactor than the one associated with the original handle.

flux_close() destroys a flux_t handle, closing its connection with the Flux message broker.

RETURN VALUE

flux_open() and flux_clone() return a flux_t` handle on success. On error, NULL is returned, with errno set.

ERRORS

EINVAL: One or more arguments was invalid.
ENOMEM: Out of memory.

EXAMPLES

This example opens the Flux broker using the default connector and path, requests the broker rank, and finally closes the broker handle.

#include <flux/core.h>
#include "die.h"

int main (int argc, char **argv)
{
    flux_t *h;
    uint32_t rank;

    if (!(h = flux_open (NULL, 0)))
        die ("could not connect to broker");
    if (flux_get_rank (h, &rank) < 0)
        die ("could not get rank");
    printf ("My rank is %d\n", (int)rank);
    flux_close (h);
    return (0);
}