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_INTERFACES_IPC_H
6 #define BITCOIN_INTERFACES_IPC_H
7 8 #include <functional>
9 #include <memory>
10 #include <string>
11 #include <typeindex>
12 13 namespace ipc {
14 struct Context;
15 } // namespace ipc
16 17 namespace interfaces {
18 class Init;
19 20 //! Interface providing access to interprocess-communication (IPC)
21 //! functionality. The IPC implementation is responsible for establishing
22 //! connections between a controlling process and a process being controlled.
23 //! When a connection is established, the process being controlled returns an
24 //! interfaces::Init pointer to the controlling process, which the controlling
25 //! process can use to get access to other interfaces and functionality.
26 //!
27 //! When spawning a new process, the steps are:
28 //!
29 //! 1. The controlling process calls interfaces::Ipc::spawnProcess(), which
30 //! calls ipc::Process::spawn(), which spawns a new process and returns a
31 //! socketpair file descriptor for communicating with it.
32 //! interfaces::Ipc::spawnProcess() then calls ipc::Protocol::connect()
33 //! passing the socketpair descriptor, which returns a local proxy
34 //! interfaces::Init implementation calling remote interfaces::Init methods.
35 //! 2. The spawned process calls interfaces::Ipc::startSpawnProcess(), which
36 //! calls ipc::Process::checkSpawned() to read command line arguments and
37 //! determine whether it is a spawned process and what socketpair file
38 //! descriptor it should use. It then calls ipc::Protocol::serve() to handle
39 //! incoming requests from the socketpair and invoke interfaces::Init
40 //! interface methods, and exit when the socket is closed.
41 //! 3. The controlling process calls local proxy interfaces::Init object methods
42 //! to make other proxy objects calling other remote interfaces. It can also
43 //! destroy the initial interfaces::Init object to close the connection and
44 //! shut down the spawned process.
45 //!
46 //! When connecting to an existing process, the steps are similar to spawning a
47 //! new process, except a socket is created instead of a socketpair, and
48 //! destroying an Init interface doesn't end the process, since there can be
49 //! multiple connections.
50 class Ipc
51 {
52 public:
53 virtual ~Ipc() = default;
54 55 //! Spawn a child process returning pointer to its Init interface.
56 virtual std::unique_ptr<Init> spawnProcess(const char* exe_name) = 0;
57 58 //! If this is a spawned process, block and handle requests from the parent
59 //! process by forwarding them to this process's Init interface, then return
60 //! true. If this is not a spawned child process, return false.
61 virtual bool startSpawnedProcess(int argc, char* argv[], int& exit_status) = 0;
62 63 //! Connect to a socket address and return a pointer to its Init interface.
64 //! Returns a non-null pointer if the connection was established, returns
65 //! null if address is empty ("") or disabled ("0") or if a connection was
66 //! refused but not required ("auto"), and throws an exception if there was
67 //! an unexpected error.
68 virtual std::unique_ptr<Init> connectAddress(std::string& address) = 0;
69 70 //! Listen on a socket address exposing this process's init interface to
71 //! clients. Throws an exception if there was an error.
72 virtual void listenAddress(std::string& address) = 0;
73 74 //! Disconnect any incoming connections that are still connected.
75 virtual void disconnectIncoming() = 0;
76 77 //! Add cleanup callback to remote interface that will run when the
78 //! interface is deleted.
79 template<typename Interface>
80 void addCleanup(Interface& iface, std::function<void()> cleanup)
81 {
82 addCleanup(typeid(Interface), &iface, std::move(cleanup));
83 }
84 85 //! IPC context struct accessor (see struct definition for more description).
86 virtual ipc::Context& context() = 0;
87 88 protected:
89 //! Internal implementation of public addCleanup method (above) as a
90 //! type-erased virtual function, since template functions can't be virtual.
91 virtual void addCleanup(std::type_index type, void* iface, std::function<void()> cleanup) = 0;
92 };
93 94 //! Return implementation of Ipc interface.
95 std::unique_ptr<Ipc> MakeIpc(const char* exe_name, const char* process_argv0, Init& init);
96 } // namespace interfaces
97 98 #endif // BITCOIN_INTERFACES_IPC_H
99