+section: rts

+issues: #27105

+mrs: !16023

+synopsis: RTS stopTicker is asynchronous, but is used relying on it being synchronous.

+description: {

+  As a result of the fix, the exported RTS APIs `stopTimer` and `startTimer`

+  are now no-ops and are deprecated. They were called at least by the process

+  and unix libraries. No replacement is needed.

+

+  They were used by libraries to temporarily block the RTS's use of the timer

+  signal. These functions no longer have a purpose since the RTS interval

+  timer no longer uses signals.

+}

+#include "Timer.h"

+    blockTimer();

+    unblockTimer();

+    /* start the timer (after initTimer above) */

+    unblockTimer();

+    /* We rely on the guarantee that exitTimer stops the timer synchronously,

+     * which ensures the timer handler does not get run again after this point.

+     * We are about to start freeing resources used by the timer handler (like

+     * the capabilities, eventlog and profiling data structures).

+    exitTimer();

+            unpauseTimer();

+            pauseTimer();

+    blockTimer(); // See #4074

+        unblockTimer(); // #4074

+        // The timer thread is not present in the child process, so we need

+        // to initialise the timer again. Note that the timer is in a blocked

+        // state when we re-init, and this is permitted.

+        unblockTimer();

+    blockTimer();

+    unblockTimer();

+/* The ticker is initialised in a blocked state. Use unblockTicker to start. */

+void initTicker(Time interval, TickProc handle_tick);

+

+/* Stop and terminate the ticker. It does not need to be stopped first. */

+void exitTicker(void);

+

+/* Block and unblock the ticker handle_tick action.

+ *

+ * The blockTicker action is *synchronous*. When it returns the caller is

+ * guaranteed that the tick action is blocked. The unblockTicker may be

+ * asynchronous.

+ *

+ * These should be used for the purpose of *concurrency safety*: to prevent

+ * the tick action from running concurrently with some other critical section.

+ *

+ * The blockTicker action is moderately expensive (because it is synchronous)

+ * and the implementation is optimised on the assumption that this action is

+ * infrequent (e.g. compared to tick frequency).

+ *

+ * It is *not* safe to call these functions from within the tick handler itself.

+ *

+ * It is safe to use these functions concurrently from multiple threads. They

+ * are *not* idempotent however: each thread must pair up each blockTicker call

+ * with exactly one corresponding unblockTicker. Additionally, initTicker acts

+ * like blockTicker and also must be matched by a corresponding unblockTicker.

+ */

+void blockTicker(void);

+void unblockTicker(void);

+

+/* Pause and unpause (resume) the ticker.

+ *

+ * The pauseTicker and unpauseTicker actions are *asynchronous*. After calling

+ * pauseTicker, the ticker will pause eventually, but there may be another tick

+ * action before it does pause (and theoretically there could be several but

+ * in practice this is unlikely). Similarly, after calling unpauseTicker the

+ * ticker will start up again eventually, but there is an unspecified delay

+ * between the unpause and the next tick action (but in practice it is short).

+ *

+ * This should be used for the purpose of *efficiency*: to avoid unnecessary

+ * OS thread wakeups caused by the ticker.

+ *

+ * The pairing of unpauseTicker and the handle_tick action form a

+ * synchonises-with relation: values written before unpauseTicker can be

+ * read from the resulting handle_tick action.

+ *

+ * It *is* safe to call these functions from within the tick handler itself.

+ *

+ * It is safe to use these functions concurrently from multiple threads, but

+ * note that they *are* idempotent. This means it is not appropriate to use

+ * paired pause/unpause calls concurrently. They can be used by threads based

+ * on consistent use of some shared state or observation.

+ */

+void pauseTicker(void);

+void unpauseTicker(void);

+  handleProfTick(); // Bad or worse: see issue #27250.

+

+  if (RtsFlags.ConcFlags.ctxtSwitchTicks > 0)

+          flushEventLog(NULL);  // Bad or worse: see issue #27250.

+              // The scheduler will call pauseTimer() when it has done

+                  pauseTimer();

+              pauseTimer();

+void initTimer(void)

+/* Deprecated exported functions. Now no-ops.

+ * Historically they were used by the process and unix libraries to disable

+ * the signal-based interval timer, since otherwise the timer signal would

+ * keep going off in the child process and confusing everything. The interval

+ * timer no longer uses signals, so there is no need any more for libraries to

+ * disable the timer. Also, the timer internal API has changed.

+ */

+void stopTimer(void)  { /* no-op */ }

+void startTimer(void) { /* no-op */ }

+

+/* We allow multiple threads to block the timer temporarily with a

+ * blockTimer()/unblockTimer() pair. The counting for this is done by

+ * the ticker implementation when using blockTicker()/unblockTicker().

+ */

+void unblockTimer(void)

+    if (RtsFlags.MiscFlags.tickInterval != 0) {

+        unblockTicker();

+void blockTimer(void)

+    if (RtsFlags.MiscFlags.tickInterval != 0) {

+        blockTicker();

+void pauseTimer(void)

+{

+#if defined(HAVE_PREEMPTION)

+    if (RtsFlags.MiscFlags.tickInterval != 0) {

+        pauseTicker();

+    }

+#endif

+}

+

+void unpauseTimer(void)

+{

+#if defined(HAVE_PREEMPTION)

+    if (RtsFlags.MiscFlags.tickInterval != 0) {

+        unpauseTicker();

+    }

+#endif

+}

+

+void exitTimer (void)

+        exitTicker();

+#include "BeginPrivate.h"

+

+void initTimer(void);

+void exitTimer(void);

+

+void blockTimer(void);

+void unblockTimer(void);

+

+void pauseTimer(void);

+void unpauseTimer(void);

+

+#include "EndPrivate.h"

+void startTimer (void);    // Deprecated: see issue #27086

+void stopTimer (void);     // Deprecated: see issue #27086

+#define RELEASE_ADD_ALWAYS(ptr,val) __atomic_add_fetch(ptr, val, __ATOMIC_RELEASE)

+#define RELEASE_SUB_ALWAYS(ptr,val) __atomic_sub_fetch(ptr, val, __ATOMIC_RELEASE)

+static Time ticker_interval = DEFAULT_TICK_INTERVAL;

+

+// Atomic variable used by client threads to communicate their request to the

+// ticker thread to block the ticks.

+static int block_request_count;

+

+// Condition, mutex and cond var to communicate confirmation that the ticker is

+// indeed blocked.

+static bool block_confirmed; // must hold the mutex to get/set

+static Mutex block_confirmed_mutex;

+static Condition block_confirmed_cond;

+

+// Atomic variable used by client threads to communicate that they want the

+// ticker thread to pause. This communication is one-way, with no

+// acknowledgement.

+static bool pause_request;

+

+// Atomic variable used by other threads to communicate that they want the

+// ticker thread to exit.

+static bool exit_request;

+// Used to wait for the ticker thread to terminate after asking it to exit.

+static OSThreadId ticker_thread_id;

+

+// Fds used with sendFdWakeup to notify the ticker thread that any of the

+// *_request variables above have been set.

+static int notifyfd_r = -1, notifyfd_w = -1;

+

+

+// Synchronous, request and confirm. Not idempotent.

+// Request the ticker to stop ticking, and wait until it confirms

+// this. This guarantees no more ticks after this returns.

+void blockTicker(void)

+{

+    // Request

+    // atomic increment with release memory order

+    RELEASE_ADD_ALWAYS(&block_request_count, 1);

+

+    OS_ACQUIRE_LOCK(&block_confirmed_mutex);

+    if (!block_confirmed) {

+        // Avoid notifying if it's not necessary. This always happens during

+        // rts startup, since initTicker starts in the blocked state and then

+        // moreCapabilities() uses block/unblockTicker.

+        sendFdWakeup(notifyfd_w);

+    }

+    // Wait for confirmation

+    while (!block_confirmed) {

+        waitCondition(&block_confirmed_cond, &block_confirmed_mutex);

+    }

+    OS_RELEASE_LOCK(&block_confirmed_mutex);

+}

+// Asynchronous request. Not idempotent.

+void unblockTicker(void)

+{

+    // Request

+    RELEASE_SUB_ALWAYS(&block_request_count, 1);

+    sendFdWakeup(notifyfd_w);

+}

+// Asynchronous request. Idempotent.

+void pauseTicker(void)

+{

+    RELEASE_STORE_ALWAYS(&pause_request, true);

+    sendFdWakeup(notifyfd_w);

+}

+// Asynchronous request. Idempotent.

+void unpauseTicker(void)

+    RELEASE_STORE_ALWAYS(&pause_request, false);

+    sendFdWakeup(notifyfd_w);

+}

+// Synchronous. Not idempotent.

+// The ticker is guaranteed stopped after this.

+void exitTicker(void)

+{

+    ASSERT(!RELAXED_LOAD_ALWAYS(&exit_request));

+    RELEASE_STORE_ALWAYS(&exit_request, true);

+    sendFdWakeup(notifyfd_w);

+    // wait for ticker thread to terminate

+    if (pthread_join(ticker_thread_id, NULL)) {

+        sysErrorBelch("Ticker: Failed to join: %s", strerror(errno));

+    }

+    closeFdWakeup(notifyfd_r, notifyfd_w);

+    closeMutex(&block_confirmed_mutex);

+    closeCondition(&block_confirmed_cond);

+}

+#if defined(HAVE_DECL_PPOLL) && HAVE_DECL_PPOLL == 1

+typedef struct timespec timeout;  // for ppoll()

+typedef struct { struct pollfd pollfds[1]; } fdset;

+typedef struct timeval timeout;   // for select()

+typedef struct { int fd; fd_set selectfds; } fdset; // need to stash fd

+// local helpers, to hide the difference between ppoll() and select()

+static void poll_init_timeout(timeout *tv, Time t);

+static void poll_init_fdset(fdset *fds, int fd); // single fd only

+// These two return: >0 if fd ready, ==0 if timeout, <0 if error

+static int poll_no_timeout(fdset *fdset);

+static int poll_with_timeout(fdset *fdset, timeout *t);

+static void *ticker_thread_func(void *_handle_tick)

+{

+    TickProc handle_tick = _handle_tick;

+

+    // Thread-local view of our state. We compare these with the corresponding

+    // atomic shared variables used to request state changes.

+    bool blocked = true; // compare to atomic shared var block_request_count

+    bool paused  = false; // updated from atomic shared var pause_request

+    bool exit    = false; // updated from atomic shared var exit_request

+

+    timeout timeout;

+    fdset fdset;

+    poll_init_timeout(&timeout, ticker_interval);

+    poll_init_fdset(&fdset, notifyfd_r);

+

+    while (!exit) {

+

+        int notify;

+        if (blocked || paused) {

+            notify = poll_no_timeout(&fdset);

+            notify = poll_with_timeout(&fdset, &timeout);

+        if (RTS_LIKELY(notify == 0)) {

+            // The time expired, no state change notification.

+

+        } else if (notify > 0) {

+            // State change notification, check the request variables.

+

+            // We rely on sendFdWakeup and select/poll to provide the

+            // happens-before relation. So if the request variables are set

+            // before calling sendFdWakeup, then we should be able to reliably

+            // read them here afterwards.

+            collectFdWakeup(notifyfd_r);

+

+            paused = ACQUIRE_LOAD_ALWAYS(&pause_request);

+            exit   = RELAXED_LOAD_ALWAYS(&exit_request);

+            int block_request_count_snapshot =

+                     ACQUIRE_LOAD_ALWAYS(&block_request_count);

+

+            if (block_request_count_snapshot > 0 && !blocked) {

+                // State change: !blocked -> blocked

+                blocked = true; // local state

+

+                // confirm to requesting thread(s)

+                OS_ACQUIRE_LOCK(&block_confirmed_mutex);

+                block_confirmed = true;

+                // Must use broadcastCondition not signalCondition since there

+                // could be concurrent requesting threads.

+                broadcastCondition(&block_confirmed_cond);

+                OS_RELEASE_LOCK(&block_confirmed_mutex);

+

+            } else if (block_request_count_snapshot == 0 && blocked) {

+                // State change: blocked -> !blocked

+                blocked = false; // local state

+

+                OS_ACQUIRE_LOCK(&block_confirmed_mutex);

+                block_confirmed = false;

+                OS_RELEASE_LOCK(&block_confirmed_mutex);

+            }

+

+        } else if (errno != EINTR) {

+            // While the RTS attempts to mask signals, some foreign libraries

+            // that rely on signal delivery may unmask them. Consequently we

+            // may see EINTR. See #24610.

+            sysErrorBelch("Ticker: poll failed: %s", strerror(errno));

+/* Initialise the ticker on startup or re-initialise the ticker after a fork().

+ * In the fork case, the thread will not be present, but fds are inherited.

+ *

+ * The ticker is started in the blocked state. A single unblockTicker should

+ * be used to unblock.

+ */

+    ticker_interval     = interval;

+    block_request_count = 1;

+    pause_request       = false;

+    exit_request        = false;

+

+    block_confirmed = true;

+    initMutex(&block_confirmed_mutex);

+    initCondition(&block_confirmed_cond);

+     * We used to do it in ticker_thread_func (i.e. in the timer thread) but it

+    if (notifyfd_r != -1) {

+        closeFdWakeup(notifyfd_r, notifyfd_w);

+    newFdWakeup(&notifyfd_r, &notifyfd_w);

+    ret = createAttachedOSThread(&ticker_thread_id, "ghc_ticker", ticker_thread_func, (void*)handle_tick);

+/* Implementation of the local helpers, to hide the difference between ppoll()

+ * and select().

+ */

+#if defined(HAVE_DECL_PPOLL) && HAVE_DECL_PPOLL == 1

+static void poll_init_timeout(timeout *tv, Time t)

+    tv->tv_sec  = TimeToSeconds(t);

+    tv->tv_nsec = TimeToNS(t) % 1000000000;

+static void poll_init_fdset(fdset *fds, int fd)

+    fds->pollfds[0].fd = fd;

+    fds->pollfds[0].events = POLLIN;

+static int poll_no_timeout(fdset *fds)

+    int nfds = 1;

+    return ppoll(fds->pollfds, nfds, NULL, NULL);

+}

+

+static int poll_with_timeout(fdset *fds, timeout *ts)

+{

+    int nfds = 1;

+    return ppoll(fds->pollfds, nfds, ts, NULL);

+}

+

+#else // select()

+

+static void poll_init_timeout(timeout *tv, Time t)

+{

+    tv->tv_sec  = TimeToSeconds(t);

+   /* convert remainder time in nanoseconds to microseconds, rounding up: */

+    tv->tv_usec = ((TimeToNS(t) % 1000000000) + 999) / 1000;

+}

+

+static void poll_init_fdset(fdset *fds, int fd)

+{

+    FD_ZERO(&fds->selectfds);

+    FD_SET(fd, &fds->selectfds);

+    fds->fd = fd;

+}

+

+static int poll_no_timeout(fdset *fds)

+{

+    int nfds = fds->fd+1;

+    return select(nfds, &fds->selectfds, NULL, NULL, NULL);

+static int poll_with_timeout(fdset *fds, timeout *tv)

+{

+    struct timeval tv_tmp = *tv; // copy since select may change this value.

+    int nfds = fds->fd+1;

+    return select(nfds, &fds->selectfds, NULL, NULL, &tv_tmp);

+}

+#endif

+

+/* This is obsolete, but is used in the unix package for now */

+static Time tick_interval = 0;

+

+static Mutex mutex; // To protect the timer and state vars below

+static int blocked_count;

+static Bool paused;

+    ASSERT(timer_queue == NULL);

+    OS_INIT_LOCK(mutex);

+    blocked_count = 1; // starts blocked

+    paused = false;

+static void startTicker(void) {

+    ASSERT(timer_queue != NULL && timer == NULL);

+    DWORD interval = TimeToMS(tick_interval); // ms

+    BOOL r = CreateTimerQueueTimer(&timer,

+                                   timer_queue,

+                                   tick_callback,

+                                   NULL,     // callback param

+                                   interval, // inital interval

+                                   interval, // recurrant interval

+                                   WT_EXECUTEINTIMERTHREAD);

+    //TODO: using WT_EXECUTEINTIMERTHREAD is fine for context switching, and

+    // plausibly also ok for profile sampling but is way out for eventlog

+    // flushing. The eventlog flush does a global synchronisation of all

+    // capabilities and I/O! And with eventlog providers, it calls arbitrary

+    // user code. This is not ok! See issue #27250.