Struct gix_filter::driver::State

pub struct State {
    pub context: Context,
    /* private fields */
}

State required to handle process filters, which are running until all their work is done.

These can be significantly faster on some platforms as they are launched only once, while supporting asynchronous processing.

Lifecycle

Note that shutdown() must be called to finalize long-running processes. Failing to do so will naturally shut them down by terminating their pipes, but finishing explicitly allows to wait for processes as well.

Fields

context: Context

The context to pass to spawned filter programs.

Implementations

impl State

Lifecycle

pub fn maybe_launch_process( &mut self, driver: &Driver, operation: Operation, rela_path: &BStr, ) -> Result<Option<Process<'_>>, Error>

Obtain a process as defined in driver suitable for a given operation. rela_pathmay be used to substitute the current file for use in the invokedSingleFile` process.

Note that if a long-running process is defined, the operation isn’t relevant and capabilities are to be checked by the caller.

impl State

Apply operations to filter programs.

pub fn apply<'a>( &'a mut self, driver: &Driver, src: &mut impl Read, operation: Operation, ctx: Context<'_, '_>, ) -> Result<Option<Box<dyn Read + 'a>>, Error>

Apply operation of driver to the bytes read from src and return a reader to immediately consume the output produced by the filter. rela_path is the repo-relative path of the entry to handle. It’s possible that the filter stays inactive, in which case the src isn’t consumed and has to be used by the caller.

Each call to this method will cause the corresponding filter to be invoked unless driver indicates a process filter, which is only launched once and maintained using this state.

Note that it’s not an error if there is no filter process for operation or if a long-running process doesn’t supported the desired capability.

Deviation

If a long running process returns the ‘abort’ status after receiving the data, it will be removed similar to how git does it. However, it delivers an unsuccessful error status later, it will not be removed, but reports the error only. If any other non-‘error’ status is received, the process will be stopped. But that doesn’t happen if if such a status is received after reading the filtered result.

pub fn apply_delayed<'a>( &'a mut self, driver: &Driver, src: &mut impl Read, operation: Operation, delay: Delay, ctx: Context<'_, '_>, ) -> Result<Option<MaybeDelayed<'a>>, Error>

Like [apply()]Self::apply(), but use delay to determine if the filter result may be delayed or not.

Poll list_delayed_paths() until it is empty and query the available paths again. Note that even though it’s possible, the API assumes that commands aren’t mixed when delays are allowed.

impl State

Lifecycle

pub fn shutdown( self, mode: Mode, ) -> Result<Vec<(BString, Option<ExitStatus>)>, Error>

Handle long-running processes according to mode. If an error occurs, all remaining processes will be ignored automatically. Return a list of (process, Option<status>)

impl State

Operations related to delayed filtering.

pub fn list_delayed_paths( &mut self, process: &Key, ) -> Result<Vec<BString>, Error>

Return a list of delayed paths for process that can then be obtained with fetch_delayed().

A process abiding the protocol will eventually list all previously delayed paths for any invoked command, or signals that it is done with all delayed paths by returning an empty list. It’s up to the caller to validate these assumptions.

Error Handling

Usually if the process sends the “abort” status, we will not use a certain capability again. Here it’s unclear what capability that is and what to do, so we leave the process running and do nothing else (just like git).

pub fn fetch_delayed( &mut self, process: &Key, path: &BStr, operation: Operation, ) -> Result<impl Read + '_, Error>

Given a process and a path (as previously returned by list_delayed_paths()), return a reader to stream the filtered result. Note that operation must match the original operation that produced the delayed result or the long-running process might not know the path, depending on its implementation.

impl State

Initialization

pub fn new(context: Context) -> Self

Create a new instance using context to inform launched processes about their environment.

Trait Implementations

impl Clone for State

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Default for State

fn default() -> State

Returns the “default value” for a type.