flux_sync_create(3)

SYNOPSIS

#include <flux/core.h>

flux_future_t *flux_sync_create (flux_t *h, double minimum);

Link with -lflux-core.

DESCRIPTION

flux_sync_create() creates a future that is fulfilled when the system heartbeat message is received. System heartbeats are event messages published periodically at a configurable interval. Synchronizing Flux internal overhead to the heartbeat can, in theory, reduce disruption to bulk synchronous applications.

If minimum is greater than zero, it establishes a minimum time in seconds between fulfillments. Heartbeats that arrive too soon after the last one are ignored. This may be used to protect from thrashing if the heartbeat period is set too fast, or if heartbeats arrive close to one another in time due to overlay network congestion.

A maximum time between fulfillments may be established by specifying a continuation timeout with flux_future_then(3). If the timeout expires, the future is fulfilled with an error (ETIMEDOUT), as usual.

On each fulfillment, flux_future_reset(3) should be called to enable the future to be fulfilled again, and to re-start any timeout.

RETURN VALUE

flux_sync_create() returns a future, or NULL on failure with errno set.

ERRORS

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

EXAMPLE

Set up a continuation callback for each heartbeat that arrives at least sync_min seconds from the last, with a timeout of sync_max seconds:

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

const double sync_min = 1.0;
const double sync_max = 60.0;

void sync_continuation (flux_future_t *f, void *arg)
{
    // do work here
    flux_future_reset (f);
}

int main (int argc, char **argv)
{
    flux_t *h;
    flux_future_t *f;

    if (!(h = flux_open (NULL, 0)))
        die ("could not connect to broker");

    if (!(f = flux_sync_create (h, sync_max)))
        die ("error creating future");

    if (flux_future_then (f, sync_min, sync_continuation, NULL) < 0)
        die ("error registering continuation");

    if (flux_reactor_run (flux_get_reactor (h), 0) < 0)
        die ("reactor returned with error");

    flux_future_destroy (f);

    flux_close (h);
    return (0);
}