System.Signal

Signal raising and handling.

NOTE that there are important differences between
what can be done out-of-box in Windows and POSIX based
operating systems. This module tries to honor both
by putting things only available in POSIX environments
into appropriately named namespaces or data types.

Definitions

data PosixSignal : Type

Totality: total
Visibility: public export
Constructors:

SigHUP : PosixSignal

  Hangup (i.e. controlling terminal closed)

SigQUIT : PosixSignal

  Quit

SigTRAP : PosixSignal

  Trap (as used by debuggers)

SigUser1 : PosixSignal

SigUser2 : PosixSignal

Hint: 

Eq PosixSignal

data Signal : Type

Totality: total
Visibility: public export
Constructors:

SigINT : Signal

  Interrupt (e.g. ctrl+c pressed)

SigABRT : Signal

  Abnormal termination

SigILL : Signal

  Ill-formed instruction

SigSEGV : Signal

  Segmentation fault

SigFPE : Signal

  Floating-point error

SigPosix : PosixSignal -> Signal

  Signals only available on POSIX operating systems

Hint: 

Eq Signal

signalCode : Signal -> Int

  Converts a `Signal` to its integer representation to be used
  in FFI calls.

Totality: total
Visibility: export

toSignal : Int -> Maybe Signal

  Tries to convert an integer to the corresponding `Signal`.

Totality: total
Visibility: export

data SignalError : Type

  An Error represented by a code. See
  relevant `errno` documentation.
  https://man7.org/linux/man-pages/man3/errno.3.html

Totality: total
Visibility: public export
Constructor: 

Error : Int -> SignalError

ignoreSignal : HasIO io => Signal -> io (Either SignalError ())

  Ignore the given signal.
  Be careful doing this, as most signals have useful
  default behavior -- you might want to set the signal
  to its default behavior instead with `defaultSignal`.

Totality: total
Visibility: export

defaultSignal : HasIO io => Signal -> io (Either SignalError ())

  Use the default handler for the given signal.
  You can use this function to unset custom
  handling of a signal.

Totality: total
Visibility: export

collectSignal : HasIO io => Signal -> io (Either SignalError ())

  Collect the given signal.
  
  This replaces the existing handling of the given signal
  and instead results in Idris collecting occurrences of
  the signal until you call `handleNextCollectedSignal`.
  
  First, call `collectSignal` for any number of signals.
  Then, call `handleNextCollectedSignal` in each main loop
  of your program to retrieve (and mark as handled) the next
  signal that was collected, if any.
  
  Signals are not queued, so the return order of signals is
  not specified and signals may be deduplicated.

Totality: total
Visibility: export

handleNextCollectedSignal : HasIO io => io (Maybe Signal)

  Get next collected signal under the pretense of handling it.
  
  Calling this "marks" the signal as handled so the next time
  this function is called you will retrieve the next unhandled
  signal instead of the same signal again.
  
  You get back Nothing if there are no pending signals.

Totality: total
Visibility: export

handleManyCollectedSignals : HasIO io => Fuel -> io (List Signal)

  Get many collected signals and mark them as handled.
  
  Use `forever` as your fuel if you don't want or need to
  retain totality. Alternatively, pick a max number to
  retrieve and use `limit/1` as your fuel.

Totality: total
Visibility: export

raiseSignal : HasIO io => Signal -> io (Either SignalError ())

  Send a signal to the current process.

Totality: total
Visibility: export

sendSignal : HasIO io => Signal -> Int -> io (Either SignalError ())

  Send a signal to a POSIX process using a PID to identify the process.

Totality: total
Visibility: export