libiphb.c

/**
   @brief Self-contained timerfd implementation of libiphb.

   @file libiphb.c

   Each iphb handle owns a private timerfd instead of talking to a heartbeat
   server over a socket. See README.md for the rationale, the ABI-compatibility
   notes, and the CAP_WAKE_ALARM requirement for suspend-waking timers.

   This file is part of libiphb-timerfd and is distributed under the GNU Lesser
   General Public License version 2.1 (see COPYING).
*/

#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include <errno.h>
#include <time.h>
#include <poll.h>
#include <stdint.h>
#include <sys/timerfd.h>

#include "libiphb.h"

#ifndef CLOCK_BOOTTIME_ALARM
# define CLOCK_BOOTTIME_ALARM 9
#endif
#ifndef CLOCK_BOOTTIME
# define CLOCK_BOOTTIME 7
#endif

/** Allocated structure for an iphb handle. */
struct _iphb_t {
  int fd;       /*!< timerfd used for the wakeup */
  int alarm;    /*!< non-zero if fd is an alarm clock (wakes from suspend) */
};

#define HB_INST(x) ((struct _iphb_t *)(x))

/* Drain any pending expirations from the timerfd. The fd is non-blocking, so
 * this returns once there is nothing left to read. Returns the number of bytes
 * consumed, or -1 on a real error. */
static int
iphb_drain(int fd)
{
  int total = 0;
  for (;;) {
    uint64_t exp = 0;
    ssize_t rc = read(fd, &exp, sizeof exp);
    if (rc > 0) {
      total += (int)rc;
      continue;
    }
    if (rc == 0)
      break;
    if (errno == EAGAIN || errno == EWOULDBLOCK)
      break;
    if (errno == EINTR)
      continue;
    return -1;
  }
  return total;
}

/* Arm (or, when seconds == 0, disarm) the timerfd to fire "seconds" from now,
 * relative to the timerfd's own clock. */
static int
iphb_arm(int fd, unsigned seconds)
{
  struct itimerspec its;
  memset(&its, 0, sizeof its);
  its.it_value.tv_sec  = (time_t)seconds;
  its.it_value.tv_nsec = 0;
  /* One-shot: it_interval stays zero. */
  return timerfd_settime(fd, 0, &its, NULL);
}

iphb_t
iphb_open(int *dummy)
{
  struct _iphb_t *self = calloc(1, sizeof *self);
  if (!self) {
    errno = ENOMEM;
    return 0;
  }

  /* Prefer an alarm clock so wakeups can end (auto)suspend. This needs
   * CAP_WAKE_ALARM; unprivileged callers transparently fall back to a plain
   * boottime timer that only fires while the device is awake. */
  self->fd = timerfd_create(CLOCK_BOOTTIME_ALARM, TFD_NONBLOCK | TFD_CLOEXEC);
  self->alarm = 1;
  if (self->fd == -1) {
    self->fd = timerfd_create(CLOCK_BOOTTIME, TFD_NONBLOCK | TFD_CLOEXEC);
    self->alarm = 0;
  }
  if (self->fd == -1) {
    int saved = errno;
    free(self);
    errno = saved;
    return 0;
  }

  if (dummy)
    *dummy = 30; /* for compatibility with the old API */

  return self;
}

int
iphb_get_fd(iphb_t iphbh)
{
  if (!iphbh) {
    errno = EINVAL;
    return -1;
  }
  return HB_INST(iphbh)->fd;
}

time_t
iphb_wait2(iphb_t iphbh, unsigned mintime, unsigned maxtime, int must_wait,
           int resume)
{
  (void)resume; /* clock type is fixed at open time; see iphb_open */

  if (!iphbh || mintime > maxtime) {
    errno = EINVAL;
    return (time_t)-1;
  }

  struct _iphb_t *self = HB_INST(iphbh);

  /* Clear any wakeup that fired for a previous request. */
  if (iphb_drain(self->fd) == -1)
    return (time_t)-1;

  /* mintime == maxtime == 0 cancels the pending wakeup (matches the old
   * server semantics used by callers to stop waiting). */
  if (maxtime == 0) {
    if (iphb_arm(self->fd, 0) == -1)
      return (time_t)-1;
    return 0;
  }

  /* Wake at the far end of the [mintime, maxtime] window: it honours the
   * mandatory minimum wait and maximises the chance of coalescing with other
   * wakeups / staying suspended as long as allowed. */
  if (iphb_arm(self->fd, maxtime) == -1)
    return (time_t)-1;

  if (!must_wait)
    return 0;

  /* Blocking variant: wait here until the timer fires. */
  struct timespec beg = { 0, 0 };
  clock_gettime(CLOCK_MONOTONIC, &beg);

  for (;;) {
    struct pollfd pfd = { .fd = self->fd, .events = POLLIN };
    int rc = poll(&pfd, 1, -1);
    if (rc > 0) {
      (void)iphb_drain(self->fd);
      struct timespec end = { 0, 0 };
      clock_gettime(CLOCK_MONOTONIC, &end);
      return (time_t)(end.tv_sec - beg.tv_sec);
    }
    if (rc == -1 && errno != EINTR)
      return (time_t)-1;
  }
}

time_t
iphb_wait(iphb_t iphbh, unsigned short mintime, unsigned short maxtime,
          int must_wait)
{
  return iphb_wait2(iphbh, mintime, maxtime, must_wait, 1);
}

int
iphb_I_woke_up(iphb_t iphbh)
{
  if (!iphbh) {
    errno = EINVAL;
    return -1;
  }
  struct _iphb_t *self = HB_INST(iphbh);
  int drained = iphb_drain(self->fd);
  /* Woken by some other means: cancel the outstanding wakeup. */
  (void)iphb_arm(self->fd, 0);
  return drained;
}

int
iphb_discard_wakeups(iphb_t iphbh)
{
  if (!iphbh) {
    errno = EINVAL;
    return -1;
  }
  return iphb_drain(HB_INST(iphbh)->fd);
}

int
iphb_get_stats(iphb_t iphbh, struct iphb_stats *stats)
{
  if (!iphbh || !stats) {
    errno = EINVAL;
    return -1;
  }
  /* There is no central server to aggregate statistics any more. Report a
   * single local client so callers that sanity-check the struct keep working. */
  stats->clients = 1;
  stats->waiting = 0;
  stats->next_hb = 0;
  return 0;
}

iphb_t
iphb_close(iphb_t iphbh)
{
  if (iphbh) {
    struct _iphb_t *self = HB_INST(iphbh);
    if (self->fd != -1)
      close(self->fd);
    free(self);
  }
  return 0;
}