/*-------------------------------------------------------------------------

 *

 * timeout.c

 *    Routines to multiplex SIGALRM interrupts for multiple timeout reasons.

 *

 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group

 * Portions Copyright (c) 1994, Regents of the University of California

 *

 *

 * IDENTIFICATION

 *    src/backend/utils/misc/timeout.c

 *

 *-------------------------------------------------------------------------

 */

#include "postgres.h"

#include <sys/time.h>

#include "miscadmin.h"

#include "storage/latch.h"

#include "utils/timeout.h"

#include "utils/timestamp.h"

/* Data about any one timeout reason */

typedef struct timeout_params

{

  TimeoutId index;      /* identifier of timeout reason */

  /* volatile because these may be changed from the signal handler */

  volatile bool active;   /* true if timeout is in active_timeouts[] */

  volatile bool indicator;  /* true if timeout has occurred */

  /* callback function for timeout, or NULL if timeout not registered */

  timeout_handler_proc timeout_handler;

  TimestampTz start_time;   /* time that timeout was last activated */

  TimestampTz fin_time;   /* time it is, or was last, due to fire */

  int     interval_in_ms; /* time between firings, or 0 if just once */

} timeout_params;

/*

 * List of possible timeout reasons in the order of enum TimeoutId.

 */

static timeout_params all_timeouts[MAX_TIMEOUTS];

static bool all_timeouts_initialized = false;

/*

 * List of active timeouts ordered by their fin_time and priority.

 * This list is subject to change by the interrupt handler, so it's volatile.

 */

static volatile int num_active_timeouts = 0;

static timeout_params *volatile active_timeouts[MAX_TIMEOUTS];

/*

 * Flag controlling whether the signal handler is allowed to do anything.

 * This is useful to avoid race conditions with the handler.  Note in

 * particular that this lets us make changes in the data structures without

 * tediously disabling and re-enabling the timer signal.  Most of the time,

 * no interrupt would happen anyway during such critical sections, but if

 * one does, this rule ensures it's safe.  Leaving the signal enabled across

 * multiple operations can greatly reduce the number of kernel calls we make,

 * too.  See comments in schedule_alarm() about that.

 *

 * We leave this "false" when we're not expecting interrupts, just in case.

 */

static volatile sig_atomic_t alarm_enabled = false;

#define disable_alarm() (alarm_enabled = false)

#define enable_alarm()  (alarm_enabled = true)

/*

 * State recording if and when we next expect the interrupt to fire.

 * (signal_due_at is valid only when signal_pending is true.)

 * Note that the signal handler will unconditionally reset signal_pending to

 * false, so that can change asynchronously even when alarm_enabled is false.

 */

static volatile sig_atomic_t signal_pending = false;

static volatile TimestampTz signal_due_at = 0;

/*****************************************************************************

 * Internal helper functions

 *

 * For all of these, it is caller's responsibility to protect them from

 * interruption by the signal handler.  Generally, call disable_alarm()

 * first to prevent interruption, then update state, and last call

 * schedule_alarm(), which will re-enable the signal handler if needed.

 *****************************************************************************/

/*

 * Find the index of a given timeout reason in the active array.

 * If it's not there, return -1.

 */

static int

find_active_timeout(TimeoutId id)

{

  int     i;

  for (i = 0; i < num_active_timeouts; i++)

  {

    if (active_timeouts[i]->index == id)

      return i;

  }

  return -1;

}

/*

 * Insert specified timeout reason into the list of active timeouts

 * at the given index.

 */

static void

insert_timeout(TimeoutId id, int index)

{

  int     i;

  if (index < 0 || index > num_active_timeouts)

    elog(FATAL, "timeout index %d out of range 0..%d", index,

       num_active_timeouts);

  Assert(!all_timeouts[id].active);

  all_timeouts[id].active = true;

  for (i = num_active_timeouts - 1; i >= index; i--)

    active_timeouts[i + 1] = active_timeouts[i];

  active_timeouts[index] = &all_timeouts[id];

  num_active_timeouts++;

}

/*

 * Remove the index'th element from the timeout list.

 */

static void

remove_timeout_index(int index)

{

  int     i;

  if (index < 0 || index >= num_active_timeouts)

    elog(FATAL, "timeout index %d out of range 0..%d", index,

       num_active_timeouts - 1);

  Assert(active_timeouts[index]->active);

  active_timeouts[index]->active = false;

  for (i = index + 1; i < num_active_timeouts; i++)

    active_timeouts[i - 1] = active_timeouts[i];

  num_active_timeouts--;

}

/*

 * Enable the specified timeout reason

 */

static void

enable_timeout(TimeoutId id, TimestampTz now, TimestampTz fin_time,

         int interval_in_ms)

{

  int     i;

  /* Assert request is sane */

  Assert(all_timeouts_initialized);

  Assert(all_timeouts[id].timeout_handler != NULL);

  /*

   * If this timeout was already active, momentarily disable it.  We

   * interpret the call as a directive to reschedule the timeout.

   */

  if (all_timeouts[id].active)

    remove_timeout_index(find_active_timeout(id));

  /*

   * Find out the index where to insert the new timeout.  We sort by

   * fin_time, and for equal fin_time by priority.

   */

  for (i = 0; i < num_active_timeouts; i++)

  {

    timeout_params *old_timeout = active_timeouts[i];

    if (fin_time < old_timeout->fin_time)

      break;

    if (fin_time == old_timeout->fin_time && id < old_timeout->index)

      break;

  }

  /*

   * Mark the timeout active, and insert it into the active list.

   */

  all_timeouts[id].indicator = false;

  all_timeouts[id].start_time = now;

  all_timeouts[id].fin_time = fin_time;

  all_timeouts[id].interval_in_ms = interval_in_ms;

  insert_timeout(id, i);

}

/*

 * Schedule alarm for the next active timeout, if any

 *

 * We assume the caller has obtained the current time, or a close-enough

 * approximation.  (It's okay if a tick or two has passed since "now", or

 * if a little more time elapses before we reach the kernel call; that will

 * cause us to ask for an interrupt a tick or two later than the nearest

 * timeout, which is no big deal.  Passing a "now" value that's in the future

 * would be bad though.)

 */

static void

schedule_alarm(TimestampTz now)

{

  if (num_active_timeouts > 0)

  {

    struct itimerval timeval;

    TimestampTz nearest_timeout;

    long    secs;

    int     usecs;

    MemSet(&timeval, 0, sizeof(struct itimerval));

    /*

     * If we think there's a signal pending, but current time is more than

     * 10ms past when the signal was due, then assume that the timeout

     * request got lost somehow; clear signal_pending so that we'll reset

     * the interrupt request below.  (10ms corresponds to the worst-case

     * timeout granularity on modern systems.)  It won't hurt us if the

     * interrupt does manage to fire between now and when we reach the

     * setitimer() call.

     */

    if (signal_pending && now > signal_due_at + 10 * 1000)

      signal_pending = false;

    /*

     * Get the time remaining till the nearest pending timeout.  If it is

     * negative, assume that we somehow missed an interrupt, and clear

     * signal_pending.  This gives us another chance to recover if the

     * kernel drops a timeout request for some reason.

     */

    nearest_timeout = active_timeouts[0]->fin_time;

    if (now > nearest_timeout)

    {

      signal_pending = false;

      /* force an interrupt as soon as possible */

      secs = 0;

      usecs = 1;

    }

    else

    {

      TimestampDifference(now, nearest_timeout,

                &secs, &usecs);

      /*

       * It's possible that the difference is less than a microsecond;

       * ensure we don't cancel, rather than set, the interrupt.

       */

      if (secs == 0 && usecs == 0)

        usecs = 1;

    }

    timeval.it_value.tv_sec = secs;

    timeval.it_value.tv_usec = usecs;

    /*

     * We must enable the signal handler before calling setitimer(); if we

     * did it in the other order, we'd have a race condition wherein the

     * interrupt could occur before we can set alarm_enabled, so that the

     * signal handler would fail to do anything.

     *

     * Because we didn't bother to disable the timer in disable_alarm(),

     * it's possible that a previously-set interrupt will fire between

     * enable_alarm() and setitimer().  This is safe, however.  There are

     * two possible outcomes:

     *

     * 1. The signal handler finds nothing to do (because the nearest

     * timeout event is still in the future).  It will re-set the timer

     * and return.  Then we'll overwrite the timer value with a new one.

     * This will mean that the timer fires a little later than we

     * intended, but only by the amount of time it takes for the signal

     * handler to do nothing useful, which shouldn't be much.

     *

     * 2. The signal handler executes and removes one or more timeout

     * events.  When it returns, either the queue is now empty or the

     * frontmost event is later than the one we looked at above.  So we'll

     * overwrite the timer value with one that is too soon (plus or minus

     * the signal handler's execution time), causing a useless interrupt

     * to occur.  But the handler will then re-set the timer and

     * everything will still work as expected.

     *

     * Since these cases are of very low probability (the window here

     * being quite narrow), it's not worth adding cycles to the mainline

     * code to prevent occasional wasted interrupts.

     */

    enable_alarm();

    /*

     * If there is already an interrupt pending that's at or before the

     * needed time, we need not do anything more.  The signal handler will

     * do the right thing in the first case, and re-schedule the interrupt

     * for later in the second case.  It might seem that the extra

     * interrupt is wasted work, but it's not terribly much work, and this

     * method has very significant advantages in the common use-case where

     * we repeatedly set a timeout that we don't expect to reach and then

     * cancel it.  Instead of invoking setitimer() every time the timeout

     * is set or canceled, we perform one interrupt and a re-scheduling

     * setitimer() call at intervals roughly equal to the timeout delay.

     * For example, with statement_timeout = 1s and a throughput of

     * thousands of queries per second, this method requires an interrupt

     * and setitimer() call roughly once a second, rather than thousands

     * of setitimer() calls per second.

     *

     * Because of the possible passage of time between when we obtained

     * "now" and when we reach setitimer(), the kernel's opinion of when

     * to trigger the interrupt is likely to be a bit later than

     * signal_due_at.  That's fine, for the same reasons described above.

     */

    if (signal_pending && nearest_timeout >= signal_due_at)

      return;

    /*

     * As with calling enable_alarm(), we must set signal_pending *before*

     * calling setitimer(); if we did it after, the signal handler could

     * trigger before we set it, leaving us with a false opinion that a

     * signal is still coming.

     *

     * Other race conditions involved with setting/checking signal_pending

     * are okay, for the reasons described above.  One additional point is

     * that the signal handler could fire after we set signal_due_at, but

     * still before the setitimer() call.  Then the handler could

     * overwrite signal_due_at with a value it computes, which will be the

     * same as or perhaps later than what we just computed.  After we

     * perform setitimer(), the net effect would be that signal_due_at

     * gives a time later than when the interrupt will really happen;

     * which is a safe situation.

     */

    signal_due_at = nearest_timeout;

    signal_pending = true;

    /* Set the alarm timer */

    if (setitimer(ITIMER_REAL, &timeval, NULL) != 0)

    {

      /*

       * Clearing signal_pending here is a bit pro forma, but not

       * entirely so, since something in the FATAL exit path could try

       * to use timeout facilities.

       */

      signal_pending = false;

      elog(FATAL, "could not enable SIGALRM timer: %m");

    }

  }

}

/*****************************************************************************

 * Signal handler

 *****************************************************************************/

/*

 * Signal handler for SIGALRM

 *

 * Process any active timeout reasons and then reschedule the interrupt

 * as needed.

 */

static void

handle_sig_alarm(SIGNAL_ARGS)

{

  /*

   * Bump the holdoff counter, to make sure nothing we call will process

   * interrupts directly. No timeout handler should do that, but these

   * failures are hard to debug, so better be sure.

   */

  HOLD_INTERRUPTS();

  /*

   * SIGALRM is always cause for waking anything waiting on the process

   * latch.

   */

  SetLatch(MyLatch);

  /*

   * Always reset signal_pending, even if !alarm_enabled, since indeed no

   * signal is now pending.

   */

  signal_pending = false;

  /*

   * Fire any pending timeouts, but only if we're enabled to do so.

   */

  if (alarm_enabled)

  {

    /*

     * Disable alarms, just in case this platform allows signal handlers

     * to interrupt themselves.  schedule_alarm() will re-enable if

     * appropriate.

     */

    disable_alarm();

    if (num_active_timeouts > 0)

    {

      TimestampTz now = GetCurrentTimestamp();

      /* While the first pending timeout has been reached ... */

      while (num_active_timeouts > 0 &&

           now >= active_timeouts[0]->fin_time)

      {

        timeout_params *this_timeout = active_timeouts[0];

        /* Remove it from the active list */

        remove_timeout_index(0);

        /* Mark it as fired */

        this_timeout->indicator = true;

        /* And call its handler function */

        this_timeout->timeout_handler();

        /* If it should fire repeatedly, re-enable it. */

        if (this_timeout->interval_in_ms > 0)

        {

          TimestampTz new_fin_time;

          /*

           * To guard against drift, schedule the next instance of

           * the timeout based on the intended firing time rather

           * than the actual firing time. But if the timeout was so

           * late that we missed an entire cycle, fall back to

           * scheduling based on the actual firing time.

           */

          new_fin_time =

            TimestampTzPlusMilliseconds(this_timeout->fin_time,

                          this_timeout->interval_in_ms);

          if (new_fin_time < now)

            new_fin_time =

              TimestampTzPlusMilliseconds(now,

                            this_timeout->interval_in_ms);

          enable_timeout(this_timeout->index, now, new_fin_time,

                   this_timeout->interval_in_ms);

        }

        /*

         * The handler might not take negligible time (CheckDeadLock

         * for instance isn't too cheap), so let's update our idea of

         * "now" after each one.

         */

        now = GetCurrentTimestamp();

      }

      /* Done firing timeouts, so reschedule next interrupt if any */

      schedule_alarm(now);

    }

  }

  RESUME_INTERRUPTS();

}

/*****************************************************************************

 * Public API

 *****************************************************************************/

/*

 * Initialize timeout module.

 *

 * This must be called in every process that wants to use timeouts.

 *

 * If the process was forked from another one that was also using this

 * module, be sure to call this before re-enabling signals; else handlers

 * meant to run in the parent process might get invoked in this one.

 */

void

InitializeTimeouts(void)

{

  int     i;

  /* Initialize, or re-initialize, all local state */

  disable_alarm();

  num_active_timeouts = 0;

  for (i = 0; i < MAX_TIMEOUTS; i++)

  {

    all_timeouts[i].index = i;

    all_timeouts[i].active = false;

    all_timeouts[i].indicator = false;

    all_timeouts[i].timeout_handler = NULL;

    all_timeouts[i].start_time = 0;

    all_timeouts[i].fin_time = 0;

    all_timeouts[i].interval_in_ms = 0;

  }

  all_timeouts_initialized = true;

  /* Now establish the signal handler */

  pqsignal(SIGALRM, handle_sig_alarm);

}

/*

 * Register a timeout reason

 *

 * For predefined timeouts, this just registers the callback function.

 *

 * For user-defined timeouts, pass id == USER_TIMEOUT; we then allocate and

 * return a timeout ID.

 */

TimeoutId

RegisterTimeout(TimeoutId id, timeout_handler_proc handler)

{

  Assert(all_timeouts_initialized);

  /* There's no need to disable the signal handler here. */

  if (id >= USER_TIMEOUT)

  {

    /* Allocate a user-defined timeout reason */

    for (id = USER_TIMEOUT; id < MAX_TIMEOUTS; id++)

      if (all_timeouts[id].timeout_handler == NULL)

        break;

    if (id >= MAX_TIMEOUTS)

      ereport(FATAL,

          (errcode(ERRCODE_CONFIGURATION_LIMIT_EXCEEDED),

           errmsg("cannot add more timeout reasons")));

  }

  Assert(all_timeouts[id].timeout_handler == NULL);

  all_timeouts[id].timeout_handler = handler;

  return id;

}

/*

 * Reschedule any pending SIGALRM interrupt.

 *

 * This can be used during error recovery in case query cancel resulted in loss

 * of a SIGALRM event (due to longjmp'ing out of handle_sig_alarm before it

 * could do anything).  But note it's not necessary if any of the public

 * enable_ or disable_timeout functions are called in the same area, since

 * those all do schedule_alarm() internally if needed.

 */

void

reschedule_timeouts(void)

{

  /* For flexibility, allow this to be called before we're initialized. */

  if (!all_timeouts_initialized)

    return;

  /* Disable timeout interrupts for safety. */

  disable_alarm();

  /* Reschedule the interrupt, if any timeouts remain active. */

  if (num_active_timeouts > 0)

    schedule_alarm(GetCurrentTimestamp());

}

/*

 * Enable the specified timeout to fire after the specified delay.

 *

 * Delay is given in milliseconds.

 */

void

enable_timeout_after(TimeoutId id, int delay_ms)

{

  TimestampTz now;

  TimestampTz fin_time;

  /* Disable timeout interrupts for safety. */

  disable_alarm();

  /* Queue the timeout at the appropriate time. */

  now = GetCurrentTimestamp();

  fin_time = TimestampTzPlusMilliseconds(now, delay_ms);

  enable_timeout(id, now, fin_time, 0);

  /* Set the timer interrupt. */

  schedule_alarm(now);

}

/*

 * Enable the specified timeout to fire periodically, with the specified

 * delay as the time between firings.

 *

 * Delay is given in milliseconds.

 */

void

enable_timeout_every(TimeoutId id, TimestampTz fin_time, int delay_ms)

{

  TimestampTz now;

  /* Disable timeout interrupts for safety. */

  disable_alarm();

  /* Queue the timeout at the appropriate time. */

  now = GetCurrentTimestamp();

  enable_timeout(id, now, fin_time, delay_ms);

  /* Set the timer interrupt. */

  schedule_alarm(now);

}

/*

 * Enable the specified timeout to fire at the specified time.

 *

 * This is provided to support cases where there's a reason to calculate

 * the timeout by reference to some point other than "now".  If there isn't,

 * use enable_timeout_after(), to avoid calling GetCurrentTimestamp() twice.

 */

void

enable_timeout_at(TimeoutId id, TimestampTz fin_time)

{

  TimestampTz now;

  /* Disable timeout interrupts for safety. */

  disable_alarm();

  /* Queue the timeout at the appropriate time. */

  now = GetCurrentTimestamp();

  enable_timeout(id, now, fin_time, 0);

  /* Set the timer interrupt. */

  schedule_alarm(now);

}

/*

 * Enable multiple timeouts at once.

 *

 * This works like calling enable_timeout_after() and/or enable_timeout_at()

 * multiple times.  Use this to reduce the number of GetCurrentTimestamp()

 * and setitimer() calls needed to establish multiple timeouts.

 */

void

enable_timeouts(const EnableTimeoutParams *timeouts, int count)

{

  TimestampTz now;

  int     i;

  /* Disable timeout interrupts for safety. */

  disable_alarm();

  /* Queue the timeout(s) at the appropriate times. */

  now = GetCurrentTimestamp();

  for (i = 0; i < count; i++)

  {

    TimeoutId id = timeouts[i].id;

    TimestampTz fin_time;

    switch (timeouts[i].type)

    {

      case TMPARAM_AFTER:

        fin_time = TimestampTzPlusMilliseconds(now,

                             timeouts[i].delay_ms);

        enable_timeout(id, now, fin_time, 0);

        break;

      case TMPARAM_AT:

        enable_timeout(id, now, timeouts[i].fin_time, 0);

        break;

      case TMPARAM_EVERY:

        fin_time = TimestampTzPlusMilliseconds(now,

                             timeouts[i].delay_ms);

        enable_timeout(id, now, fin_time, timeouts[i].delay_ms);

        break;

      default:

        elog(ERROR, "unrecognized timeout type %d",

           (int) timeouts[i].type);

        break;

    }

  }

  /* Set the timer interrupt. */

  schedule_alarm(now);

}

/*

 * Cancel the specified timeout.

 *

 * The timeout's I've-been-fired indicator is reset,

 * unless keep_indicator is true.

 *

 * When a timeout is canceled, any other active timeout remains in force.

 * It's not an error to disable a timeout that is not enabled.

 */

void

disable_timeout(TimeoutId id, bool keep_indicator)

{

  /* Assert request is sane */

  Assert(all_timeouts_initialized);

  Assert(all_timeouts[id].timeout_handler != NULL);

  /* Disable timeout interrupts for safety. */

  disable_alarm();

  /* Find the timeout and remove it from the active list. */

  if (all_timeouts[id].active)

    remove_timeout_index(find_active_timeout(id));

  /* Mark it inactive, whether it was active or not. */

  if (!keep_indicator)

    all_timeouts[id].indicator = false;

  /* Reschedule the interrupt, if any timeouts remain active. */

  if (num_active_timeouts > 0)

    schedule_alarm(GetCurrentTimestamp());

}

/*

 * Cancel multiple timeouts at once.

 *

 * The timeouts' I've-been-fired indicators are reset,

 * unless timeouts[i].keep_indicator is true.

 *

 * This works like calling disable_timeout() multiple times.

 * Use this to reduce the number of GetCurrentTimestamp()

 * and setitimer() calls needed to cancel multiple timeouts.

 */

void

disable_timeouts(const DisableTimeoutParams *timeouts, int count)

{

  int     i;

  Assert(all_timeouts_initialized);

  /* Disable timeout interrupts for safety. */

  disable_alarm();

  /* Cancel the timeout(s). */

  for (i = 0; i < count; i++)

  {

    TimeoutId id = timeouts[i].id;

    Assert(all_timeouts[id].timeout_handler != NULL);

    if (all_timeouts[id].active)

      remove_timeout_index(find_active_timeout(id));

    if (!timeouts[i].keep_indicator)

      all_timeouts[id].indicator = false;

  }

  /* Reschedule the interrupt, if any timeouts remain active. */

  if (num_active_timeouts > 0)

    schedule_alarm(GetCurrentTimestamp());

}

/*

 * Disable the signal handler, remove all timeouts from the active list,

 * and optionally reset their timeout indicators.

 */

void

disable_all_timeouts(bool keep_indicators)

{

  int     i;

  disable_alarm();

  /*

   * We used to disable the timer interrupt here, but in common usage

   * patterns it's cheaper to leave it enabled; that may save us from having

   * to enable it again shortly.  See comments in schedule_alarm().

   */

  num_active_timeouts = 0;

  for (i = 0; i < MAX_TIMEOUTS; i++)

  {

    all_timeouts[i].active = false;

    if (!keep_indicators)

      all_timeouts[i].indicator = false;

  }

}

/*

 * Return true if the timeout is active (enabled and not yet fired)

 *

 * This is, of course, subject to race conditions, as the timeout could fire

 * immediately after we look.

 */

bool

get_timeout_active(TimeoutId id)

{

  return all_timeouts[id].active;

}

/*

 * Return the timeout's I've-been-fired indicator

 *

 * If reset_indicator is true, reset the indicator when returning true.

 * To avoid missing timeouts due to race conditions, we are careful not to

 * reset the indicator when returning false.

 */

bool

get_timeout_indicator(TimeoutId id, bool reset_indicator)

{

  if (all_timeouts[id].indicator)

  {

    if (reset_indicator)

      all_timeouts[id].indicator = false;

    return true;

  }

  return false;

}

/*

 * Return the time when the timeout was most recently activated

 *

 * Note: will return 0 if timeout has never been activated in this process.

 * However, we do *not* reset the start_time when a timeout occurs, so as

 * not to create a race condition if SIGALRM fires just as some code is

 * about to fetch the value.

 */

TimestampTz

get_timeout_start_time(TimeoutId id)

{

  return all_timeouts[id].start_time;

}

/*

 * Return the time when the timeout is, or most recently was, due to fire

 *

 * Note: will return 0 if timeout has never been activated in this process.

 * However, we do *not* reset the fin_time when a timeout occurs, so as

 * not to create a race condition if SIGALRM fires just as some code is

 * about to fetch the value.

 */

TimestampTz

get_timeout_finish_time(TimeoutId id)

{

  return all_timeouts[id].fin_time;

}