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