runnable

README

runnable

Overview

runnable is a Go package that provides a Runnable interface for functions or objects that can be started and stopped. It provides a simple way to run a function or object in a goroutine and stop it when needed. It also provides a way to run a function with retry and statistics number of restarts, when started and stopped, if returned error, etc.

Examples

Runnable Function

fmt.Println("Simple function...")
err := runnable.New(func(ctx context.Context) error {
    fmt.Println("Starting...")
    defer fmt.Println("Stopping...")

    for i := 0; i < 5; i++ {
        select {
        case <-ctx.Done():
            return nil
        default:
        }
        time.Sleep(1 * time.Second)
        fmt.Println("Running...")
    }
    return nil
}).Run(context.Background())
if err != nil {
    fmt.Println(err)
}

Runnable Function with Stop

fmt.Println("Simple function with stop...")
r := runnable.New(func(ctx context.Context) error {
    fmt.Println("Starting...")
    defer fmt.Println("Stopping...")

    for {
        select {
        case <-ctx.Done():
            return nil
        default:
        }
        time.Sleep(1 * time.Second)
        fmt.Println("Running...")
    }
})

go func() {
    time.Sleep(5 * time.Second)

    fmt.Println("Calling Stop...")
    err := r.Stop(context.Background())
    if err != nil {
        fmt.Println(err)
    }
}()

err = r.Run(context.Background())
if err != nil {
    fmt.Println(err)
}

Runnable Function with timeout

fmt.Println("Simple function with timeout...")
ctxWithTimeout, _ := context.WithTimeout(context.Background(), 5*time.Second)
err = runnable.New(func(ctx context.Context) error {
    fmt.Println("Starting...")
    defer fmt.Println("Stopping...")

    for {
        select {
        case <-ctx.Done():
            return nil
        default:
        }
        time.Sleep(1 * time.Second)
        fmt.Println("Running...")
    }
}).Run(ctxWithTimeout)
if err != nil {
    fmt.Println(err)
}

Runnable Function with retry

fmt.Println("Simple function with retry...")
errorReturned := false
err = runnable.New(func(ctx context.Context) error {
    fmt.Println("Starting...")
    defer fmt.Println("Stopping...")
    
    if !errorReturned {
        errorReturned = true
        return fmt.Errorf("error")
    }
    
    // do something
    for i := 0; i < 5; i++ {
        select {
        case <-ctx.Done():
            return nil
        default:
        }
        time.Sleep(1 * time.Second)
        fmt.Println("Running...")
    }
    return nil
}, runnable.WithRetry(3, runnable.ResetNever)).Run(context.Background())
if err != nil {
    fmt.Println(err)
}

Runnable Object

package main

import (
	"time"

	"github.com/0xsequence/runnable"
)

type Monitor struct {
	runnable.Runnable
}

func NewMonitor() *Monitor {
	m := &Monitor{}
	m.Runnable = runnable.New(m.run)
	return m
}

func (m *Monitor) run(ctx context.Context) error {
	fmt.Println("Starting...")
	defer fmt.Println("Stopping...")
	
	// Start monitoring
	for {
		select {
		case <-ctx.Done():
			return nil
		default:
		}

		time.Sleep(1 * time.Second)
		fmt.Println("Monitoring...")
	}
	return nil
}

func main() {
	fmt.Println("Runnable object(Monitor)...")
	m := NewMonitor()

	go func() {
		time.Sleep(5 * time.Second)

		fmt.Println("Calling Stop...")
		err := m.Stop(context.Background())
		if err != nil {
			fmt.Println(err)
		}
	}()

	err = m.Run(context.Background())
	if err != nil {
		fmt.Println(err)
	}
}

Documentation

Index

• Constants
• Variables
• type NoopReporter
  • func (*NoopReporter) Report(ctx context.Context, rec interface{})
• type Option
  • func WithRecoverer(reporter RecoveryReporter, stackPrinter StackPrinter) Option
  • func WithRetry(maxRetries int, resetAfter time.Duration) Option
  • func WithStatus(id string, store *StatusStore) Option
• type RecoveryReporter
• type Runnable
  • func New(runFunc func(ctx context.Context) error, options ...Option) Runnable
  • func NewGroup(runners ...Runnable) Runnable
• type StackPrinter
• type Status
• type StatusMap
• type StatusStore
  • func NewStatusStore() *StatusStore
  • func (s *StatusStore) Get() StatusMap

Constants

const ResetNever time.Duration = 0

Variables

var (
	ErrAlreadyRunning = fmt.Errorf("already running")
	ErrNotRunning     = fmt.Errorf("not running")
)

Types

type NoopReporter

type NoopReporter struct{}

NoopReporter Used to continue running go routine and do nothing

func (*NoopReporter) Report

func (*NoopReporter) Report(ctx context.Context, rec interface{})

type Option

type Option interface {
	// contains filtered or unexported methods
}

func WithRecoverer

func WithRecoverer(reporter RecoveryReporter, stackPrinter StackPrinter) Option

func WithRetry

func WithRetry(maxRetries int, resetAfter time.Duration) Option

func WithStatus

func WithStatus(id string, store *StatusStore) Option

type RecoveryReporter

type RecoveryReporter interface {
	Report(ctx context.Context, rec interface{})
}

type Runnable

type Runnable interface {
	Run(ctx context.Context) error
	Stop(ctx context.Context) error
	IsRunning() bool
}

func New

func New(runFunc func(ctx context.Context) error, options ...Option) Runnable

New creates a new Runnable with the given runFunc.

Example:

type Monitor struct {
	runnable.Runnable
}

func (m *Monitor) run(ctx context.Context) error {
	// do something
	return nil
}

func NewMonitor() Monitor {
	m := Monitor{}
	m.Runnable = runnable.NewRunnable(m.run)
	return m
}

func NewGroup

func NewGroup(runners ...Runnable) Runnable

NewGroup creates a new Runnable that runs multiple runnables concurrently.

Example:

group := NewGroup(
	New(func(ctx context.Context) error {
		// do something
		return nil
	}),
	New(func(ctx context.Context) error {
		// do something
		return nil
	}),
)

err := group.Run(context.Background())
if err != nil {
	// handle error
}

type StackPrinter

type StackPrinter interface {
	Print(ctx context.Context, callstack []byte)
}

type Status

type Status struct {
	Running   bool       `json:"running"`
	Restarts  int        `json:"restarts"`
	StartTime time.Time  `json:"start_time"`
	EndTime   *time.Time `json:"end_time,omitempty"`
	LastError error      `json:"last_error"`
}

type StatusMap

type StatusMap map[string]Status

type StatusStore

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

func NewStatusStore

func NewStatusStore() *StatusStore

func (*StatusStore) Get

func (s *StatusStore) Get() StatusMap