1// Copyright (c) 2023-present The Bitcoin Core developers
2// Distributed under the MIT software license, see the accompanying
3// file COPYING or http://www.opensource.org/licenses/mit-license.php.
4
5#ifndef BITCOIN_KERNEL_NOTIFICATIONS_INTERFACE_H
6#define BITCOIN_KERNEL_NOTIFICATIONS_INTERFACE_H
7
8#include <cstdint>
9#include <variant>
10
11class CBlockIndex;
12enum class SynchronizationState;
13struct bilingual_str;
14
15namespace kernel {
16
17//! Result type for use with std::variant to indicate that an operation should be interrupted.
18struct Interrupted{};
19enum class Warning;
20
21
22//! Simple result type for functions that need to propagate an interrupt status and don't have other return values.
23using InterruptResult = std::variant<std::monostate, Interrupted>;
24
25template <typename T>
26bool IsInterrupted(const T& result)
27{
28    return std::holds_alternative<kernel::Interrupted>(result);
29}
30
31/**
32 * A base class defining functions for notifying about certain kernel
33 * events.
34 */
35class Notifications
36{
37public:
38    virtual ~Notifications() = default;
39
40    [[nodiscard]] virtual InterruptResult blockTip(SynchronizationState state, const CBlockIndex& index, double verification_progress) { return {}; }
41    virtual void headerTip(SynchronizationState state, int64_t height, int64_t timestamp, bool presync) {}
42    virtual void progress(const bilingual_str& title, int progress_percent, bool resume_possible) {}
43    virtual void warningSet(Warning id, const bilingual_str& message) {}
44    virtual void warningUnset(Warning id) {}
45
46    //! The flush error notification is sent to notify the user that an error
47    //! occurred while flushing block data to disk. Kernel code may ignore flush
48    //! errors that don't affect the immediate operation it is trying to
49    //! perform. Applications can choose to handle the flush error notification
50    //! by logging the error, or notifying the user, or triggering an early
51    //! shutdown as a precaution against causing more errors.
52    virtual void flushError(const bilingual_str& message) {}
53
54    //! The fatal error notification is sent to notify the user when an error
55    //! occurs in kernel code that can't be recovered from. After this
56    //! notification is sent, whatever function triggered the error should also
57    //! return an error code or raise an exception. Applications can choose to
58    //! handle the fatal error notification by logging the error, or notifying
59    //! the user, or triggering an early shutdown as a precaution against
60    //! causing more errors.
61    virtual void fatalError(const bilingual_str& message) {}
62};
63} // namespace kernel
64
65#endif // BITCOIN_KERNEL_NOTIFICATIONS_INTERFACE_H
66