Struct SharedSystem

Source

pub struct SharedSystem<S>(/* 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 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)

SharedSystem

Struct SharedSystem Copy item path

Implementations§

impl<S> SharedSystem<S>

pub fn new(system: S) -> Self

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

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

pub async fn print_error(&self, message: &str)where S: Fcntl + Write,

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

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<()>where S: Select + CaughtSignals + Clock,

pub fn new_child_process(&self) -> Result<ChildProcessStarter<S>>where S: Fork,

Trait Implementations§

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

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

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

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

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

fn now(&self) -> Instant

impl<S> Clone for SharedSystem<S>

fn clone(&self) -> Self

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

impl<T: Fork> Fork for SharedSystem<T>

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

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

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

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

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

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

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

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

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

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

fn getpid(&self) -> Pid

fn getppid(&self) -> Pid

fn getpgrp(&self) -> Pid

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

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

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

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

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

fn getuid(&self) -> Uid

fn geteuid(&self) -> Uid

fn getgid(&self) -> Gid

fn getegid(&self) -> Gid

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Struct SharedSystem

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

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

pub async fn print_error(&self, message: &str)
where S: Fcntl + Write,

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

pub fn select(&self, poll: bool) -> Result<()>
where S: Select + CaughtSignals + Clock,

pub fn new_child_process(&self) -> Result<ChildProcessStarter<S>>
where S: Fork,

impl<T> Any for T
where T: 'static + ?Sized,

impl<T> Borrow<T> for T
where T: ?Sized,

impl<T> BorrowMut<T> for T
where T: ?Sized,

impl<T> CloneToUninit for T
where T: Clone,

impl<T> DynClone for T
where T: Clone,

impl<T, U> Into<U> for T
where U: From<T>,

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

impl<T> SystemEx for T
where T: System + ?Sized,