run

README

run

A drop-in replacement for oklog/run with automatic panic recovery.

Features

• Drop-in replacement: Compatible with oklog/run.Group API
• Automatic panic recovery: All panics in actors are caught and converted to errors
• Custom panic handlers: Optional custom handling of panic situations
• Zero dependencies: Only depends on oklog/run
• 100% test coverage: Thoroughly tested with comprehensive test suite

Installation

go get github.com/dio/run

Quick Start

package main

import (
    "errors"
    "fmt"
    "log"

    "github.com/dio/run"
)

func main() {
    g := run.New()

    // Add an actor that might panic
    g.Add(func() error {
        // This panic will be caught and converted to an error
        panic("something went wrong")
    }, func(err error) {
        log.Printf("Actor interrupted: %v", err)
    })

    // Add a normal actor
    g.Add(func() error {
        return errors.New("normal error")
    }, func(err error) {
        log.Printf("Actor interrupted: %v", err)
    })

    if err := g.Run(); err != nil {
        log.Printf("Group failed: %v", err)
    }
}

Usage

Basic Usage

The run.Group works exactly like oklog/run.Group but with automatic panic recovery:

g := run.New()

g.Add(execute, interrupt)

err := g.Run()

Custom Panic Handler

You can provide a custom panic handler to process panics in your own way:

g := run.NewWithHandler(func(panicValue any, stackTrace string) error {
    // Log the panic with custom formatting
    log.Printf("PANIC: %v\nStack trace:\n%s", panicValue, stackTrace)

    // Return a custom error
    return fmt.Errorf("actor panicked: %v", panicValue)
})

Error Handling

When an actor panics, it's automatically converted to a PanicError:

err := g.Run()
if err != nil {
    if panicErr, ok := err.(*run.PanicError); ok {
        fmt.Printf("Actor panicked with value: %v\n", panicErr.Value)
        fmt.Printf("Stack trace:\n%s\n", panicErr.StackTrace)
    }
}

API Reference

Types

Group

type Group struct {
    // PanicHandler is called when an actor panics.
    // If nil, panics are converted to PanicError and returned.
    PanicHandler func(panicValue any, stackTrace string) error
}

PanicError

type PanicError struct {
    Value      any    // The panic value
    StackTrace string // Stack trace at panic time
}

Functions

New

func New() *Group

Creates a new Group with panic recovery enabled.

NewWithHandler

func NewWithHandler(handler func(panicValue any, stackTrace string) error) *Group

Creates a new Group with a custom panic handler.

Methods

Add

func (g *Group) Add(execute func() error, interrupt func(error))

Add an actor to the group. This is a drop-in replacement for oklog/run.Group.Add().

Run

func (g *Group) Run() error

Execute all actors. This is identical to oklog/run.Group.Run().

Development

Prerequisites

• Go 1.24+
• golangci-lint (installed via go tool)

Building

go build ./...

Testing

go test -v -race -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Linting

go tool golangci-lint run

Formatting

go tool golangci-lint fmt

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for your changes
5. Ensure all tests pass (go test ./...)
6. Run linting (go tool golangci-lint run)
7. Commit your changes (git commit -am 'Add amazing feature')
8. Push to the branch (git push origin feature/amazing-feature)
9. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• oklog/run - The original actor model implementation
• Inspired by the need for safer concurrent programming in Go

Documentation

Index

• type Group
  • func New() *Group
  • func NewWithHandler(handler func(panicValue any, stackTrace string) error) *Group
  • func (g *Group) Add(execute func() error, interrupt func(error))
  • func (g *Group) Run() error
• type PanicError
  • func (e *PanicError) Error() string

Types

type Group

type Group struct {

	// PanicHandler is called when an actor panics.
	// If nil, panics are converted to PanicError and returned.
	// If set, this function is called with the panic value and stack trace.
	PanicHandler func(panicValue any, stackTrace string) error
	// contains filtered or unexported fields
}

Group is a drop-in replacement for oklog/run.Group with automatic panic recovery. All panics in actors are caught and converted to PanicError.

func New

func New() *Group

New creates a new Group with panic recovery always enabled.

func NewWithHandler

func NewWithHandler(handler func(panicValue any, stackTrace string) error) *Group

NewWithHandler creates a new Group with a custom panic handler.

func (*Group) Add

func (g *Group) Add(execute func() error, interrupt func(error))

Add an actor to the group with automatic panic recovery. This is a drop-in replacement for oklog/run.Group.Add().

func (*Group) Run

func (g *Group) Run() error

Run executes all actors. This is identical to oklog/run.Group.Run().

type PanicError

type PanicError struct {
	Value      any
	StackTrace string
}

PanicError represents an error that occurred during the execution of a program.

func (*PanicError) Error

func (e *PanicError) Error() string

Error implements the error interface for PanicError.