pinger

README

pinger

Pinger is a Go package used to ping multiple IPv4 peers at an interval, with the ability to register callback functions to be called upon a successful ping or a timeout.

Example

Ping 192.168.1.1, 8.8.8.8 and 4.4.4.4 every second, with a timeout of five seconds. Each time a successful ping occurs (i.e. an ICMP echo reply is received which matches an ICMP echo request that was sent by the Pinger), good is incremented. Each time a timeout occurs (i.e. a matching ICMP echo reply is not received within the timeout period), bad is incremented.

This example exits after ten seconds, or an error occurs during the pinging process, whichever happens first.

package main

import (
	"log"
	"net"
	"time"

	"github.com/jhwbarlow/pinger"
)

func main() {
	var good, bad int

	incGood := func(_ net.IP, _ int) {
		good++
		log.Printf("good: %d", good)
	}

	incBad := func(_ net.IP, _ int) {
		bad++
		log.Printf("bad: %d", bad)
	}

	pinger, err := pinger.New(1*time.Second, 5*time.Second, []byte("hello-world-ping"))
	if err != nil {
		log.Fatalf("Pinger construction error: %v", err)
	}
	pinger.WithSuccessHandler(incGood).WithTimeoutHandler(incBad)

	if err := pinger.Init(); err != nil {
		log.Fatalf("Pinger init error: %v", err)
	}

	pinger.AddPeer("8.8.8.8")
	pinger.AddPeer("4.4.4.4")
	pinger.AddPeer("192.168.1.1")

	done := make(chan struct{})
	errChan := pinger.Run(done)

	select {
	case <-time.Tick(10 * time.Second):
		close(done)
	case err := <-errChan:
		log.Fatalf("Run error: %v", err)
	}
}

Documentation

Overview

Package pinger implements a Pinger type, used to ping multiple IPv4 peers at an interval, with the ability to register callback functions to be called upon a successful ping or a timeout.

Example

package main

import (
	"log"
	"net"
	"time"

	"github.com/jhwbarlow/pinger"
)

func main() {
	var good, bad int

	incGood := func(_ net.IP, _ int) {
		good++
		log.Printf("good: %d", good)
	}

	incBad := func(_ net.IP, _ int) {
		bad++
		log.Printf("bad: %d", bad)
	}

	pinger, err := pinger.New(1*time.Second, 5*time.Second, []byte("hello-world-ping"))
	if err != nil {
		log.Fatalf("Pinger construction error: %v", err)
	}
	pinger.WithSuccessHandler(incGood).WithTimeoutHandler(incBad)

	if err := pinger.Init(); err != nil {
		log.Fatalf("Pinger init error: %v", err)
	}

	pinger.AddPeer("8.8.8.8")
	pinger.AddPeer("4.4.4.4")
	pinger.AddPeer("192.168.1.1")

	done := make(chan struct{})
	errChan := pinger.Run(done)

	select {
	case <-time.Tick(10 * time.Second):
		close(done)
	case err := <-errChan:
		log.Fatalf("Run error: %v", err)
	}
}

Index

• type HandlerFunc
• type Pinger
  • func New(interval, timeout time.Duration, data []byte) (*Pinger, error)
  • func (p *Pinger) AddPeer(peer string) error
  • func (p *Pinger) Init() error
  • func (p *Pinger) RemovePeer(peer string)
  • func (p *Pinger) Run(done <-chan struct{}) <-chan error
  • func (p *Pinger) WithSpuriousHandler(spuriousHandler SpuriousHandlerFunc) *Pinger
  • func (p *Pinger) WithSuccessHandler(successHandler HandlerFunc) *Pinger
  • func (p *Pinger) WithTimeoutHandler(timeoutHandler HandlerFunc) *Pinger
• type SpuriousHandlerFunc

Examples

• Package

Types

type HandlerFunc

type HandlerFunc func(peerIP net.IP, seq int)

HandlerFunc is a callback function called when a ping reply is received or a timeout occurs.

type Pinger

type Pinger struct {
	Interval, Timeout              time.Duration
	SuccessHandler, TimeoutHandler HandlerFunc
	SpuriousHandler                SpuriousHandlerFunc
	Data                           []byte
	// contains filtered or unexported fields
}

Pinger repeatedly pings peers at a time given by Interval with a timeout given by Timeout. The data to send in each ICMP packet is specified in Data. Optional callback functions can be provided in SuccessHandler and TimeoutHandler. These functions are executed synchronously, so users of Pinger should start their own goroutines in these callback functions if required.

func New

func New(interval, timeout time.Duration, data []byte) (*Pinger, error)

New constructs a new Pinger. It does not initialise resources such as network connections. For that, Init must be called subsequently.

func (*Pinger) AddPeer

func (p *Pinger) AddPeer(peer string) error

AddPeer adds a peer to the Pinger. When the next interval time arrives, the peer will be pinged. Peer in IPv4 dotted-decimal notation.

func (*Pinger) Init

func (p *Pinger) Init() error

Init initialises a newly constructed Pinger, initialising resources such as network connections. It does not start pinging. For that, Run must be called subsequently.

func (*Pinger) RemovePeer

func (p *Pinger) RemovePeer(peer string)

RemovePeer removes a peer from the Pinger, such that it will no longer be pinged. Peer in IPv4 dotted-decimal notation.

func (*Pinger) Run

func (p *Pinger) Run(done <-chan struct{}) <-chan error

Run starts the Pinger. Any peers added will start to be pinged after the first interval time and every interval after that, until the peer is removed, or the done channel is closed. Once done is closed, the Pinger instance cannot be reused.

func (*Pinger) WithSpuriousHandler

func (p *Pinger) WithSpuriousHandler(spuriousHandler SpuriousHandlerFunc) *Pinger

WithSpuriousHandler installs the provided SpuriousHandlerFunc as the handler for spuriously received ICMP messages and late ping responses.

func (*Pinger) WithSuccessHandler

func (p *Pinger) WithSuccessHandler(successHandler HandlerFunc) *Pinger

WithSuccessHandler installs the provided HandlerFunc as the handler for sucessfully responded ping requests.

func (*Pinger) WithTimeoutHandler

func (p *Pinger) WithTimeoutHandler(timeoutHandler HandlerFunc) *Pinger

WithTimeoutHandler installs the provided HandlerFunc as the handler for timed-out ping requests.

type SpuriousHandlerFunc

type SpuriousHandlerFunc func(peerIP net.IP)

SpuriousHandlerFunc is a callback function called when a spurious or late ICMP message is received.