README
¶
golly
A transient error handling library for Go, like Polly. But for Go.
Usage
Golly is really simple, and short. It's a convenience, and there's no reason not to look at the code to see how it works. The most basic example, that connects to a MySQL server:
var err error
var db *sql.DB
mysqlConnection = "[connection-parameters]"
err = golly.Run(func() error {
db, err = sql.Open("mysql", mysqlConnection)
if nil!=err {
return err
}
// Ping is required to check that the server is really there
return db.Ping()
})
This example will attempt to connect to the mysql server, and ping the server to ensure it's working. If there is an error, golly will retry the function indefinitely, first with a 1 second pause, then 2, 4, 8, 16 and 32s pauses until success.
This example is encapsulated in the golly.DbOpen function. So you can simplify this code to:
db, err := golly.DbOpen("mysql", "[connection parameters]")
Retrying
Golly catches errors and handles retries through a retry handler. This is a function of the form:
func (err error, failureCount int, lastWait time.Duration) (time.Duration,error)
The retry handler returns the time.Duration that golly should wait before retrying (a negative or zero duration will cause golly to retry at once). If the retry handler doesn't want to retry, but rather to abort, return a non-nil error.
You set the retry handle with the Retry() method/function.
By default, Golly uses the golly.RetryWithBackoff function defined in presets.go. It's really simple, and does the 2, 4, 8, 16 and 32s pauses.
Methods or Functions
Golly uses a struct to configure handlers and keep track of the failures on a function call. You can create this struct with the golly.New() function call. There are proxy functions in golly that automatically call golly.New() for you, so in practice you don't need golly.New() at all.
Golly Methods / Functions
Golly has four methods:
New() *Golly
Returns a new Golly structure. Because golly defines a function for every 'method', you should never need to use the New(). The other golly functions automatically call a New() for you.
Retry(func (error,int,time.Duration) (time.Duration,error)) *Golly
Retry sets a Retry handler for the Golly struct. The retry handler returns determines whether to return an error, or retry after the returned duration has passed.
Panic(func (interface{}) error) *Golly
Panic sets a panic handler. The panic handler can convert any panic to an error, to permit golly to do retries on panics as well as errors. By default, golly doesn't handle panics. If you don't have a panic handler, of if you throw a panic from the panic handler, golly would exit with the panic.
Logging Errors
If the golly.ErrorLog var is set, golly will report all errors it encounters while trying to connect to the database to this function. This can be useful, since if your database connection string is faulty, your application can appear to be frozen awaiting a database connection.
To use this, just set the ErrorLog var to your own func (err error) implementation:
golly.ErrorLog = func(err error) { fmt.Fprintln(os.Stderr, err.Error()) }
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrorLog func(err error)
Set ErrorLog to report errors to your logging system
Functions ¶
func DbOpen ¶
DbOpen is a utility method that connects to a Database, and Ping's the database, permitting really easy data connection. It runs a standard golly.Run function to ensure that the connection MUST succeed before this function will return.
func RetryWithBackoff ¶
RetryWithBackoff is the default retry handler for golly. The default handler will retry indefinitely, with backoff waits between attempts of 1, 2, 4, 8, 16 and ultimately 32s.
Types ¶
type Golly ¶
type Golly struct {
// contains filtered or unexported fields
}
func New ¶
func New() *Golly
New returns a new golly struct configured with a default retry handler of RetryWithBackoff. The golly functions will automatically call New() for you, so there's no necessity to use New() yourself for basic golly usage.
func (*Golly) Panic ¶
Panic sets the panic handler on the Golly struct. The panic handler will be called if the function that is Run panics. If the panic handler returns an error, golly's wait handler will receive the error and handle it as it would any other error.
func (*Golly) Retry ¶
func (g *Golly) Retry(retry func(err error, errorCount int, lastWait time.Duration) (time.Duration, error)) *Golly
Retry sets the retry handler. The retry handler determines whether golly should retry the Run function, or exit with an error. If the retry handler returns an error, golly's Run method returns the error. If it returns a nil error and a time.Duration, golly will wait for the duration, then retry the function.
Source Files
Directories