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