tsafe

README

tsafe - Panic-Safe Goroutine Launcher

English | 中文

tsafe is a lightweight Go library that makes goroutines panic-proof. Start goroutines safely with automatic panic recovery and customizable error handling.

Features

• Panic-Proof Goroutines: Automatically catch and handle panics in goroutines
• Custom Error Handling: Pluggable logger interface and custom recovery functions
• Thread-Safe: All operations are thread-safe and suitable for concurrent use
• Zero Dependencies: No external dependencies (only testify for testing)
• Minimal Overhead: Simple API with ~220ns per goroutine overhead

Installation

go get -u github.com/tinystack/tsafe

Quick Start

Basic Safe Goroutine Execution

package main

import (
    "fmt"
    "github.com/tinystack/tsafe"
)

func main() {
    // Safe goroutine with automatic panic recovery
    tsafe.Go(func() {
        panic("This won't crash your program!")
    })

    // Safe goroutine with custom panic handling
    tsafe.GoWithRecover(func() {
        panic("Custom handling")
    }, func(err any) {
        fmt.Printf("Caught panic: %v\n", err)
    })
}

Custom Logger

type MyLogger struct{}

func (l *MyLogger) Print(err, stack any) {
    log.Printf("Custom Logger - Error: %v\nStack: %s", err, stack)
}

func main() {
    // Set custom logger
    tsafe.SetLogger(&MyLogger{})

    tsafe.Go(func() {
        panic("This will be logged by MyLogger")
    })
}

API Reference

Core Functions

Go(goroutine func())

Starts a goroutine with automatic panic recovery. Panics are logged using the configured logger.

tsafe.Go(func() {
    // Your code here
    panic("This will be caught safely")
})

GoWithRecover(goroutine func(), customRecover func(err any))

Starts a goroutine with custom panic recovery handling.

tsafe.GoWithRecover(func() {
    // Your code here
    panic("Custom handling")
}, func(err any) {
    fmt.Printf("Caught: %v\n", err)
})

SetLogger(l Logger)

Sets a custom logger for panic handling. The logger must implement the Logger interface.

tsafe.SetLogger(&MyCustomLogger{})

Logger Interface

type Logger interface {
    Print(err, stack any) // Print logs an error and its stack trace
}

Best Practices

1. Use for fire-and-forget goroutines: Perfect for goroutines that shouldn't crash your application
2. Custom logging: Implement custom loggers for better error tracking and monitoring
3. Resource cleanup: Ensure proper resource cleanup in your goroutine functions
4. Error handling: Use GoWithRecover when you need specific error handling logic

Examples

Check out the examples directory for comprehensive usage examples:

• Basic Usage - Simple panic recovery examples
• Custom Logger Implementation - Various logger implementations

Testing

Run the test suite:

go test -v ./...

Run benchmarks:

go test -bench=. -benchmem

Performance

TSafe is designed for high performance with minimal overhead:

• Goroutine creation overhead: ~220ns per goroutine
• Memory allocation: 24B per goroutine

Contributing

Contributions are welcome! Please read our Contributing Guide for details on how to submit pull requests, report issues, and contribute to the project.

License

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

Changelog

See CHANGELOG.md for a detailed list of changes and version history.

Support

• Documentation: pkg.go.dev
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ❤️ by the TSafe team. If you find this project useful, please consider giving it a ⭐ on GitHub!

Documentation

Overview

Package tsafe provides utilities for safe goroutine execution with panic recovery

Index

• func Go(goroutine func())
• func GoWithRecover(goroutine func(), customRecover func(err any))
• func SetLogger(l Logger)
• type Logger

Functions

func Go

func Go(goroutine func())

Go starts a goroutine with automatic panic recovery When a panic occurs, it will be logged using the configured logger This is the most convenient way to start a safe goroutine

func GoWithRecover

func GoWithRecover(goroutine func(), customRecover func(err any))

GoWithRecover starts a goroutine with custom panic recovery handling Parameters:

• goroutine: the function to execute in the goroutine
• customRecover: the function to handle panic recovery (called if panic occurs)

This provides more control over error handling compared to Go()

func SetLogger

func SetLogger(l Logger)

SetLogger sets a custom logger for goroutine error handling This function is thread-safe

Types

type Logger

type Logger interface {
	// Print logs an error and its stack trace
	Print(err, stack any)
}

Logger defines the interface for custom error logging Users can implement this interface to customize how goroutine errors are logged