pinger

README

go-parallel-pinger

A easy and thread-safe way to send ping in Go.

package main

import (
	"context"
	"log"
	"net"
	"time"

	"github.com/macrat/go-parallel-pinger"
)

func Example() {
	target, _ := net.ResolveIPAddr("ip", "127.0.0.1")

	// 1. make Pinger for IPv4 (or, you can use NewIPv6)
	p := pinger.NewIPv4()

	// 2. make context for handle timeout or cancel
	ctx, cancel := context.WithTimeout(context.Background(), 1*time.Second)
	defer cancel()

	// 3. start Pinger for send/receive ICMP packet before send ping
	if err := p.Start(ctx); err != nil {
		log.Fatalf("failed to start pinger: %s", err)
	}

	// 4. send ping for the target, and wait until receive all reply or context canceled
	result, err := p.Ping(ctx, target, 4, 100*time.Millisecond)
	if err != nil {
		log.Fatalf("failed to send ping: %s", err)
	}

	// 5. check the result
	log.Printf("sent %d packets and received %d packets", result.Sent, result.Recv)
	log.Printf("RTT: min=%s / avg=%s / max=%s", result.MinRTT, result.AvgRTT, result.MaxRTT)

Documentation

Overview

go-parallel-pinger is a easy and thread-safe way to send ping in Go.

Example

target, _ := net.ResolveIPAddr("ip", "127.0.0.1")

// 1. make Pinger for IPv4
p := pinger.NewIPv4()

// 2. make context for handle timeout or cancel
ctx, cancel := context.WithTimeout(context.Background(), 1*time.Second)
defer cancel()

// 3. start Pinger for send/receive ICMP packet before send ping
if err := p.Start(ctx); err != nil {
	log.Fatalf("failed to start pinger: %s", err)
}

// 4. send ping for the target, and wait until receive all reply or context canceled
result, err := p.Ping(ctx, target, 4, 100*time.Millisecond)
if err != nil {
	log.Fatalf("failed to send ping: %s", err)
}

// 5. check the result
log.Printf("sent %d packets and received %d packets", result.Sent, result.Recv)
log.Printf("RTT: min=%s / avg=%s / max=%s", result.MinRTT, result.AvgRTT, result.MaxRTT)

Example (Parallel)

p := pinger.NewIPv4()

ctx, cancel := context.WithTimeout(context.Background(), 1*time.Second)
defer cancel()

if err := p.Start(ctx); err != nil {
	log.Fatalf("failed to start pinger: %s", err)
}

wg := &sync.WaitGroup{}

for _, target := range []string{"127.0.0.1", "127.0.0.2", "127.0.0.3", "127.0.0.4", "127.0.0.5"} {
	wg.Add(1)

	go func(target string) {
		t, _ := net.ResolveIPAddr("ip", target)
		result, err := p.Ping(ctx, t, 4, 100*time.Millisecond)

		if err != nil {
			log.Printf("%s: failed to send ping: %s", target, err)
		} else {
			log.Printf("%s: min=%s / avg=%s / max=%s", target, result.MinRTT, result.AvgRTT, result.MaxRTT)
		}

		wg.Done()
	}(target)
}

wg.Wait()

Index

• Constants
• Variables
• type Pinger
  • func NewIPv4() *Pinger
  • func NewIPv6() *Pinger
  • func (p *Pinger) Ping(ctx context.Context, target *net.IPAddr, count int, interval time.Duration) (Result, error)
  • func (p *Pinger) Privileged() bool
  • func (p *Pinger) Protocol() string
  • func (p *Pinger) SetPrivileged(b bool) error
  • func (p *Pinger) Start(ctx context.Context) error
  • func (p *Pinger) Started() bool
  • func (p *Pinger) Stop() error
• type Result

Examples

• Package
• Package (Parallel)

Constants

const (
	// DEFAULT_PRIVILEGED is the default value of Pinger.Privileged/Pinger.SetPrivileged.
	DEFAULT_PRIVILEGED = runtime.GOOS == "windows"
)

Variables

var (
	// ErrAlreadyStarted is the error if the pinger is already started.
	ErrAlreadyStarted = errors.New("Pinger is already started")

	// ErrNotStarted is the error if call Pinger.Ping before start the pinger.
	ErrNotStarted = errors.New("Pinger is not started yet")
)

Types

type Pinger

type Pinger struct {
	// contains filtered or unexported fields
}

Pinger is the ping sender and receiver.

func NewIPv4

func NewIPv4() *Pinger

NewIPv4 makes new Pinger for IPv4 protocol.

func NewIPv6

func NewIPv6() *Pinger

NewIPv6 makes new Pinger for IPv6 protocol.

func (*Pinger) Ping

func (p *Pinger) Ping(ctx context.Context, target *net.IPAddr, count int, interval time.Duration) (Result, error)

Ping sends ping to target, and wait for reply.

It returns ErrNotStarted if call this before call Start.

func (*Pinger) Privileged

func (p *Pinger) Privileged() bool

Privileged returns current privileged mode.

Please seealso SetPrivileged.

func (*Pinger) Protocol

func (p *Pinger) Protocol() string

Protocol returns "v4" if it's a Pinger for IPv4, otherwise returns "v6".

func (*Pinger) SetPrivileged

func (p *Pinger) SetPrivileged(b bool) error

SetPrivileged sets privileged mode.

It should set as true if runs on Windows, and the default value in Windows is true.

In Linux or Darwin(mac os), you have to run as root if use privileged mode. and the default is false.

You can't call it after call Start method. It will returns ErrAlreadyStarted if call it after Pinger started.

func (*Pinger) Start

func (p *Pinger) Start(ctx context.Context) error

Start is starts this Pinger for send and receive ping in new goroutine.

It returns ErrAlreadyStarted if the Pinger already started.

func (*Pinger) Started

func (p *Pinger) Started() bool

Started returns true if this Pinger is started, otherwise returns false.

func (*Pinger) Stop

func (p *Pinger) Stop() error

Stop will stop this Pinger and block for stopped it completely.

It returns ErrNotStarted if call this before call Start.

type Result

type Result struct {
	Target *net.IPAddr
	Sent   int
	Recv   int
	Loss   int
	RTTs   []time.Duration
	MinRTT time.Duration
	MaxRTT time.Duration
	AvgRTT time.Duration
}

Result is a result of Ping.