Skip to main content

Tracer

Trait Tracer 

Source
pub trait Tracer: Send + Sync {
    // Required methods
    fn run(
        &self,
        request: &RunRequest,
        echo: &dyn EchoSink,
        cancel: &Cancellation,
    ) -> Result<RunResult, TraceError>;
    fn extended_attributes(
        &self,
        path: &Path,
        follow: bool,
    ) -> Result<ExtendedAttributes>;
    fn machine_state(&self, cwd: &Path) -> MachineState;

    // Provided methods
    fn run_untraced(
        &self,
        _request: &RunRequest,
        _echo: &dyn EchoSink,
        _cancel: &Cancellation,
    ) -> Result<RunResult, TraceError> { ... }
    fn error_name(&self, errno: i32) -> String { ... }
}
Expand description

Runs and traces commands, and answers the platform queries of the core.

The Linux tracer implements it with ptrace and seccomp, and tests implement it with a fake that performs scripted file operations and reports them, and that answers the queries from values the test sets.

Required Methods§

Source

fn run( &self, request: &RunRequest, echo: &dyn EchoSink, cancel: &Cancellation, ) -> Result<RunResult, TraceError>

Run one command, wait for its whole process tree to finish, and report what it did.

When RunRequest::echo is set, output also goes to echo live. When cancel is set while the command runs, the tracer interrupts the whole process tree, kills whatever remains of it after a grace period, and returns the result once the tree has exited; the command may then have ended by a signal or with an exit code. A signal that the caller forwards through cancel with Cancellation::forward while the command runs goes once to the command’s first process while it lives, and afterwards to each live process of the tree; a fake tracer may ignore it. When RunRequest::terminal is set, the command keeps the terminal and the result’s output is empty.

§Errors

Returns a TraceError when the command could not start or the tracer failed.

Source

fn extended_attributes( &self, path: &Path, follow: bool, ) -> Result<ExtendedAttributes>

The extended attributes of path, each name with its value, sorted by name, following a final symbolic link when follow is set, or not when it is not. A file system that keeps no extended attributes has none.

The core reads extended attributes only through this query, because the standard library cannot read them.

§Errors

Returns the error of reading the attributes, such as io::ErrorKind::NotFound when nothing is at the path.

Source

fn machine_state(&self, cwd: &Path) -> MachineState

The machine and process state that a command started in cwd inherits: the kernel, the resource limits, the CPUs it may run on, the memory, and the file system that holds cwd, with its size and free space. A part that cannot be read is None.

The core reads machine state only through this query, because the standard library cannot read it.

Provided Methods§

Source

fn run_untraced( &self, _request: &RunRequest, _echo: &dyn EchoSink, _cancel: &Cancellation, ) -> Result<RunResult, TraceError>

Run a command without tracing its dependencies. The engine never reuses its result. Implementations must preserve the request’s environment, streams and cancellation. The result must mark observation incomplete, including any forced stream closure, and must not claim unobserved dependencies.

§Errors

Returns an error when untraced execution is unsupported or the command cannot start.

Source

fn error_name(&self, errno: i32) -> String

The name of the error number errno on the platform, such as ENOENT, which the core uses to report a failed check of its own as the tracer reports a failed call.

The default answer is unnamed_error, errno and the number, so a tracer that knows no names, such as a fake, needs no implementation.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§