package panics

import "github.com/sourcegraph/conc/panics"

Index

Examples

Types

type Catcher 

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

Catcher is used to catch panics. You can execute a function with Try, which will catch any spawned panic. Try can be called any number of times, from any number of goroutines. Once all calls to Try have completed, you can get the value of the first panic (if any) with Recovered(), or you can just propagate the panic (re-panic) with Repanic().

Example

Code: 

{
	var pc Catcher
	i := 0
	pc.Try(func() { i += 1 })
	pc.Try(func() { panic("abort!") })
	pc.Try(func() { i += 1 })

	rc := pc.Recovered()

	fmt.Println(i)
	fmt.Println(rc.Value.(string))
	// Output:
	// 2
	// abort!
}

Output:

2
abort!
Example (Callers)

Code: 

{
	var pc Catcher
	pc.Try(func() { panic("mayday!") })

	recovered := pc.Recovered()

	// For debugging, the pre-formatted recovered.Stack is easier to use than
	// rc.Callers. This is not used in the example because its output is
	// machine-specific.

	frames := runtime.CallersFrames(recovered.Callers)
	for {
		frame, more := frames.Next()

		fmt.Println(frame.Function)

		if !more {
			break
		}
	}
	// Output:
	// github.com/sourcegraph/conc/panics.(*Catcher).tryRecover
	// runtime.gopanic
	// github.com/sourcegraph/conc/panics.ExampleCatcher_callers.func1
	// github.com/sourcegraph/conc/panics.(*Catcher).Try
	// github.com/sourcegraph/conc/panics.ExampleCatcher_callers
	// testing.runExample
	// testing.runExamples
	// testing.(*M).Run
	// main.main
	// runtime.main
	// runtime.goexit
}

Output:

github.com/sourcegraph/conc/panics.(*Catcher).tryRecover
runtime.gopanic
github.com/sourcegraph/conc/panics.ExampleCatcher_callers.func1
github.com/sourcegraph/conc/panics.(*Catcher).Try
github.com/sourcegraph/conc/panics.ExampleCatcher_callers
testing.runExample
testing.runExamples
testing.(*M).Run
main.main
runtime.main
runtime.goexit
Example (Error)

Code: 

{
	helper := func() error {
		var pc Catcher
		pc.Try(func() { panic(errors.New("error")) })
		return pc.Recovered().AsError()
	}

	if err := helper(); err != nil {
		// In normal use cases, you can use err.Error() output directly to
		// dump the panic's stack. This is not used in the example because
		// its output is machine-specific - instead, we demonstrate getting
		// the underlying error that was used for the panic.
		if cause := errors.Unwrap(err); cause != nil {
			fmt.Printf("helper panicked with an error: %s", cause)
		}
	}
	// Output:
	// helper panicked with an error: error
}

Output:

helper panicked with an error: error

func (*Catcher) Recovered 

func (p *Catcher) Recovered() *Recovered

Recovered returns the value of the first panic caught by Try, or nil if no calls to Try panicked.

func (*Catcher) Repanic 

func (p *Catcher) Repanic()

Repanic panics if any calls to Try caught a panic. It will panic with the value of the first panic caught, wrapped in a panics.Recovered with caller information.

func (*Catcher) Try 

func (p *Catcher) Try(f func())

Try executes f, catching any panic it might spawn. It is safe to call from multiple goroutines simultaneously.

type ErrRecovered 

type ErrRecovered struct{ Recovered }

ErrRecovered wraps a panics.Recovered in an error implementation.

func (*ErrRecovered) Error 

func (p *ErrRecovered) Error() string

func (*ErrRecovered) Unwrap 

func (p *ErrRecovered) Unwrap() error

type Recovered 

type Recovered struct {
	// The original value of the panic.
	Value any
	// The caller list as returned by runtime.Callers when the panic was
	// recovered. Can be used to produce a more detailed stack information with
	// runtime.CallersFrames.
	Callers []uintptr
	// The formatted stacktrace from the goroutine where the panic was recovered.
	// Easier to use than Callers.
	Stack []byte
}

Recovered is a panic that was caught with recover().

func NewRecovered 

func NewRecovered(skip int, value any) Recovered

NewRecovered creates a panics.Recovered from a panic value and a collected stacktrace. The skip parameter allows the caller to skip stack frames when collecting the stacktrace. Calling with a skip of 0 means include the call to NewRecovered in the stacktrace.

func Try 

func Try(f func()) *Recovered

Try executes f, catching and returning any panic it might spawn.

The recovered panic can be propagated with panic(), or handled as a normal error with (*panics.Recovered).AsError().

func (*Recovered) AsError 

func (p *Recovered) AsError() error

AsError casts the panic into an error implementation. The implementation is unwrappable with the cause of the panic, if the panic was provided one.

func (*Recovered) String 

func (p *Recovered) String() string

String renders a human-readable formatting of the panic.

Source Files

panics.go try.go

Version
v0.3.0 (latest)
Published
Feb 25, 2023
Platform
linux/amd64
Imports
4 packages
Last checked
1 hour ago –

Tools for package owners.