temperrcatcher

README

go-temp-err-catcher

This is a little package to use with your net.Listeners.

Docs: https://godoc.org/github.com/jbenet/go-temp-err-catcher

Get:

go get github.com/jbenet/go-temp-err-catcher

Examples

It is meant to be used with things like net.Lister.Accept:

import (
  tec "github.com/jbenet/go-temp-err-catcher"
)

func listen(listener net.Listener) {
  var c tec.TempErrCatcher

  for {
    conn, err := listener.Accept()
    if err != nil && c.IsTemporary(c) {
      continue
    }
    return conn, err
  }
}

You can make your errors implement Temporary:

type errTemp struct {
  e error
}

func (e errTemp) Temporary() bool {
  return true
}

func (e errTemp) Error() string {
  return e.e.Error()
}

err := errors.New("beep boop")
var c tec.TempErrCatcher
c.IsTemporary(err)              // false
c.IsTemporary(errTemp{err}) // true

Or just use ErrTemp:

err := errors.New("beep boop")
var c tec.TempErrCatcher
c.IsTemporary(err)              // false
c.IsTemporary(tec.ErrTemp{err}) // true

You can also define an IsTemp function to classify errors:

var ErrSkip = errors.New("this should be skipped")
var ErrNotSkip = errors.New("this should not be skipped")

var c tec.TempErrCatcher
c.IsTemp = func(e error) bool {
  return e == ErrSkip
}

c.IsTemporary(ErrSkip) // true
c.IsTemporary(ErrNotSkip) // false
c.IsTemporary(ErrTemp) // false! no longer accepts Temporary()

Documentation

Overview

Package temperrcatcher provides a TempErrCatcher object, which implements simple error-retrying functionality. It is meant to be used with things like net.Lister.Accept:

import (
  tec "github.com/jbenet/go-temp-err-catcher"
)

func listen(listener net.Listener) {
  var c tec.TempErrCatcher

  for {
    conn, err := listener.Accept()
    if err != nil && c.IsTemporary(c) {
      continue
    }
    return conn, err
  }
}

You can make your errors implement `Temporary`:

type errTemp struct {
  e error
}

func (e errTemp) Temporary() bool {
  return true
}

func (e errTemp) Error() string {
  return e.e.Error()
}

err := errors.New("beep boop")
var c tec.TempErrCatcher
c.IsTemporary(err)              // false
c.IsTemporary(errTemp{err}) // true

Or just use `ErrTemp`:

err := errors.New("beep boop")
var c tec.TempErrCatcher
c.IsTemporary(err)              // false
c.IsTemporary(tec.ErrTemp{err}) // true

You can also define an `IsTemp` function to classify errors:

var ErrSkip = errors.New("this should be skipped")
var ErrNotSkip = errors.New("this should not be skipped")

var c tec.TempErrCatcher
c.IsTemp = func(e error) bool {
  return e == ErrSkip
}

c.IsTemporary(ErrSkip) // true
c.IsTemporary(ErrNotSkip) // false
c.IsTemporary(ErrTemp) // false! no longer accepts Temporary()

Package temperrcatcher provides a TempErrCatcher object, which implements simple error-retrying functionality.

Index

• Variables
• func ErrIsTemporary(e error) bool
• type ErrTemporary
  • func (e ErrTemporary) Error() string
  • func (e ErrTemporary) String() string
  • func (e ErrTemporary) Temporary() bool
• type TempErrCatcher
  • func (tec *TempErrCatcher) IsTemporary(e error) bool
  • func (tec *TempErrCatcher) Reset()
• type Temporary

Variables

var InitialDelay = time.Millisecond

InitialDelay governs how long to wait the first time. This is defaulted to time.Millisecond, which makes sense for network listener failures. You may want a much smaller delay. You can configure this package wide, or in each TempErrCatcher

Functions

func ErrIsTemporary

func ErrIsTemporary(e error) bool

ErrIsTemporary returns whether an error is Temporary(), iff it implements the Temporary interface.

Types

type ErrTemporary

type ErrTemporary struct {
	Err error
}

ErrTemporary wraps any error and implements Temporary function.

err := errors.New("beep boop")
var c tec.TempErrCatcher
c.IsTemporary(err)              // false
c.IsTemporary(tec.ErrTemp{err}) // true

func (ErrTemporary) Error

func (e ErrTemporary) Error() string

func (ErrTemporary) String

func (e ErrTemporary) String() string

func (ErrTemporary) Temporary

func (e ErrTemporary) Temporary() bool

type TempErrCatcher

type TempErrCatcher struct {
	IsTemp func(error) bool    // the classifier to use. default: ErrIsTemporary
	Wait   func(time.Duration) // the wait func to call. default: time.Sleep
	Max    time.Duration       // the maximum time to wait. default: time.Second
	Start  time.Duration       // the delay to start with. default: InitialDelay
	// contains filtered or unexported fields
}

TempErrCatcher catches temporary errors for you. It then sleeps for a bit before returning (you should then try again). This may seem odd, but it's exactly what net/http does: http://golang.org/src/net/http/server.go?s=51504:51550#L1728

You can set a few options in TempErrCatcher. They all have defaults so a zero TempErrCatcher is ready to be used:

var c tec.TempErrCatcher
c.IsTemporary(tempErr)

func (*TempErrCatcher) IsTemporary

func (tec *TempErrCatcher) IsTemporary(e error) bool

IsTemporary checks whether an error is temporary. It will call tec.Wait before returning, with a delay. The delay is also doubled, so we do not constantly spin. This is the strategy net.Listener uses.

Note: you will want to call Reset() if you get a success, so that the stored delay is brough back to 0.

func (*TempErrCatcher) Reset

func (tec *TempErrCatcher) Reset()

Reset sets the internal delay counter to 0

type Temporary

type Temporary interface {
	Temporary() bool
}

Temporary is an interface errors can implement to ensure they are correctly classified by the default TempErrCatcher classifier