## HiPi::Interrupt::Handler

This module provides access to interrupt handling and inter thread communication in your main thread.

The main interrupt module, HiPi::Interrupt, must be loaded at the beginning of your script. You may then either create your own class deriving from HiPi::Interrupt::Handler to handle interrupts or you can use an instance of the class directly providing one or more callback code references.

Working examples are provided in:

- Derived Class Example
- Callback Example
- Mixed Handlers Example

You choose to deal with notifications either by registering callbacks with an instance of HiPi::Interrupt::Handler or you may create your own class deriving from HiPi::Interrupt::Handler and override its methods.

## Constructor

### my $handler = HiPi::Interrupt::Class->new();

## Methods

### $handler->add_pin($pin);
$handler->add_pin($pinnumber, $pinclass);

Method add_pin takes either a pin object inheriting from class HiPi::Pin or a GPIO pin number and a pinclass defining how the pin is managed ( gpio for sysfs HiPi::Device::GPIO pins, bcmd for HiPi::BCM2835 pins and wire for HiPi::Wiring pins.

The pin will be polled for interrupts. It is assumed that all of the necessary settings will have been applied to the pin prior to a call to $handler->add_pin.

### $handler->remove_pin($pin);
$handler->remove_pin($pinnumber);

Removes the pin from interrupt polling.

### $handler->stop;

Stops and exits the $handler poll loop. Call this to close your application.

### $handler->poll;

Call this to begin polling for pin interrupts. The method will not return until your code calls $handler->stop. After calling $handler->poll, your code execution continues in the main application thread by calls to methods in your custon HiPi::Interrupt::Handler class or through callbacks you have registered with your $handler instance.

### $handler->register_callback( $cbname, $coderef );

Rather than create your own class derived from HiPi::Interrupt::Handler, you can create an instance of HiPi::Interrupt::Handler directly and register callback subroutines to receive notifications. The code reference specified in $coderef will be called with the same parameters described in the Notification Methods below for the relevant $cbname. Possible values for $cbname are
start, continue, interrupt, error, add, remove, stop.

### $handler->get_timestamp();

A convenience method that returns milliseconds since the Unix epoch. It is a simple wrapper around Time::HiRes::gettimeofday()

## Overridable Notification Methods

### on_start ( $handler )

on_start is called once immediately after $handler->poll is called.

  $handler Your HiPi::Interrupt::Handler instance.

### on_add ( $handler, $message )

Called with the result of a call to $handler->add_pin

  $handler Your HiPi::Interrupt::Handler instance.

  $message An instance of HiPi::Interrupt::Message

### on_remove ( $handler, $message )

Called with the result of a call to $handler->remove_pin

  $handler Your HiPi::Interrupt::Handler instance.

  $message An instance of HiPi::Interrupt::Message

### on_interrupt ( $handler, $message )

Called with the result polling for interrupts on the monitored pins.

  $handler Your HiPi::Interrupt::Handler instance.

  $message An instance of HiPi::Interrupt::Message

### on_continue ( $handler, $actions )

Called periodically so that you may run code when no interrupts are occuring. Can be treated as a 'heartbeat' method. You can use $handler->get_timestamp to return milliseconds since the Unix epoch and store the value if you wish to carry out actions at a specific time offset.

  $handler Your HiPi::Interrupt::Handler instance.

  $actions The number of interrupts handled since the last call to on_continue.

### on_error ( $handler, $message )

Called when an error occurs that is not specific to a particular $handler call.

  $handler Your HiPi::Interrupt::Handler instance.

  $message An instance of HiPi::Interrupt::Message

### on_stop ( $handler, $message )

Called with the result of a call to $handler->stop

  $handler Your HiPi::Interrupt::Handler instance.

  $message An instance of HiPi::Interrupt::Message

HiPi Modules Copyright © 2013 - 2016 Mark Dootson