Struct SharedSystem 

pub struct SharedSystem<S>(/* private fields */);

System shared by a reference counter.

A SharedSystem is a reference-counted container of a System instance accompanied with an internal state for supporting asynchronous interactions with the system. As it is reference-counted, cloning a SharedSystem instance only increments the reference count without cloning the backing system instance. This behavior allows calling SharedSystem’s methods concurrently from different async tasks that each have a SharedSystem instance sharing the same state.

SharedSystem implements System by delegating to the contained system instance of type S. You should avoid calling some of the System methods, however. Prefer async functions provided by SharedSystem (e.g., read_async) over raw system functions (e.g., read).

The following example illustrates how multiple concurrent tasks are run in a single-threaded pool:

let system = SharedSystem::new(VirtualSystem::new());
let system2 = system.clone();
let system3 = system.clone();
let (reader, writer) = system.pipe().unwrap();
let mut executor = futures_executor::LocalPool::new();

// We add a task that tries to read from the pipe, but nothing has been
// written to it, so the task is stalled.
let read_task = executor.spawner().spawn_local_with_handle(async move {
    let mut buffer = [0; 1];
    system.read_async(reader, &mut buffer).await.unwrap();
    buffer[0]
});
executor.run_until_stalled();

// Let's add a task that writes to the pipe.
executor.spawner().spawn_local(async move {
    system2.write_all(writer, &[123]).await.unwrap();
});
executor.run_until_stalled();

// The write task has written a byte to the pipe, but the read task is still
// stalled. We need to wake it up by calling `select`.
system3.select(false).unwrap();

// Now the read task can proceed to the end.
let number = executor.run_until(read_task.unwrap());
assert_eq!(number, 123);

If there is a child process in the VirtualSystem, you should call SystemState::select_all in addition to SharedSystem::select so that the child process task is woken up when needed. (TBD code example)

Implementations

impl<S> SharedSystem<S>

pub fn new(system: S) -> Self

Creates a new shared system.

pub async fn read_async(&self, fd: Fd, buffer: &mut [u8]) -> Result<usize>

where S: Fcntl + Read,

Reads from the file descriptor.

This function waits for one or more bytes to be available for reading. If successful, returns the number of bytes read.

pub async fn write_all(&self, fd: Fd, buffer: &[u8]) -> Result<usize>

where S: Fcntl + Write,

Writes to the file descriptor.

This function calls write repeatedly until the whole buffer is written to the FD. If the buffer is empty, write is not called at all, so any error that would be returned from write is not returned.

This function silently ignores signals that may interrupt writes.

pub async fn print_error(&self, message: &str)

where S: Fcntl + Write,

Convenience function for printing a message to the standard error

pub async fn wait_until(&self, target: Instant)

where S: Clock,

Waits until the specified time point.

pub async fn wait_for_signals(&self) -> Rc<[Number]>

Waits for some signals to be delivered to this process.

Before calling this function, you need to set the signal disposition to Catch. Without doing so, this function cannot detect the receipt of the signals.

Returns an array of signals that were caught.

If this SharedSystem is part of an Env, you should call Env::wait_for_signals rather than calling this function directly so that the trap set can remember the caught signal.

pub async fn wait_for_signal(&self, signal: Number)

Waits for a signal to be delivered to this process.

Before calling this function, you need to set the signal disposition to Catch. Without doing so, this function cannot detect the receipt of the signal.

If this SharedSystem is part of an Env, you should call Env::wait_for_signal rather than calling this function directly so that the trap set can remember the caught signal.

pub fn select(&self, poll: bool) -> Result<()>

where S: Select + CaughtSignals + Clock,

Waits for a next event to occur.

This function calls Select::select with arguments computed from the current internal state of the SharedSystem. It will wake up tasks waiting for the file descriptor to be ready in read_async and write_all or for a signal to be caught in wait_for_signal. If no tasks are woken for FDs or signals and poll is false, this function will block until the first task waiting for a specific time point is woken.

If poll is true, this function does not block, so it may not wake up any tasks.

This function may wake up a task even if the condition it is expecting has not yet been met.

pub fn new_child_process(&self) -> Result<ChildProcessStarter<S>>

where S: Fork,

Creates a new child process.

See Fork::new_child_process for details.

Trait Implementations

impl<T: CaughtSignals> CaughtSignals for SharedSystem<T>

Delegates CaughtSignals methods to the contained implementor.

fn caught_signals(&self) -> Vec<Number>

Returns signals this process has caught, if any.

impl<T: Chdir> Chdir for SharedSystem<T>

Delegates Chdir methods to the contained implementor.

fn chdir(&self, path: &CStr) -> Result<()>

Changes the working directory.

impl<T: Clock> Clock for SharedSystem<T>

Delegates Time methods to the contained implementor.

fn now(&self) -> Instant

Returns the current time.

impl<S> Clone for SharedSystem<S>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Close> Close for SharedSystem<T>

fn close(&self, fd: Fd) -> Result<()>

Closes a file descriptor.

impl<S: Debug> Debug for SharedSystem<S>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Dup> Dup for SharedSystem<T>

Delegates Dup methods to the contained implementor.

fn dup(&self, from: Fd, to_min: Fd, flags: EnumSet<FdFlag>) -> Result<Fd>

Duplicates a file descriptor.

fn dup2(&self, from: Fd, to: Fd) -> Result<Fd>

Duplicates a file descriptor.

impl<T: Exec> Exec for SharedSystem<T>

Delegates Exec methods to the contained implementor.

fn execve( &self, path: &CStr, args: &[CString], envs: &[CString], ) -> impl Future<Output = Result<Infallible>> + use<T>

Replaces the current process with an external utility.

impl<T: Exit> Exit for SharedSystem<T>

Delegates Exit methods to the contained implementor.

fn exit( &self, exit_status: ExitStatus, ) -> impl Future<Output = Infallible> + use<T>

Terminates the current process.

impl<T: Fcntl> Fcntl for SharedSystem<T>

Delegates Fcntl methods to the contained implementor.

fn ofd_access(&self, fd: Fd) -> Result<OfdAccess>

Returns the open file description access mode.

fn get_and_set_nonblocking(&self, fd: Fd, nonblocking: bool) -> Result<bool>

Gets and sets the non-blocking mode for the open file description.

fn fcntl_getfd(&self, fd: Fd) -> Result<EnumSet<FdFlag>>

Returns the attributes for the file descriptor.

fn fcntl_setfd(&self, fd: Fd, flags: EnumSet<FdFlag>) -> Result<()>

Sets attributes for the file descriptor.

impl<T: Fstat> Fstat for SharedSystem<T>

Delegates Fstat methods to the contained implementor.

fn fstat(&self, fd: Fd) -> Result<Stat>

Retrieves metadata of a file.

fn fstatat( &self, dir_fd: Fd, path: &CStr, follow_symlinks: bool, ) -> Result<Stat>

Retrieves metadata of a file.

fn is_directory(&self, path: &CStr) -> bool

Whether there is a directory at the specified path.

fn fd_is_pipe(&self, fd: Fd) -> bool

Tests if a file descriptor is a pipe.

impl<T: GetCwd> GetCwd for SharedSystem<T>

Delegates GetCwd methods to the contained implementor.

fn getcwd(&self) -> Result<PathBuf>

Returns the current working directory path.

impl<T: GetPid> GetPid for SharedSystem<T>

Delegates GetPid methods to the contained implementor.

fn getsid(&self, pid: Pid) -> Result<Pid>

Returns the session ID of the specified process.

fn getpid(&self) -> Pid

Returns the process ID of the current process.

fn getppid(&self) -> Pid

Returns the process ID of the parent process.

fn getpgrp(&self) -> Pid

Returns the process group ID of the current process.

impl<T: GetPw> GetPw for SharedSystem<T>

Delegates GetPw methods to the contained implementor.

fn getpwnam_dir(&self, name: &CStr) -> Result<Option<PathBuf>>

Returns the home directory path of the given user.

impl<T: GetRlimit> GetRlimit for SharedSystem<T>

Delegates GetRlimit methods to the contained implementor.

fn getrlimit(&self, resource: Resource) -> Result<LimitPair>

Returns the limits for the specified resource.

impl<T: Sigaction> GetSigaction for SharedSystem<T>

Delegates GetSigaction methods to the contained implementor.

fn get_sigaction(&self, signal: Number) -> Result<Disposition>

Gets the disposition for a signal.

impl<T: GetUid> GetUid for SharedSystem<T>

Delegates GetUid methods to the contained implementor.

fn getuid(&self) -> Uid

Returns the real user ID of the current process.

fn geteuid(&self) -> Uid

Returns the effective user ID of the current process.

fn getgid(&self) -> Gid

Returns the real group ID of the current process.

fn getegid(&self) -> Gid

Returns the effective group ID of the current process.

impl<T: IsExecutableFile> IsExecutableFile for SharedSystem<T>

Delegates IsExecutableFile methods to the contained implementor.

fn is_executable_file(&self, path: &CStr) -> bool

Whether there is an executable regular file at the specified path.

impl<T: Isatty> Isatty for SharedSystem<T>

Delegates Isatty methods to the contained implementor.

fn isatty(&self, fd: Fd) -> bool

Tests if a file descriptor is associated with a terminal device.

impl<T: Open> Open for SharedSystem<T>

fn open( &self, path: &CStr, access: OfdAccess, flags: EnumSet<OpenFlag>, mode: Mode, ) -> Result<Fd>

Opens a file descriptor.

fn open_tmpfile(&self, parent_dir: &Path) -> Result<Fd>

Opens a file descriptor associated with an anonymous temporary file.

fn fdopendir(&self, fd: Fd) -> Result<impl Dir + use<T>>

Opens a directory for enumerating entries.

fn opendir(&self, path: &CStr) -> Result<impl Dir + use<T>>

Opens a directory for enumerating entries.

impl<T: Pipe> Pipe for SharedSystem<T>

Delegates Pipe methods to the contained implementor.

fn pipe(&self) -> Result<(Fd, Fd)>

Creates an unnamed pipe.

impl<T: Read> Read for SharedSystem<T>

Delegates Read methods to the contained implementor.

fn read(&self, fd: Fd, buffer: &mut [u8]) -> Result<usize>

Reads from the file descriptor.

impl<T: Seek> Seek for SharedSystem<T>

Delegates Seek methods to the contained implementor.

fn lseek(&self, fd: Fd, position: SeekFrom) -> Result<u64>

Moves the position of the open file description.

impl<T: Select> Select for SharedSystem<T>

Delegates Select methods to the contained implementor.

fn select( &self, readers: &mut Vec<Fd>, writers: &mut Vec<Fd>, timeout: Option<Duration>, signal_mask: Option<&[Number]>, ) -> Result<c_int>

Waits for a next event.

impl<T: SendSignal> SendSignal for SharedSystem<T>

Delegates SendSignal methods to the contained implementor.

fn kill( &self, target: Pid, signal: Option<Number>, ) -> impl Future<Output = Result<()>> + use<T>

Sends a signal.

fn raise(&self, signal: Number) -> impl Future<Output = Result<()>> + use<T>

Sends a signal to the current process.

impl<T: SetPgid> SetPgid for SharedSystem<T>

Delegates SetPgid methods to the contained implementor.

fn setpgid(&self, pid: Pid, pgid: Pid) -> Result<()>

Modifies the process group ID of a process.

impl<T: SetRlimit> SetRlimit for SharedSystem<T>

Delegates SetRlimit methods to the contained implementor.

fn setrlimit(&self, resource: Resource, limits: LimitPair) -> Result<()>

Sets the limits for the specified resource.

impl<T: ShellPath> ShellPath for SharedSystem<T>

Delegates ShellPath methods to the contained implementor.

fn shell_path(&self) -> CString

Returns the path to the shell executable.

impl<T: Sigaction> Sigaction for SharedSystem<T>

Delegates Sigaction methods to the contained implementor.

fn sigaction(&self, signal: Number, action: Disposition) -> Result<Disposition>

Gets and sets the disposition for a signal.

impl<T: Sigmask> Sigmask for SharedSystem<T>

Delegates Sigmask methods to the contained implementor.

fn sigmask( &self, op: Option<(SigmaskOp, &[Number])>, old_mask: Option<&mut Vec<Number>>, ) -> Result<()>

Gets and/or sets the signal blocking mask.

impl<S: Signals + Sigmask + Sigaction> SignalSystem for SharedSystem<S>

fn get_disposition(&self, signal: Number) -> Result<Disposition>

Returns the current disposition for a signal.

fn set_disposition( &mut self, signal: Number, disposition: Disposition, ) -> Result<Disposition>

Sets how a signal is handled.

impl<T: Signals> Signals for SharedSystem<T>

Delegates Signals methods to the contained implementor.

const SIGABRT: Number = T::SIGABRT

The signal number for SIGABRT

const SIGALRM: Number = T::SIGALRM

The signal number for SIGALRM

const SIGBUS: Number = T::SIGBUS

The signal number for SIGBUS

const SIGCHLD: Number = T::SIGCHLD

The signal number for SIGCHLD

const SIGCLD: Option<Number> = T::SIGCLD

The signal number for SIGCLD, if available on the system

const SIGCONT: Number = T::SIGCONT

The signal number for SIGCONT

const SIGEMT: Option<Number> = T::SIGEMT

The signal number for SIGEMT, if available on the system

const SIGFPE: Number = T::SIGFPE

The signal number for SIGFPE

const SIGHUP: Number = T::SIGHUP

The signal number for SIGHUP

const SIGILL: Number = T::SIGILL

The signal number for SIGILL

const SIGINFO: Option<Number> = T::SIGINFO

The signal number for SIGINFO, if available on the system

const SIGINT: Number = T::SIGINT

The signal number for SIGINT

const SIGIO: Option<Number> = T::SIGIO

The signal number for SIGIO, if available on the system

const SIGIOT: Number = T::SIGIOT

The signal number for SIGIOT

const SIGKILL: Number = T::SIGKILL

The signal number for SIGKILL

const SIGLOST: Option<Number> = T::SIGLOST

The signal number for SIGLOST, if available on the system

const SIGPIPE: Number = T::SIGPIPE

The signal number for SIGPIPE

const SIGPOLL: Option<Number> = T::SIGPOLL

The signal number for SIGPOLL, if available on the system

const SIGPROF: Number = T::SIGPROF

The signal number for SIGPROF

const SIGPWR: Option<Number> = T::SIGPWR

The signal number for SIGPWR, if available on the system

const SIGQUIT: Number = T::SIGQUIT

The signal number for SIGQUIT

const SIGSEGV: Number = T::SIGSEGV

The signal number for SIGSEGV

const SIGSTKFLT: Option<Number> = T::SIGSTKFLT

The signal number for SIGSTKFLT, if available on the system

const SIGSTOP: Number = T::SIGSTOP

The signal number for SIGSTOP

const SIGSYS: Number = T::SIGSYS

The signal number for SIGSYS

const SIGTERM: Number = T::SIGTERM

The signal number for SIGTERM

const SIGTHR: Option<Number> = T::SIGTHR

The signal number for SIGTHR, if available on the system

const SIGTRAP: Number = T::SIGTRAP

The signal number for SIGTRAP

const SIGTSTP: Number = T::SIGTSTP

The signal number for SIGTSTP

const SIGTTIN: Number = T::SIGTTIN

The signal number for SIGTTIN

const SIGTTOU: Number = T::SIGTTOU

The signal number for SIGTTOU

const SIGURG: Number = T::SIGURG

The signal number for SIGURG

const SIGUSR1: Number = T::SIGUSR1

The signal number for SIGUSR1

const SIGUSR2: Number = T::SIGUSR2

The signal number for SIGUSR2

const SIGVTALRM: Number = T::SIGVTALRM

The signal number for SIGVTALRM

const SIGWINCH: Number = T::SIGWINCH

The signal number for SIGWINCH

const SIGXCPU: Number = T::SIGXCPU

The signal number for SIGXCPU

const SIGXFSZ: Number = T::SIGXFSZ

The signal number for SIGXFSZ

fn sigrt_range(&self) -> Option<RangeInclusive<Number>>

Returns the range of real-time signals supported by the system.

fn iter_sigrt(&self) -> impl DoubleEndedIterator<Item = Number> + use<T>

Returns an iterator over all real-time signals supported by the system.

fn validate_signal(&self, number: RawNumber) -> Option<(Name, Number)>

Tests if a signal number is valid and returns its name and number.

const NAMED_SIGNALS: &'static [(&'static str, Option<Number>)] = _

List of all signal names and their numbers, excluding real-time signals

fn to_signal_number<N: Into<RawNumber>>(&self, number: N) -> Option<Number>

Tests if a signal number is valid and returns its signal number.

fn sig2str<N: Into<RawNumber>>(&self, signal: N) -> Option<Cow<'static, str>>

Converts a signal number to its string representation.

fn str2sig(&self, name: &str) -> Option<Number>

Converts a string representation of a signal to its signal number.

fn signal_name_from_number(&self, number: Number) -> Name

Returns the signal name for the signal number.

fn signal_number_from_name(&self, name: Name) -> Option<Number>

Gets the signal number from the signal name.

impl<T: Sysconf> Sysconf for SharedSystem<T>

Delegates Sysconf methods to the contained implementor.

fn confstr_path(&self) -> Result<UnixString>

Returns the standard $PATH value where all standard utilities are expected to be found.

impl<T: TcGetPgrp> TcGetPgrp for SharedSystem<T>

Delegates TcGetPgrp methods to the contained implementor.

fn tcgetpgrp(&self, fd: Fd) -> Result<Pid>

Returns the current foreground process group ID.

impl<T: TcSetPgrp> TcSetPgrp for SharedSystem<T>

Delegates TcSetPgrp methods to the contained implementor.

fn tcsetpgrp( &self, fd: Fd, pgid: Pid, ) -> impl Future<Output = Result<()>> + use<T>

Switches the foreground process group.

impl<T: Times> Times for SharedSystem<T>

Delegates Times methods to the contained implementor.

fn times(&self) -> Result<CpuTimes>

Returns the consumed CPU time statistics.

impl<T: Umask> Umask for SharedSystem<T>

Delegates Umask methods to the contained implementor.

fn umask(&self, new_mask: Mode) -> Mode

Gets and sets the file creation mode mask.

impl<T: Wait> Wait for SharedSystem<T>

Delegates Wait methods to the contained implementor.

fn wait(&self, target: Pid) -> Result<Option<(Pid, ProcessState)>>

Reports updated status of a child process.

impl<T: Write> Write for SharedSystem<T>

Delegates Write methods to the contained implementor.

fn write(&self, fd: Fd, buffer: &[u8]) -> Result<usize>

Writes to the file descriptor.