goping

Documentation

Index

• Constants
• Variables
• func SetCtl(c Controller)
• type Controller
  • func Ctl() Controller
• type EchoReply
• type Messenger
• type OSPinger
• type Pinger
• type Poolable
• type Pooler
  • func Pool() Pooler
• type Requester
• type Responder
• type Summary
• type Target

Constants

const (
	GET = iota
	PUT
	DEL
)

const (
	//IPProtoICMP represents an ICMP Protocol to be used in a Request object
	IPProtoICMP = iota
	//IPProtoUDP represents an UDP Protocol to be used in a Request object
	IPProtoUDP
	//IPProtoTCP represents a TCP Protocol to be used in a Request object
	IPProtoTCP
	//IPV4 represent ipv4 in a Request object
	IPV4
	//IPV6 to be used in a Request object
	IPV6
)

Variables

var (
	ErrNoRegisteredOSPinger = errors.New("No registered OSPinger")
	ErrNoSuchOperation      = errors.New("No such operation. only GET PUT or DEL are accepted")
	ErrSeqSlotIsOccupied    = errors.New("Error while trying to use Sequence slot to wait for a response")
	ErrResponseTimeout      = errors.New("Response timeout")
	ErrNoResponderChannel   = errors.New("Request has no Responder Channel to receive a reply")
)

var (
	ErrTakingTooLongTime = errors.New("Taking too long time while waiting for a response")
)

Functions

func SetCtl

func SetCtl(c Controller)

To change the builtin implementation of PingController.

Types

type Controller

type Controller interface {
	/*
		Called when requesting a ping
			Choose the right OsPinger to use
			Set the WhenSent attribute returned by the OSPinger into the Request
			Configure a timer to timeout the response
			Async  select a response or times out. Send the response to the request response channel
			Should return before receive and response
	*/
	Ping(Requester) error

	/*
		Called by the OSPinger when a message is received
			Set the RTT of the Response Object
			Send the response to the async select.
			Should return ASAP
	*/
	Pong(Responder) error

	/*
		Allows third parties to implement their own OSPinger
	*/
	RegisterOSPinger(ver uint8, prot uint8, goos string, osPinger OSPinger) (OSPinger, error)
	/*
		Allows third parties to implement their own OSPinger
	*/
	UnRegisterOSPinger(ver uint8, prot uint8, goos string) (OSPinger, error)
	/*
		Get the registered OSPinger
	*/
	OSPinger(ver uint8, prot uint8, goos string) (OSPinger, error)
}

PingController coordinates the ping requests and responses

func Ctl

func Ctl() Controller

Return the Ping Controller of this package

type EchoReply

type EchoReply interface {
	Target() Target
	Cycle() uint
	Peer() net.IPAddr
	Bytes() uint8
	Seq() uint16
	TTL() uint8
	TOS() uint8
	Rtt() float64
	Err() error
}

type Messenger

type Messenger interface {

	//The Sequence  number to be sent or received
	Sequence() int

	//The ICMP type to be sent or received
	ICMPType() byte

	//The ICMP Code  to be sent or received
	ICMPCode() byte

	//The Data Size to be sent or received
	Size() int

	//The TTL value of the received ip header
	TTL() int

	//The TOS value of the received ip packet
	TOS() int

	//Set the TOS field to be sent or received
	SetTOS(int)

	//Set the TTL field to be sent or received
	SetTTL(int)

	//Set the Packet Size field to be sent or received
	SetSize(int)

	//Set the ICMPType to be sent or received
	SetICMPType(byte)

	//Set the ICMPCode to be sent or received
	SetICMPCode(byte)

	SetSequence(int)
}

Messenger Represents an ICMP Message and an IP Header to be sent or received. It is a poolable object, so the caller function should call its Release method to return it to the pool as soon as possible. This will lower the pressure on the garbage collector, as i learned reading blogs and the guys that are making the cockroachdb (sync.Pool)

To get a Request Message r:=goping.Pool().NewRequest()

To get a Response Message r:=goping.Pool().NewResponse()

type OSPinger

type OSPinger interface {

	//Called by the Controller when a ping is needed
	Ping(Requester) time.Time
}

OSPinger Represents an Operational System implementation of the ping command.

Once one implementation is created, the Controller.RegisterOSPinger should be called to register the OSPinger.

The registration process has the following procedures:

The Controller references itself to OsPinger.Init(Controller)
The Controller configure an internal map with  using the sent parameters

type Pinger

type Pinger interface {
	AddTarget(target string, userData map[string]string) error
	PingAsync() (<-chan EchoReply, <-chan Summary)
	Ping() []Summary

	IPProto() uint8               //IPProtoICMP, IPProtoUDP or IPProtoTCP. Default IPProtoICMP
	IPVersion() uint8             //IPV4 or IPV6 . Default IPV4
	Bytes() uint8                 //The number of bytes to send as the payload. Default 56
	TTL() uint8                   //The time to live value of the ip header. Default 64
	TOS() uint8                   //The DSCP value of the ip header. Default 0
	Timeout() time.Duration       //The maximum duration to wait for an echo reply. Default 3 sec
	Cycles() uint                 //The number of cycles to execute. Default 1
	CycleInterval() time.Duration //The minimum interval between two cycles. Default: 1 sec

	SetIPProto(uint8) error   //Validate IPProto
	SetIPVersion(uint8) error //Validate IPVersion
	SetBytes(uint8)
	SetTTL(uint8)
	SetTOS(uint8)
	SetTimeout(time.Duration)
	SetCycles(uint)
	SetCycleInterval(time.Duration)
}

type Poolable

type Poolable interface {

	//Sets the inner Pool
	SetPool(p Pooler)

	//Calls the method Pool.Release from the inner Pool
	Release()
}

Poolable represents an object that is generated by the Pool.

type Pooler

type Pooler interface {

	//Retrieves a Request object from the sync.Pool
	//Calls the SetPool method passing itself reference
	//Should set the Controller object using the method goping.Controller()
	NewRequest() Requester

	//Retrieves a Response object from the Pool
	//Calls the SetPool method passing itself reference
	//Should set the Controller object using the method goping.Controller()
	NewResponse() Responder

	//Releases a Requester object. It is called internally by the Requester.Release() method
	ReleaseRequest(Requester)

	//Releases a Responder object. It is called internally by the Responder.Release() method
	ReleaseResponse(Responder)
}

Pooler Represents a pool of objects.

Every object retrieved from the pool has a Release method that should be called after its use. This practice is mandatory and serves the purpouse of return the object back to the pool for reuse. This will allow the garbage collector to work with less pressure and avoid memory leakings inside goroutines

func Pool

func Pool() Pooler

Pool returns the singleton Pooler of this package

type Requester

type Requester interface {

	//The Request object is a Message Object
	Messenger

	Poolable

	//The target address
	Target() Target

	ResponderChan() chan<- Responder

	//Returns the IPVersion configured for this request
	IPVersion() uint8

	//Returns the IPProto configured for this request
	IPProto() uint8

	//The maximum time to wait for an answer
	//Should be implemented inside the Controller
	Timeout() time.Duration

	//Returns the Time when the Request was sent over the socket
	WhenSent() time.Time

	//Set the IP Version Constant:
	//IPVersion_4 or IPVersion_6
	SetIPVersion(uint8)

	//Set the Protocol Constant:
	//IPProto_ICMP, IPProto_UDP or IPProto_TCP
	//Actually only the IPProto_ICMP is being developed
	SetIPProto(uint8)

	//Set the maximum duration to wait for a response
	//The Controller shoul implement this timer
	SetTimeout(time.Duration)

	//Set the time when the ping was sent over the socket
	//This should be called by the Controller using the very value
	//that was returned by the function OsPinger.Ping(Request) time.Time
	SetWhenSent(time.Time)

	SetTarget(Target)

	SetResponderChan(chan<- Responder)
}

Requester represents an ICMP Echo Request message with a target ip A request is created using the goping.Pool().NewRequest() method The caller should fill the attributes like:

from Message Interface:
SetPeer(net.IP) //Set the peer node to  be sent or received
SetTOS(int)     //Set the TOS field to be sent or received
SetTTL(int)     //Set the TTL field to be sent or received
SetSize(int)    //Set the Packet Size field to be sent or received

from Request Interface:
SetIPVersion(int8)
SetIPProto(int8)
SetTimeout(time.Duration)

Once the attribute was set, the Request.Ping() method should be called to execute the ping. This will call the method Controller.Ping(). The implementation should store the Response channel returned by the Controller to be used in the Pong function.

The response is retrieved using the Pong() method. This function will receive a Response from the Response Channel and set the RTT time of it before deliver the Response object back to the caller

type Responder

type Responder interface {

	//Response is a Message Object
	Messenger

	//Responder is a Poolable Object
	Poolable

	Request() Requester

	//The peer node  to be sent or received
	Peer() net.IP

	//The Round Trip Time of the received icmp message
	//Should be NaN if an error occurred
	RTT() float64

	//The error, if any, of the received icmp message
	Error() error

	//The time this response whas received
	WhenRecv() time.Time

	//The  output string like the unix ping command
	//eg: 64 bytes from 200.221.2.45: icmp_seq=2 ttl=53 time=25.291 ms
	fmt.GoStringer

	//Called by OSPinger to set the time this response was received
	SetWhenRecv(time.Time)

	//Set the RTT for this Response
	SetRTT(float64)

	//Set the Error Message
	SetError(error)

	SetRequest(Requester)

	//Set the peer node to  be sent or received
	SetPeer(net.IP)
}

Responder represent an ICMP reply message

This object is originated at the OSPinger and sent right to the Controller.

When a response object is not sent by the OSPinger, the Controller then generates one with a timeout Error.

type Summary

type Summary interface {
	Target() Target
	TotalSent() float64 //The number of ping sents
	TotalRecv() float64 //The number of succesful replies received
	Max() float64       //The maximum rtt
	Min() float64       //The minimum rtt
	Avg() float64       //The average rtt
}

type Target

type Target interface {
	Host() string                //The target hostname, as received at the AddTarget function
	IP() net.IPAddr              //The target IP Address
	UserData() map[string]string //UserData
}