util: Add SignalInterrupt class and use in shutdown.cpp

This change helps generalize shutdown code so an interrupt can be
provided to libbitcoinkernel callers. This may also be useful to
eventually de-globalize all of the shutdown code.

Co-authored-by: Russell Yanofsky <russ@yanofsky.org>
Co-authored-by: TheCharlatan <seb.kung@gmail.com>

3 files changed, 137 insertions, 5 deletions

diff --git a/src/util/signalinterrupt.cpp b/src/util/signalinterrupt.cpp
new file mode 100644
index 0000000000..c551ba8044
--- /dev/null
+++ b/src/util/signalinterrupt.cpp
@@ -0,0 +1,74 @@
+// Copyright (c) 2022 The Bitcoin Core developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+#include <util/signalinterrupt.h>
+
+#ifdef WIN32
+#include <mutex>
+#else
+#include <util/tokenpipe.h>
+#endif
+
+#include <ios>
+#include <optional>
+
+namespace util {
+
+SignalInterrupt::SignalInterrupt() : m_flag{false}
+{
+#ifndef WIN32
+    std::optional<TokenPipe> pipe = TokenPipe::Make();
+    if (!pipe) throw std::ios_base::failure("Could not create TokenPipe");
+    m_pipe_r = pipe->TakeReadEnd();
+    m_pipe_w = pipe->TakeWriteEnd();
+#endif
+}
+
+SignalInterrupt::operator bool() const
+{
+    return m_flag;
+}
+
+void SignalInterrupt::reset()
+{
+    // Cancel existing interrupt by waiting for it, this will reset condition flags and remove
+    // the token from the pipe.
+    if (*this) wait();
+    m_flag = false;
+}
+
+void SignalInterrupt::operator()()
+{
+#ifdef WIN32
+    std::unique_lock<std::mutex> lk(m_mutex);
+    m_flag = true;
+    m_cv.notify_one();
+#else
+    // This must be reentrant and safe for calling in a signal handler, so using a condition variable is not safe.
+    // Make sure that the token is only written once even if multiple threads call this concurrently or in
+    // case of a reentrant signal.
+    if (!m_flag.exchange(true)) {
+        // Write an arbitrary byte to the write end of the pipe.
+        int res = m_pipe_w.TokenWrite('x');
+        if (res != 0) {
+            throw std::ios_base::failure("Could not write interrupt token");
+        }
+    }
+#endif
+}
+
+void SignalInterrupt::wait()
+{
+#ifdef WIN32
+    std::unique_lock<std::mutex> lk(m_mutex);
+    m_cv.wait(lk, [this] { return m_flag.load(); });
+#else
+    int res = m_pipe_r.TokenRead();
+    if (res != 'x') {
+        throw std::ios_base::failure("Did not read expected interrupt token");
+    }
+#endif
+}
+
+} // namespace util
diff --git a/src/util/signalinterrupt.h b/src/util/signalinterrupt.h
new file mode 100644
index 0000000000..ca02feda91
--- /dev/null
+++ b/src/util/signalinterrupt.h
@@ -0,0 +1,52 @@
+// Copyright (c) 2023 The Bitcoin Core developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+#ifndef BITCOIN_UTIL_SIGNALINTERRUPT_H
+#define BITCOIN_UTIL_SIGNALINTERRUPT_H
+
+#ifdef WIN32
+#include <condition_variable>
+#include <mutex>
+#else
+#include <util/tokenpipe.h>
+#endif
+
+#include <atomic>
+#include <cstdlib>
+
+namespace util {
+/**
+ * Helper class that manages an interrupt flag, and allows a thread or
+ * signal to interrupt another thread.
+ *
+ * This class is safe to be used in a signal handler. If sending an interrupt
+ * from a signal handler is not necessary, the more lightweight \ref
+ * CThreadInterrupt class can be used instead.
+ */
+
+class SignalInterrupt
+{
+public:
+    SignalInterrupt();
+    explicit operator bool() const;
+    void operator()();
+    void reset();
+    void wait();
+
+private:
+    std::atomic<bool> m_flag;
+
+#ifndef WIN32
+    // On UNIX-like operating systems use the self-pipe trick.
+    TokenPipeEnd m_pipe_r;
+    TokenPipeEnd m_pipe_w;
+#else
+    // On windows use a condition variable, since we don't have any signals there
+    std::mutex m_mutex;
+    std::condition_variable m_cv;
+#endif
+};
+} // namespace util
+
+#endif // BITCOIN_UTIL_SIGNALINTERRUPT_H
diff --git a/src/util/threadinterrupt.h b/src/util/threadinterrupt.h
index ccc053f576..0b79b38276 100644
--- a/src/util/threadinterrupt.h
+++ b/src/util/threadinterrupt.h
@@ -12,11 +12,17 @@
 #include <chrono>
 #include <condition_variable>
 
-/*
-    A helper class for interruptible sleeps. Calling operator() will interrupt
-    any current sleep, and after that point operator bool() will return true
-    until reset.
-*/
+/**
+ * A helper class for interruptible sleeps. Calling operator() will interrupt
+ * any current sleep, and after that point operator bool() will return true
+ * until reset.
+ *
+ * This class should not be used in a signal handler. It uses thread
+ * synchronization primitives that are not safe to use with signals. If sending
+ * an interrupt from a signal handler is necessary, the \ref SignalInterrupt
+ * class can be used instead.
+ */
+
 class CThreadInterrupt
 {
 public: