Struct addy::SignalHandle

pub struct SignalHandle { /* fields omitted */ }

This is the struct returned from an addy::mediate(Signal) call. It allows the caller to add, remove, and clear callbacks to the provided interrupt handler. Adding closures prevents the default bevaior (if any).

You can also set the interrupt to the default behaviour, or to be ignored by the process. If you set a signal to be ignored or back to the defaults you can call .resume() to to have it handle your callbacks again.

Dropping it does not stop the signal handler. You must call .release() to have Addy stop handling this interrupt and free the associated resources. Conversely, you don't have to keep a handle to this around once you've set it up.

If you register callbacks for an interrupt, you must call .enable() to have them run. If you call .release() on a SignalHandler you must call .enable() again (after re-registering new callbacks).

Example

use addy::{Signal, SIGWINCH};

fn my_func(signal: Signal) {
	/* Does a thing */
}

fn main() -> Result<(), addy::Error> {
	addy::mediate(SIGWINCH)
			.register("print", |_signal| { println!("Screen Resized!"); })?
			.register("my_func", my_func)?
			.enable()?;

	//-- Later --//

	// Ignore the incoming signal
	addy::mediate(SIGWINCH).ignore()?;

	//-- Later Still --//

	// Swap out one of the callbacks and re-enable capturing the interrupt
	addy::mediate(SIGWINCH)
			.remove("print")?
			.register("print", |_signal| { println!("New Output!"); })?
			.enable()?;

	Ok(())
}

Methods

impl SignalHandle

pub fn register<'a, A, F>(
    &'a mut self,
    name: A,
    cb: F
) -> Result<&'a mut SignalHandle, Error> where
    A: AsRef<str>,
    F: Fn(Signal) + Send + 'static, 

Registers a callback with the interrupt handler for the associated Signal. If you call register with the same name it will replace the previous callback.

Example

use addy::{Signal, SIGWINCH};

fn my_func(signal: Signal) {
	/* Does a thing */
}

fn main() -> Result<(), addy::Error> {
	addy::mediate(SIGWINCH)
			.register("print", |_signal| { println!("Screen Resized!"); })?
			.register("my_func", my_func)?
			.enable()?;

	Ok(())
}

pub fn remove<'a, A>(
    &'a mut self,
    name: A
) -> Result<&'a mut SignalHandle, Error> where
    A: AsRef<str>, 

Removes a named callback from the associated Signal. If no callback with that name exists, it does nothing.

Example

use addy::{Signal, SIGWINCH};

fn my_func(signal: Signal) {
	/* Does a thing */
}

fn main() -> Result<(), addy::Error> {
	addy::mediate(SIGWINCH)
			.register("print", |_signal| { println!("Screen Resized!"); })?
			.register("my_func", my_func)?
			.enable()?;

	//-- Later --//

	// Stop calling "print" when the process receives a SIGWINCH signal
	addy::mediate(SIGWINCH).remove("print")?;

	Ok(())
}

pub fn clear<'a>(&'a mut self) -> Result<&'a mut SignalHandle, Error>

Removes a all callbacks from the associated Signal. Functionally similar to calling .ignore() except you don't need to call .enable() if you add new callbacks later.

Example

use addy::{Signal, SIGWINCH};

fn my_func(signal: Signal) {
	/* Does a thing */
}

fn main() -> Result<(), addy::Error> {
	addy::mediate(SIGWINCH)
			.register("print", |_signal| { println!("Screen Resized!"); })?
			.register("my_func", my_func)?
			.enable()?;

	//-- Later --//

	// Capture the signal, but stop calling anything
	addy::mediate(SIGWINCH)
			.clear()?
			.register("solo_callback", |_signal| { println!("ALONE!"); })?;

	Ok(())
}

pub fn release<'a>(&'a mut self) -> Result<&'a mut SignalHandle, Error>

Removes a all callbacks from the associated Signal and resets the interrupt handler to the default behavior. Funcationally the same as calling .clear() and .default().

You will need to call .enable() again after re-registering callbacks.

Example

use addy::SIGWINCH;

fn main() -> Result<(), addy::Error> {
	addy::mediate(SIGWINCH)
			.register("print", |_signal| { println!("Screen Resized!"); })?
			.enable()?;

	//-- Later --//

	// Stop capturing the signal
	addy::mediate(SIGWINCH).release()?;
  
	//-- Later Still --//

	// Start catpuring again
	addy::mediate(SIGWINCH)
			.register("new", |_signal| { println!("New callback!"); })?
			.enable()?;

	Ok(())
}

pub fn ignore<'a>(&'a mut self) -> Result<&'a mut SignalHandle, Error>

Tells the process to ignore this interrupt. Keeps all your callbacks. Calling .resume() will re-enable them.

Example

use addy::SIGWINCH;

fn main() -> Result<(), addy::Error> {
	addy::mediate(SIGWINCH)
			.register("print", |_signal| { println!("Screen Resized!"); })?
			.enable()?;

	//-- Later --//

	// Ignore the signal
	addy::mediate(SIGWINCH).ignore()?;

	//-- Later Still --//

	// Start catpuring again
	addy::mediate(SIGWINCH).resume()?;

	Ok(())
}

pub fn default<'a>(&'a mut self) -> Result<&'a mut SignalHandle, Error>

Restore the interrupt handler to the system default. Not all interrupts have a default, and some interrupts default is to be ignored. Keeps all your callbacks. Calling .resume() will re-enable them.

Example

use addy::SIGINT;

fn main() -> Result<(), addy::Error> {
	addy::mediate(SIGINT)
			.register("print", |_signal| { println!("Interrupted!"); })?
			.enable()?;

	//-- Later --//

	// Set the signal to its default
	addy::mediate(SIGINT).default()?;

	//-- Later Still --//

	// Start catpuring again
	addy::mediate(SIGINT).resume()?;

	Ok(())
}

pub fn resume<'a>(&'a mut self) -> Result<&'a mut SignalHandle, Error>

Resumes capturing the interrupt and calling any associated callbacks. Most often used after a call to .ignore() and .default().

Alias of .enable()

Example

use addy::SIGINT;

fn main() -> Result<(), addy::Error> {
	addy::mediate(SIGINT)
			.register("print", |_signal| { println!("Interrupted!"); })?
			.enable()?;

	//-- Later --//

	// Set the signal to its default
	addy::mediate(SIGINT).default()?;

	//-- Later Still --//

	// Start catpuring and printing "Interrupted!" again
	addy::mediate(SIGINT).resume()?;

	Ok(())
}

pub fn enable<'a>(&'a mut self) -> Result<&'a mut SignalHandle, Error>

Begins capturing the interrupt and calling any associated callbacks. Most often used after a calls .register()

Alias of .resume()

Example

use addy::SIGINT;

fn main() -> Result<(), addy::Error> {
	addy::mediate(SIGINT)
			.register("print", |_signal| { println!("Interrupted!"); })?
			.enable()?;
	Ok(())
}

Trait Implementations

impl Debug for SignalHandle

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

Formats the value using the given formatter.