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§
Sourcefn run(
&self,
request: &RunRequest,
echo: &dyn EchoSink,
cancel: &Cancellation,
) -> Result<RunResult, TraceError>
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.
Sourcefn extended_attributes(
&self,
path: &Path,
follow: bool,
) -> Result<ExtendedAttributes>
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.
Sourcefn machine_state(&self, cwd: &Path) -> MachineState
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§
Sourcefn run_untraced(
&self,
_request: &RunRequest,
_echo: &dyn EchoSink,
_cancel: &Cancellation,
) -> Result<RunResult, TraceError>
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.
Sourcefn error_name(&self, errno: i32) -> String
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".