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