1 // Copyright (c) 2021-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_IPC_PROTOCOL_H
6 #define BITCOIN_IPC_PROTOCOL_H
7 8 #include <interfaces/init.h>
9 10 #include <functional>
11 #include <memory>
12 #include <typeindex>
13 14 namespace ipc {
15 struct Context;
16 17 //! IPC protocol interface for calling IPC methods over sockets.
18 //!
19 //! There may be different implementations of this interface for different IPC
20 //! protocols (e.g. Cap'n Proto, gRPC, JSON-RPC, or custom protocols).
21 class Protocol
22 {
23 public:
24 virtual ~Protocol() = default;
25 26 //! Return Init interface that forwards requests over given socket descriptor.
27 //! Socket communication is handled on a background thread.
28 //!
29 //! @note It could be potentially useful in the future to add
30 //! std::function<void()> on_disconnect callback argument here. But there
31 //! isn't an immediate need, because the protocol implementation can clean
32 //! up its own state (calling ProxyServer destructors, etc) on disconnect,
33 //! and any client calls will just throw ipc::Exception errors after a
34 //! disconnect.
35 virtual std::unique_ptr<interfaces::Init> connect(int fd, const char* exe_name) = 0;
36 37 //! Listen for connections on provided socket descriptor, accept them, and
38 //! handle requests on accepted connections. This method doesn't block, and
39 //! performs I/O on a background thread.
40 virtual void listen(int listen_fd, const char* exe_name, interfaces::Init& init) = 0;
41 42 //! Handle requests on provided socket descriptor, forwarding them to the
43 //! provided Init interface. Socket communication is handled on the
44 //! current thread, and this call blocks until the socket is closed.
45 //!
46 //! @note: If this method is called, it needs be called before connect() or
47 //! listen() methods, because for ease of implementation it's inflexible and
48 //! always runs the event loop in the foreground thread. It can share its
49 //! event loop with the other methods but can't share an event loop that was
50 //! created by them. This isn't really a problem because serve() is only
51 //! called by spawned child processes that call it immediately to
52 //! communicate back with parent processes.
53 //
54 //! The optional `ready_fn` callback will be called after the event loop is
55 //! created but before it is started. This can be useful in tests to trigger
56 //! client connections from another thread as soon as the event loop is
57 //! available, but should not be necessary in normal code which starts
58 //! clients and servers independently.
59 virtual void serve(int fd, const char* exe_name, interfaces::Init& init, const std::function<void()>& ready_fn = {}) = 0;
60 61 //! Disconnect any incoming connections that are still connected.
62 virtual void disconnectIncoming() = 0;
63 64 //! Add cleanup callback to interface that will run when the interface is
65 //! deleted.
66 virtual void addCleanup(std::type_index type, void* iface, std::function<void()> cleanup) = 0;
67 68 //! Context accessor.
69 virtual Context& context() = 0;
70 };
71 } // namespace ipc
72 73 #endif // BITCOIN_IPC_PROTOCOL_H
74