Trait CommandWrapper

pub trait CommandWrapper:
    Debug
    + Send
    + Sync {
    // Provided methods
    fn extend(&mut self, _other: Box<dyn CommandWrapper>) { ... }
    fn pre_spawn(
        &mut self,
        _command: &mut Command,
        _core: &CommandWrap,
    ) -> Result<()> { ... }
    fn post_spawn(
        &mut self,
        _command: &mut Command,
        _child: &mut Child,
        _core: &CommandWrap,
    ) -> Result<()> { ... }
    fn wrap_child(
        &mut self,
        child: Box<dyn ChildWrapper>,
        _core: &CommandWrap,
    ) -> Result<Box<dyn ChildWrapper>> { ... }
}

Available on crate feature std only.

A trait for adding functionality to a Command.

This trait provides extension or hook points into the lifecycle of a Command. See the crate-level doc for an overview.

All methods are optional, so a minimal impl may be:

#[derive(Debug)]
pub struct YourWrapper;
impl CommandWrapper for YourWrapper {}

Provided Methods

fn extend(&mut self, _other: Box<dyn CommandWrapper>)

Called on a first instance if a second of the same type is added.

Only one of a wrapper type can exist within a Wrap at a time. The default behaviour is to silently discard any further invocations. However in some cases it might be useful to merge the two. This method is called on the instance already stored within the Wrap, with the new instance.

The other argument is guaranteed by process-wrap to be of the same type as self, so you can downcast it with .unwrap() and not panic. Note that it is possible for other code to use this trait and not guarantee this, so you should still panic if downcasting fails, instead of using unchecked downcasting and unleashing UB.

Default impl: no-op.

fn pre_spawn( &mut self, _command: &mut Command, _core: &CommandWrap, ) -> Result<()>

Called before the command is spawned, to mutate it as needed.

This is where to modify the command before it is spawned. It also gives mutable access to the wrapper instance, so state can be stored if needed. The core reference gives access to data from other wrappers; for example, that’s how CreationFlags on Windows works along with JobObject.

Defaut impl: no-op.

fn post_spawn( &mut self, _command: &mut Command, _child: &mut Child, _core: &CommandWrap, ) -> Result<()>

Called after spawn, but before the child is wrapped.

The core reference gives access to data from other wrappers; for example, that’s how CreationFlags on Windows works along with JobObject.

Default: no-op.

fn wrap_child( &mut self, child: Box<dyn ChildWrapper>, _core: &CommandWrap, ) -> Result<Box<dyn ChildWrapper>>

Called to wrap a child into this command wrapper’s child wrapper.

If the wrapper needs to override the methods on Child, then it should create an instance of its own type implementing ChildWrapper and return it here. Child wraps are in order: you may end up with a Foo(Bar(Child)) or a Bar(Foo(Child)) depending on if .wrap(Foo).wrap(Bar) or .wrap(Bar).wrap(Foo) was called.

The core reference gives access to data from other wrappers; for example, that’s how CreationFlags on Windows works along with JobObject.

Default: no-op (ie, returns the child unchanged).

Implementors

impl CommandWrapper for ProcessGroup

Available on Unix and crate feature process-group only.

impl CommandWrapper for ProcessSession

Available on Unix and crate feature process-session only.

impl CommandWrapper for ResetSigmask

Available on Unix and crate feature reset-sigmask only.