RStudio Launcher Plugin SDK  1.1.3
A software development kit for creating plugins that work the the RStudio Launcher.
Process.hpp
1 /*
2  * Process.hpp
3  *
4  * Copyright (C) 2020 by RStudio, PBC
5  *
6  * Unless you have received this program directly from RStudio pursuant to the terms of a commercial license agreement
7  * with RStudio, then this program is licensed to you under the following terms:
8  *
9  * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
10  * documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
11  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
12  * permit persons to whom the Software is furnished to do so, subject to the following conditions:
13  *
14  * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
15  * Software.
16  *
17  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
18  * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
19  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
20  * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21  *
22  */
23 
24 
25 #ifndef LAUNCHER_PLUGINS_PROCESS_HPP
26 #define LAUNCHER_PLUGINS_PROCESS_HPP
27 
28 #include <Noncopyable.hpp>
29 
30 #include <functional>
31 #include <string>
32 #include <vector>
33 
34 #include <api/Job.hpp>
35 #include <system/FilePath.hpp>
36 #include <system/DateTime.hpp>
37 #include <system/User.hpp>
38 
39 namespace rstudio {
40 namespace launcher_plugins {
41 
42 class Error;
43 
44 } // namespace launcher_plugins
45 } // namespace rstudio
46 
47 namespace rstudio {
48 namespace launcher_plugins {
49 namespace system {
50 namespace process {
51 
52 typedef std::function<void(const Error&)> OnErrorCallback;
53 typedef std::function<void(int)> OnExitCallback;
54 typedef std::function<void(const std::string&)> OnOutputCallback;
55 
60 {
64  ProcessInfo();
65 
74  static Error getProcessInfo(pid_t in_pid, ProcessInfo& out_info);
75 
77  std::vector<std::string> Arguments;
78 
80  std::string Executable;
81 
84 
86  pid_t PGrp;
87 
89  pid_t Pid;
90 
92  pid_t PPid;
93 
95  std::string State;
96 };
97 
102 {
107 
109  int ExitCode;
110 
112  std::string StdError;
113 
115  std::string StdOut;
116 };
117 
122 {
126  OnErrorCallback OnError;
127 
131  OnExitCallback OnExit;
132 
134  OnOutputCallback OnStandardError;
135 
137  OnOutputCallback OnStandardOutput;
138 };
139 
144 {
149  CloseStdIn(true),
150  IsShellCommand(false),
151  UseSandbox(true)
152  {};
153 
158  std::vector<std::string> Arguments;
159 
167 
172  api::EnvironmentList Environment;
173 
178  std::string Executable;
179 
184 
191  api::MountList Mounts;
192 
198  std::string PamProfile;
199 
205  std::string Password;
206 
213 
217  std::string StandardInput;
218 
223 
228 
241 
246 };
247 
252 {
253 public:
257  virtual ~AbstractChildProcess() = default;
258 
264  pid_t getPid() const;
265 
271  virtual Error terminate();
272 
281  virtual Error writeToStdin(const std::string& in_string, bool in_eof) = 0;
282 
283 protected:
289  explicit AbstractChildProcess(const ProcessOptions& in_options);
290 
296  Error run();
297 
298  // The private implementation of AbstractChildProcess.
299  PRIVATE_IMPL(m_baseImpl);
300 };
301 
306 {
307 public:
313  explicit SyncChildProcess(const ProcessOptions& in_options);
314 
322  Error run(ProcessResult& out_result);
323 
332  Error writeToStdin(const std::string& in_string, bool in_eof) override;
333 };
334 
338 class ProcessSupervisor final : public Noncopyable
339 {
340 public:
341 
347  static bool hasRunningChildren();
348 
358  static Error runAsyncProcess(
359  const ProcessOptions& in_options,
360  const AsyncProcessCallbacks& in_callbacks,
361  std::shared_ptr<AbstractChildProcess>* out_childProcess = nullptr);
362 
366  static void terminateAll();
367 
376  static bool waitForExit(const TimeDuration& in_maxWaitTime = TimeDuration::Infinity());
377 
378 private:
384  static ProcessSupervisor& getInstance();
385 
390 
391  // The private implementation of ProcessSupervisor.
392  PRIVATE_IMPL_SHARED(m_impl);
393 };
394 
404 Error getChildProcesses(pid_t in_parentPid, std::vector<ProcessInfo>& out_processes);
405 
416 Error signalProcess(pid_t in_pid, int in_signal, bool in_processGroupOnly = true);
417 
425 std::string shellEscape(const std::string& in_toEscape);
426 
434 std::string shellEscape(const FilePath& in_filePath);
435 
436 } // namespace process
437 } // namespace system
438 } // namespace launcher_plugins
439 } // namespace rstudio
440 
441 #endif
rstudio::launcher_plugins::system::process::ProcessOptions::StandardErrorFile
FilePath StandardErrorFile
The file to which to write standard error. If not set, standard error will not be redirected.
Definition: Process.hpp:227
rstudio::launcher_plugins::system::TimeDuration::Infinity
static TimeDuration Infinity()
Constructs a TimeDuration which represents "any amount of time". Use with caution.
rstudio::launcher_plugins::system::process::AsyncProcessCallbacks::OnExit
OnExitCallback OnExit
Callback invoked when the asynchronous child process exits.
Definition: Process.hpp:131
rstudio::launcher_plugins::system::process::ProcessOptions::Executable
std::string Executable
The executable or shell command to run. This value should either be an absolute path,...
Definition: Process.hpp:178
rstudio::launcher_plugins::system::FilePath
Class which represents a path on the system. May be any type of file (e.g. directory,...
Definition: FilePath.hpp:77
rstudio::launcher_plugins::system::process::ProcessOptions::UseSandbox
bool UseSandbox
Whether to use the rsandbox executable to launch the child in sandbox environment or launch the child...
Definition: Process.hpp:240
rstudio::launcher_plugins::system::process::ProcessSupervisor::runAsyncProcess
static Error runAsyncProcess(const ProcessOptions &in_options, const AsyncProcessCallbacks &in_callbacks, std::shared_ptr< AbstractChildProcess > *out_childProcess=nullptr)
Runs a child process asynchronously.
rstudio::launcher_plugins::system::process::AbstractChildProcess::writeToStdin
virtual Error writeToStdin(const std::string &in_string, bool in_eof)=0
Writes the specified string to stdin.
rstudio::launcher_plugins::system::process::ProcessOptions::RunAsUser
User RunAsUser
The user who the job should be run as.
Definition: Process.hpp:212
rstudio::launcher_plugins::system::process::ProcessOptions::StandardOutputFile
FilePath StandardOutputFile
The file to which to write standard output. If not set, standard output will not be redirected.
Definition: Process.hpp:222
rstudio::launcher_plugins::system::User
Class which represents a system user.
Definition: User.hpp:55
rstudio::launcher_plugins::system::process::ProcessResult::StdOut
std::string StdOut
Definition: Process.hpp:115
rstudio::launcher_plugins::system::process::ProcessInfo::PGrp
pid_t PGrp
Definition: Process.hpp:86
rstudio::launcher_plugins::system::process::AsyncProcessCallbacks
Callbacks that will be invoked when certain events happen in the asynchronous child process.
Definition: Process.hpp:121
rstudio::launcher_plugins::system::process::ProcessSupervisor::hasRunningChildren
static bool hasRunningChildren()
Checks whether the supervisor is tracking any processes which have not exited yet.
rstudio::launcher_plugins::system::process::ProcessOptions::IsShellCommand
bool IsShellCommand
True if the executable is a shell command; False otherwise. Default: false.
Definition: Process.hpp:183
rstudio::launcher_plugins::system::process::ProcessInfo::Arguments
std::vector< std::string > Arguments
Definition: Process.hpp:77
rstudio::launcher_plugins::system::process::ProcessResult::StdError
std::string StdError
Definition: Process.hpp:112
rstudio::launcher_plugins::system::process::ProcessOptions::PamProfile
std::string PamProfile
The PAM profile to load, if any.
Definition: Process.hpp:198
rstudio::launcher_plugins::system::process::ProcessInfo::Owner
User Owner
Definition: Process.hpp:83
rstudio::launcher_plugins::system::process::ProcessInfo
Represents the details of a process that is running on this machine.
Definition: Process.hpp:59
rstudio::launcher_plugins::system::process::ProcessInfo::Executable
std::string Executable
Definition: Process.hpp:80
rstudio::launcher_plugins::system::process::ProcessOptions
Defines a process that can be run.
Definition: Process.hpp:143
rstudio::launcher_plugins::system::process::ProcessInfo::Pid
pid_t Pid
Definition: Process.hpp:89
rstudio::launcher_plugins::system::process::ProcessSupervisor
Creates and manages non-blocking child processes.
Definition: Process.hpp:338
rstudio::launcher_plugins::system::process::ProcessInfo::getProcessInfo
static Error getProcessInfo(pid_t in_pid, ProcessInfo &out_info)
Gets the process information for the process with the specified PID.
rstudio::launcher_plugins::system::process::ProcessOptions::Environment
api::EnvironmentList Environment
The environment variables which should available to the process. If PATH is not set,...
Definition: Process.hpp:172
rstudio::launcher_plugins::system::process::ProcessSupervisor::terminateAll
static void terminateAll()
Terminates all running children forcefully.
rstudio::launcher_plugins::system::process::ProcessOptions::Arguments
std::vector< std::string > Arguments
The arguments of the process. Each argument will be escaped using single quotations so that the value...
Definition: Process.hpp:152
rstudio::launcher_plugins::system::process::AbstractChildProcess
Base class for a child process, which will be launched via rsandbox.
Definition: Process.hpp:251
rstudio::launcher_plugins::system::process::ProcessInfo::PPid
pid_t PPid
Definition: Process.hpp:92
rstudio::launcher_plugins::system::process::AbstractChildProcess::AbstractChildProcess
AbstractChildProcess(const ProcessOptions &in_options)
Constructor.
rstudio::launcher_plugins::system::process::SyncChildProcess
A blocking child process.
Definition: Process.hpp:305
rstudio::launcher_plugins::Error
Class which represents an error.
Definition: Error.hpp:174
rstudio::launcher_plugins::system::process::ProcessResult::ProcessResult
ProcessResult()
Constructor.
Definition: Process.hpp:106
rstudio::launcher_plugins::system::process::AbstractChildProcess::run
Error run()
Forks and executes the child process, passing along arguments and environment variables.
rstudio::launcher_plugins::system::TimeDuration
Represents an duration of time (e.g. 5 hours, 43 minutes, and 21 seconds) as opposed to a point in ti...
Definition: DateTime.hpp:48
rstudio::launcher_plugins::system::process::ProcessInfo::State
std::string State
Definition: Process.hpp:95
rstudio::launcher_plugins::system::process::ProcessInfo::ProcessInfo
ProcessInfo()
Constructor.
rstudio::launcher_plugins::system::process::ProcessResult::ExitCode
int ExitCode
Definition: Process.hpp:106
rstudio::launcher_plugins::system::process::ProcessOptions::ProcessOptions
ProcessOptions()
Constructor.
Definition: Process.hpp:148
rstudio::launcher_plugins::Noncopyable
Class which can be inherited from to disallow copying of its child classes.
Definition: Noncopyable.hpp:34
rstudio::launcher_plugins::system::process::SyncChildProcess::SyncChildProcess
SyncChildProcess(const ProcessOptions &in_options)
Constructor.
rstudio::launcher_plugins::system::process::AsyncProcessCallbacks::OnError
OnErrorCallback OnError
Callback invoked if the asynchronous child process encounters an error.
Definition: Process.hpp:126
rstudio::launcher_plugins::system::process::ProcessOptions::Password
std::string Password
The password of the user running the job, if any.
Definition: Process.hpp:205
rstudio::launcher_plugins::system::process::AbstractChildProcess::getPid
pid_t getPid() const
Gets the PID of this child process.
rstudio::launcher_plugins::system::process::AsyncProcessCallbacks::OnStandardOutput
OnOutputCallback OnStandardOutput
Callback invoked when the asynchronous child process writes to standard out.
Definition: Process.hpp:137
rstudio::launcher_plugins::system::process::ProcessOptions::Mounts
api::MountList Mounts
The set of mounts to be applied for the child process. Only mounts with a HostMountSource type will b...
Definition: Process.hpp:191
rstudio::launcher_plugins::system::process::AbstractChildProcess::~AbstractChildProcess
virtual ~AbstractChildProcess()=default
Virtual destructor for inheritance.
rstudio::launcher_plugins::system::process::SyncChildProcess::writeToStdin
Error writeToStdin(const std::string &in_string, bool in_eof) override
Writes the specified string to stdin.
rstudio::launcher_plugins::system::process::ProcessSupervisor::waitForExit
static bool waitForExit(const TimeDuration &in_maxWaitTime=TimeDuration::Infinity())
Waits for all child processes to exit.
rstudio::launcher_plugins::system::process::AsyncProcessCallbacks::OnStandardError
OnOutputCallback OnStandardError
Callback invoked when the asynchronous child process writes to standard error.
Definition: Process.hpp:134
rstudio::launcher_plugins::system::process::ProcessResult
Represents the result of a synchronous child process.
Definition: Process.hpp:101
rstudio::launcher_plugins::system::process::AbstractChildProcess::terminate
virtual Error terminate()
Terminates the child process.
rstudio::launcher_plugins::system::process::ProcessOptions::WorkingDirectory
FilePath WorkingDirectory
The directory from which to run the process. Must exist and be accessible by the RunAsUser.
Definition: Process.hpp:245
rstudio::launcher_plugins::system::process::ProcessOptions::StandardInput
std::string StandardInput
The standard input that should be sent to the process.
Definition: Process.hpp:217
rstudio::launcher_plugins::system::process::ProcessOptions::CloseStdIn
bool CloseStdIn
Whether to close write end of the standard input stream after the specified StandardInput is written....
Definition: Process.hpp:166