WPILibC++ 2024.3.2
wpi::uv::Process Class Referencefinal

Process handle. More...

#include <wpinet/uv/Process.h>

Inheritance diagram for wpi::uv::Process:
wpi::uv::HandleImpl< Process, uv_process_t > wpi::uv::Handle

Classes

struct  Option
 Structure for Spawn() option temporaries. More...
 

Public Member Functions

 Process (const private_init &)
 
 ~Process () noexcept override=default
 
void Kill (int signum)
 Sends the specified signal to the process. More...
 
uv_pid_t GetPid () const noexcept
 Get the process ID. More...
 
- Public Member Functions inherited from wpi::uv::HandleImpl< Process, uv_process_t >
std::shared_ptr< Processshared_from_this ()
 
std::shared_ptr< const Processshared_from_this () const
 
uv_process_tGetRaw () const noexcept
 Get the underlying handle data structure. More...
 
- Public Member Functions inherited from wpi::uv::Handle
 Handle (const Handle &)=delete
 
 Handle (Handle &&)=delete
 
Handleoperator= (const Handle &)=delete
 
Handleoperator= (Handle &&)=delete
 
virtual ~Handle () noexcept
 
Type GetType () const noexcept
 Get the type of the handle. More...
 
std::string_view GetTypeName () const noexcept
 Get the name of the type of the handle. More...
 
std::shared_ptr< LoopGetLoop () const noexcept
 Get the loop where this handle runs. More...
 
LoopGetLoopRef () const noexcept
 Get the loop where this handle runs. More...
 
bool IsActive () const noexcept
 Check if the handle is active. More...
 
bool IsClosing () const noexcept
 Check if a handle is closing or closed. More...
 
void Close () noexcept
 Request handle to be closed. More...
 
void SetLoopClosing (bool loopClosing) noexcept
 Set if the loop is closing. More...
 
bool IsLoopClosing () const noexcept
 Get the loop closing status. More...
 
void Reference () noexcept
 Reference the given handle. More...
 
void Unreference () noexcept
 Unreference the given handle. More...
 
bool HasReference () const noexcept
 Check if the given handle is referenced. More...
 
size_t RawSize () const noexcept
 Return the size of the underlying handle type. More...
 
uv_handle_tGetRawHandle () const noexcept
 Get the underlying handle data structure. More...
 
void SetBufferAllocator (std::function< Buffer(size_t)> alloc, std::function< void(Buffer &)> dealloc)
 Set the functions used for allocating and releasing buffers. More...
 
void FreeBuf (Buffer &buf) const noexcept
 Free a buffer. More...
 
template<typename T = void>
std::shared_ptr< T > GetData () const
 Gets user-defined data. More...
 
void SetData (std::shared_ptr< void > data)
 Sets user-defined data. More...
 
void SetLogger (Logger *logger)
 Sets logger. More...
 
LoggerGetLogger () const
 Gets logger. More...
 
void ReportError (int err) const
 Report an error. More...
 

Static Public Member Functions

static Option Env (std::string_view env)
 Set environment variable for the subprocess. More...
 
static Option Cwd (std::string_view cwd)
 Set the current working directory for the subprocess. More...
 
static Option Uid (uv_uid_t uid)
 Set the child process' user id. More...
 
static Option Gid (uv_gid_t gid)
 Set the child process' group id. More...
 
static Option SetFlags (unsigned int flags)
 Set spawn flags. More...
 
static Option ClearFlags (unsigned int flags)
 Clear spawn flags. More...
 
static Option StdioIgnore (size_t index)
 Explicitly ignore a stdio. More...
 
static Option StdioInherit (size_t index, int fd)
 Inherit a file descriptor from the parent process. More...
 
static Option StdioInherit (size_t index, Pipe &pipe)
 Inherit a pipe from the parent process. More...
 
static Option StdioCreatePipe (size_t index, Pipe &pipe, unsigned int flags)
 Create a pipe between the child and the parent. More...
 
static void DisableStdioInheritance ()
 Disables inheritance for file descriptors / handles that this process inherited from its parent. More...
 
static std::shared_ptr< ProcessSpawnArray (Loop &loop, std::string_view file, std::span< const Option > options)
 Starts a process. More...
 
static std::shared_ptr< ProcessSpawnArray (Loop &loop, std::string_view file, std::initializer_list< Option > options)
 
template<typename... Args>
static std::shared_ptr< ProcessSpawn (Loop &loop, std::string_view file, const Args &... options)
 
static std::shared_ptr< ProcessSpawnArray (const std::shared_ptr< Loop > &loop, std::string_view file, std::span< const Option > options)
 Starts a process. More...
 
static std::shared_ptr< ProcessSpawnArray (const std::shared_ptr< Loop > &loop, std::string_view file, std::initializer_list< Option > options)
 
template<typename... Args>
static std::shared_ptr< ProcessSpawn (const std::shared_ptr< Loop > &loop, std::string_view file, const Args &... options)
 
static int Kill (int pid, int signum) noexcept
 Sends the specified signal to the given PID. More...
 

Public Attributes

sig::Signal< int64_t, int > exited
 Signal generated when the process exits. More...
 
- Public Attributes inherited from wpi::uv::Handle
sig::Signal< Errorerror
 Error signal. More...
 
sig::Signal closed
 Closed signal. More...
 

Additional Inherited Members

- Public Types inherited from wpi::uv::Handle
using Type = uv_handle_type
 
- Protected Member Functions inherited from wpi::uv::HandleImpl< Process, uv_process_t >
 HandleImpl ()
 
- Protected Member Functions inherited from wpi::uv::Handle
 Handle (uv_handle_t *uv_handle)
 
void Keep () noexcept
 
void Release () noexcept
 
void ForceClosed () noexcept
 
template<typename F , typename... Args>
bool Invoke (F &&f, Args &&... args) const
 
- Static Protected Member Functions inherited from wpi::uv::Handle
static void AllocBuf (uv_handle_t *handle, size_t size, uv_buf_t *buf)
 
static void DefaultFreeBuf (Buffer &buf)
 

Detailed Description

Process handle.

Process handles will spawn a new process and allow the user to control it and establish communication channels with it using streams.

Constructor & Destructor Documentation

◆ Process()

wpi::uv::Process::Process ( const private_init &  )
inlineexplicit

◆ ~Process()

wpi::uv::Process::~Process ( )
overridedefaultnoexcept

Member Function Documentation

◆ ClearFlags()

static Option wpi::uv::Process::ClearFlags ( unsigned int  flags)
inlinestatic

Clear spawn flags.

Parameters
flagsBitmask values from uv_process_flags.

◆ Cwd()

static Option wpi::uv::Process::Cwd ( std::string_view  cwd)
inlinestatic

Set the current working directory for the subprocess.

Parameters
cwdcurrent working directory

◆ DisableStdioInheritance()

static void wpi::uv::Process::DisableStdioInheritance ( )
inlinestatic

Disables inheritance for file descriptors / handles that this process inherited from its parent.

The effect is that child processes spawned by this process don't accidentally inherit these handles.

It is recommended to call this function as early in your program as possible, before the inherited file descriptors can be closed or duplicated.

◆ Env()

static Option wpi::uv::Process::Env ( std::string_view  env)
inlinestatic

Set environment variable for the subprocess.

If not set, the parent's environment is used.

Parameters
envenvironment variable

◆ GetPid()

uv_pid_t wpi::uv::Process::GetPid ( ) const
inlinenoexcept

Get the process ID.

Returns
Process ID.

◆ Gid()

static Option wpi::uv::Process::Gid ( uv_gid_t  gid)
inlinestatic

Set the child process' group id.

Parameters
gidgroup id

◆ Kill() [1/2]

static int wpi::uv::Process::Kill ( int  pid,
int  signum 
)
inlinestaticnoexcept

Sends the specified signal to the given PID.

Parameters
pidprocess ID
signumsignal number
Returns
0 on success, otherwise error code.

◆ Kill() [2/2]

void wpi::uv::Process::Kill ( int  signum)
inline

Sends the specified signal to the process.

Parameters
signumsignal number

◆ SetFlags()

static Option wpi::uv::Process::SetFlags ( unsigned int  flags)
inlinestatic

Set spawn flags.

Parameters
flagsBitmask values from uv_process_flags.

◆ Spawn() [1/2]

template<typename... Args>
static std::shared_ptr< Process > wpi::uv::Process::Spawn ( const std::shared_ptr< Loop > &  loop,
std::string_view  file,
const Args &...  options 
)
inlinestatic

◆ Spawn() [2/2]

template<typename... Args>
static std::shared_ptr< Process > wpi::uv::Process::Spawn ( Loop loop,
std::string_view  file,
const Args &...  options 
)
inlinestatic

◆ SpawnArray() [1/4]

static std::shared_ptr< Process > wpi::uv::Process::SpawnArray ( const std::shared_ptr< Loop > &  loop,
std::string_view  file,
std::initializer_list< Option options 
)
inlinestatic

◆ SpawnArray() [2/4]

static std::shared_ptr< Process > wpi::uv::Process::SpawnArray ( const std::shared_ptr< Loop > &  loop,
std::string_view  file,
std::span< const Option options 
)
inlinestatic

Starts a process.

If the process is not successfully spawned, an error is generated on the loop and this function returns nullptr.

Possible reasons for failing to spawn would include (but not be limited to) the file to execute not existing, not having permissions to use the setuid or setgid specified, or not having enough memory to allocate for the new process.

Parameters
loopLoop object where this handle runs.
filePath pointing to the program to be executed
optionsProcess options

◆ SpawnArray() [3/4]

static std::shared_ptr< Process > wpi::uv::Process::SpawnArray ( Loop loop,
std::string_view  file,
std::initializer_list< Option options 
)
inlinestatic

◆ SpawnArray() [4/4]

static std::shared_ptr< Process > wpi::uv::Process::SpawnArray ( Loop loop,
std::string_view  file,
std::span< const Option options 
)
static

Starts a process.

If the process is not successfully spawned, an error is generated on the loop and this function returns nullptr.

Possible reasons for failing to spawn would include (but not be limited to) the file to execute not existing, not having permissions to use the setuid or setgid specified, or not having enough memory to allocate for the new process.

Parameters
loopLoop object where this handle runs.
filePath pointing to the program to be executed
optionsProcess options

◆ StdioCreatePipe()

static Option wpi::uv::Process::StdioCreatePipe ( size_t  index,
Pipe pipe,
unsigned int  flags 
)
inlinestatic

Create a pipe between the child and the parent.

Parameters
indexstdio index
pipepipe
flagsSome combination of UV_READABLE_PIPE, UV_WRITABLE_PIPE, and UV_OVERLAPPED_PIPE (Windows only, ignored on Unix).

◆ StdioIgnore()

static Option wpi::uv::Process::StdioIgnore ( size_t  index)
inlinestatic

Explicitly ignore a stdio.

Parameters
indexstdio index

◆ StdioInherit() [1/2]

static Option wpi::uv::Process::StdioInherit ( size_t  index,
int  fd 
)
inlinestatic

Inherit a file descriptor from the parent process.

Parameters
indexstdio index
fdparent file descriptor

◆ StdioInherit() [2/2]

static Option wpi::uv::Process::StdioInherit ( size_t  index,
Pipe pipe 
)
inlinestatic

Inherit a pipe from the parent process.

Parameters
indexstdio index
pipepipe

◆ Uid()

static Option wpi::uv::Process::Uid ( uv_uid_t  uid)
inlinestatic

Set the child process' user id.

Parameters
uiduser id

Member Data Documentation

◆ exited

sig::Signal<int64_t, int> wpi::uv::Process::exited

Signal generated when the process exits.

The parameters are the exit status and the signal that caused the process to terminate, if any.


The documentation for this class was generated from the following file: