StormByte-System 3.0.0
C++26 process and environment module of the StormByte suite
Loading...
Searching...
No Matches
process.hxx
Go to the documentation of this file.
1/*
2 * Copyright (C) 2024-2026 David C. Manuelda (StormBytePP)
3 *
4 * This file is part of StormByte-System.
5 *
6 * StormByte-System original source is dual-licensed:
7 *
8 * 1. GNU Lesser General Public License v3.0 (or later)
9 * You may redistribute and/or modify this file under the terms of the
10 * GNU Lesser General Public License as published by the Free Software
11 * Foundation, either version 3 of the License, or (at your option)
12 * any later version.
13 *
14 * 2. Commercial license
15 * Alternatively, this file may be used under the terms of a commercial
16 * license agreement with the copyright holder
17 * (David C. Manuelda <StormByte@gmail.com>).
18 *
19 * Both licenses apply only to original StormByte-System source in this
20 * repository. They do not cover other StormByte modules or any third-party
21 * material shipped with this repository (including everything under
22 * thirdparty/, and in particular the bundled StormByte Base tree), which
23 * remains under its own license.
24 *
25 * Neither license grants any patent rights. Any patent licenses required
26 * to use this software or third-party components must be obtained separately
27 * from the patent holders.
28 *
29 * StormByte-System is distributed in the hope that it will be useful,
30 * but WITHOUT ANY WARRANTY; without even the implied warranty of
31 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
32 * GNU Lesser General Public License for more details.
33 *
34 * You should have received a copy of the GNU Lesser General Public License
35 * version 3 along with StormByte-System. If not, see
36 * <https://www.gnu.org/licenses/lgpl-3.0.html>.
37 *
38 * SPDX-License-Identifier: LGPL-3.0-or-later OR LicenseRef-StormByte-Commercial
39 */
40
41#pragma once
42
43#include <StormByte/error.hxx>
44#include <StormByte/safe/pointers.hxx>
45#include <StormByte/safe/string.hxx>
46#include <StormByte/safe/vector.hxx>
48
49#include <chrono>
50#include <iostream>
51#include <string>
52#include <string_view>
53#include <system_error>
54#ifdef WINDOWS
55#include <windows.h>
56#else
57#include <unistd.h>
58#endif
59
60namespace StormByte::System {
61 class Pipe;
62 class ProcessImplementation;
63
68 struct {} typedef _EoF;
69
73 static constexpr const _EoF EoF = {};
74
88 public:
95 enum class Error {
96 Success = 0,
97 ExecutableNotFound,
98 CreationFailed,
99 Permission,
100 NotRunning,
101 AlreadyExited,
102 TimedOut,
103 BrokenPipe,
104 Canceled,
105 OperationFailed
106 };
107
112 enum class Status: unsigned short {
113 RUNNING,
114 SUSPENDED,
115 TERMINATED
116 };
117
123 Process(std::string_view prog, const StormByte::Safe::Vector<StormByte::Safe::String>& args = {}) noexcept;
124
125 Process(const Process& proc) = delete;
126
130 Process(Process&& proc) noexcept;
131
132 Process& operator=(const Process& proc) = delete;
133
137 Process& operator=(Process&& proc) noexcept;
138
142 virtual ~Process() noexcept;
143
148 explicit operator bool() const noexcept;
149
154 StormByte::Error::Fault Fault() const noexcept;
155
156 #ifdef UNIX
161 int Wait() noexcept;
162
168 int Wait(std::chrono::milliseconds timeout) noexcept;
169
174 pid_t Pid() noexcept;
175 #else
180 DWORD Wait() noexcept;
181
187 DWORD Wait(std::chrono::milliseconds timeout) noexcept;
188
193 DWORD Pid() noexcept;
194 #endif
195
199 void Suspend();
200
204 void Resume();
205
212
219
226
233 STORMBYTE_FORCE_INLINE friend std::ostream& operator<<(std::ostream& ostream, const Process& proc) {
235 proc >> owned;
236 return ostream << static_cast<std::string>(owned);
237 }
238
244 Process& operator<<(std::string_view str);
245
250 void operator<<(const System::_EoF& eof);
251
252 private:
253 #ifdef WINDOWS
259 static std::string QuoteWindowsArgument(std::string_view argument);
260
265 std::wstring FullCommand() const;
266 #endif
267
272 void Send(std::string_view str);
273
279 void Initialize(const StormByte::Safe::String& prog, const StormByte::Safe::Vector<StormByte::Safe::String>& args);
280
284 void Run();
285
289 void ReleaseOwnership() noexcept;
290
294 void JoinForwarder() noexcept;
295
300 void StopForwarder(bool close_source_read) noexcept;
301
302 StormByte::Safe::Unique<ProcessImplementation> m_implementation;
303 };
304
305}
306
310template<>
312 static constexpr const char* Name = "StormByte.System.Process";
313
320 switch (e) {
322 return "Success";
324 return "Executable not found";
326 return "Process creation failed";
328 return "Process permission denied";
330 return "Process is not running";
332 return "Process has already exited";
334 return "Process wait timed out";
336 return "Process pipe is broken";
338 return "Process operation canceled";
340 return "Process operation failed";
341 }
342 return "Unknown Process error";
343 }
344};
345
346namespace StormByte::System {
352
360 return std::error_code(static_cast<int>(e), process_category());
361 }
362}
363
364namespace std {
368 template<>
369 struct is_error_code_enum<StormByte::System::Process::Error>: true_type {};
370}
Runs an external program with piped stdin/stdout/stderr.
Definition process.hxx:87
Process & operator=(const Process &proc)=delete
void operator<<(const System::_EoF &eof)
Close process stdin (write end).
Process & operator=(Process &&proc) noexcept
Move assignment (invalidates the source).
STORMBYTE_FORCE_INLINE friend std::ostream & operator<<(std::ostream &ostream, const Process &proc)
Stream process stdout to an ostream.
Definition process.hxx:233
void Suspend()
Suspend the child process.
Error
Child-process enumerators.
Definition process.hxx:95
@ Canceled
The operation was canceled.
Definition process.hxx:104
@ ExecutableNotFound
The program path or name could not be resolved.
Definition process.hxx:97
@ AlreadyExited
The child has already exited.
Definition process.hxx:101
@ Success
No error.
Definition process.hxx:96
@ CreationFailed
The child could not be created (fork, pipe, CreateProcess).
Definition process.hxx:98
@ TimedOut
A timed wait expired.
Definition process.hxx:102
@ OperationFailed
A process operation failed at the platform boundary.
Definition process.hxx:105
@ NotRunning
There is no live child for this operation.
Definition process.hxx:100
@ Permission
The caller may not create or signal this child.
Definition process.hxx:99
@ BrokenPipe
stdin/stdout/stderr pipe is closed or unusable
Definition process.hxx:103
Process & operator<<(std::string_view str)
Write UTF-8 text to process stdin.
StormByte::Error::Fault Fault() const noexcept
Last Process error.
Process(const Process &proc)=delete
Process(Process &&proc) noexcept
Move constructor (invalidates the source).
void Resume()
Resume a suspended child process.
virtual ~Process() noexcept
Destructor (waits if still owning a child, then frees pipes).
Status
Process lifecycle.
Definition process.hxx:112
StormByte::Safe::String & Stderr(StormByte::Safe::String &str) const
Read remaining stderr into owned text.
pid_t Pid() noexcept
Child PID.
StormByte::Safe::String & operator>>(StormByte::Safe::String &str) const
Read remaining stdout into owned text.
Process & operator>>(Process &proc)
Forward this process stdout to proc stdin (background thread).
int Wait() noexcept
Block until the process exits (no timeout).
Process(std::string_view prog, const StormByte::Safe::Vector< StormByte::Safe::String > &args={}) noexcept
Construct and start.
System module of the StormByte suite.
Definition device.hxx:59
STORMBYTE_FORCE_INLINE std::error_code make_error_code(Device::Error e) noexcept
Builds an std::error_code from Device::Error.
Definition device.hxx:341
static constexpr const _EoF EoF
Sentinel used as process << System::EoF to close stdin.
Definition process.hxx:73
const StormByte::Error::Category< Process::Error > & process_category() noexcept
Category singleton for Process::Error.
STL namespace.
#define STORMBYTE_FORCE_INLINE
static STORMBYTE_FORCE_INLINE std::string Message(StormByte::System::Process::Error e)
Text for one Process enumerator.
Definition process.hxx:319
static constexpr const char * Name
Stable category tag.
Definition process.hxx:312
Tag type to close process stdin (write end).
Definition process.hxx:68
#define STORMBYTE_SYSTEM_PUBLIC
Definition visibility.h:53