Struct SharedSystem

Source

pub struct SharedSystem(/* private fields */);

Expand description

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. 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 mut system = SharedSystem::new(Box::new(VirtualSystem::new()));
let mut system2 = system.clone();
let mut 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)

SharedSystem

Struct SharedSystem Copy item path

Implementations§

impl SharedSystem

pub fn new(system: Box<dyn System>) -> Self

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

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

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

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

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

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

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

Trait Implementations§

impl Clone for SharedSystem

fn clone(&self) -> SharedSystem

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

impl Debug for SharedSystem

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

impl SignalSystem for &SharedSystem

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

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

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

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

impl SignalSystem for SharedSystem

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

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

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

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

impl System for &SharedSystem

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

fn fdopendir(&mut self, fd: Fd) -> Result<Box<dyn Dir>>

fn opendir(&mut self, path: &CStr) -> Result<Box<dyn Dir>>

fn umask(&mut self, mask: Mode) -> Mode

fn now(&self) -> Instant

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

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

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

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

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

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

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

fn kill( &mut self, target: Pid, signal: Option<Number>, ) -> FlexFuture<Result<()>> ⓘ

fn raise(&mut self, signal: Number) -> FlexFuture<Result<()>> ⓘ

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

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

fn getpid(&self) -> Pid

fn getppid(&self) -> Pid

fn getpgrp(&self) -> Pid

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

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

fn tcsetpgrp(&mut self, fd: Fd, pgid: Pid) -> Result<()>

fn new_child_process(&mut self) -> Result<ChildProcessStarter>

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

fn execve( &mut self, path: &CStr, args: &[CString], envs: &[CString], ) -> FlexFuture<Result<Infallible>> ⓘ

fn exit(&mut self, exit_status: ExitStatus) -> FlexFuture<Infallible> ⓘ

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

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

fn getuid(&self) -> Uid

fn geteuid(&self) -> Uid

fn getgid(&self) -> Gid

fn getegid(&self) -> Gid

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

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

Struct SharedSystem