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 <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         [ +  - ]:        1102 : class Ipc
      51                 :             : {
      52                 :             : public:
      53                 :           0 :     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                 :           0 :     void addCleanup(Interface& iface, std::function<void()> cleanup)
      81                 :             :     {
      82         [ #  # ]:           0 :         addCleanup(typeid(Interface), &iface, std::move(cleanup));
      83                 :           0 :     }
      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