lifecycle

README

lifecycle

Documentation

Overview

Example

package main

import (
	"context"
	"log"
	"time"

	"github.com/joshuarubin/lifecycle"
)

func main() {
	// At the top of your application
	ctx := lifecycle.New(
		context.Background(),
		lifecycle.WithTimeout(30*time.Second),
	)

	funcErr := func() error {
		// do stuff
		return nil
	}

	funcCtx := func(ctx context.Context) {
		done := make(chan struct{})
		go func() {
			// do stuff
			close(done)
		}()

		select {
		case <-done:
		case <-ctx.Done():
		}
	}

	funcCtxErr := func(ctx context.Context) error {
		done := make(chan struct{})
		go func() {
			// do stuff
			close(done)
		}()

		select {
		case <-done:
			return nil
		case <-ctx.Done():
			return ctx.Err()
		}
	}

	{ // Then you execute things that it will manage
		lifecycle.Go(ctx, func() {
			// do stuff
		})
		lifecycle.Go(ctx, funcErr)
		lifecycle.Go(ctx, funcCtx)
		lifecycle.Go(ctx, funcCtxErr)
	}

	{ // You can also add cleanup tasks that only get run on shutdown
		lifecycle.Defer(ctx, func() {
			// do cleanup stuff
		})
		lifecycle.Defer(ctx, funcErr)
		lifecycle.Defer(ctx, funcCtx)
		lifecycle.Defer(ctx, funcCtxErr)
	}

	// Then at the end of main(), or run() or however your application operates
	//
	// The returned err is the first non-nil error returned by any func
	// registered with Go or Defer, otherwise nil.
	if err := lifecycle.Wait(ctx); err != nil {
		log.Fatal(err)
	}
}

Index

• Variables
• func Defer(ctx context.Context, deferred ...interface{})
• func Go(ctx context.Context, f ...interface{})
• func New(ctx context.Context, opts ...Option) context.Context
• func Wait(ctx context.Context) error
• type ErrSignal
  • func (e ErrSignal) Error() string
• type Option
  • func WithSignals(val ...os.Signal) Option
  • func WithTimeout(val time.Duration) Option

Examples

• Package

Variables

var ErrNoManager = fmt.Errorf("lifecycle: manager not in context")

ErrNoManager is returned by Go(), Defer(), and Wait() if called and the passed in context was not created with New()

Functions

func Defer

func Defer(ctx context.Context, deferred ...interface{})

Defer adds funcs that should be called after the Go funcs complete (either clean or with errors) or a signal is received. If any Go or Defer func returns an error, only the first one will be returned by Wait()

The following signatures are acceptable for deferred:

func()
func() error
func(context.Context)
func(context.Context) error

Anything else passe in will result in a panic

func Go

func Go(ctx context.Context, f ...interface{})

Go run a function in a new goroutine. If any Go or Defer func returns an error, only the first one will be returned by Wait()

The following signatures are acceptable for f:

func()
func() error
func(context.Context)
func(context.Context) error

Anything else passe in will result in a panic

func New

func New(ctx context.Context, opts ...Option) context.Context

New returns a lifecycle manager with context derived from that provided.

func Wait

func Wait(ctx context.Context) error

Wait blocks until all go routines have been completed.

All funcs registered with Go and Defer _will_ complete under every circumstance except a panic

Funcs passed to Defer begin (and the context returned by New() is canceled) when any of:

• All funcs registered with Go complete successfully
• Any func registered with Go returns an error
• A signal is received (by default SIGINT or SIGTERM, but can be changed by WithSignals

Funcs registered with Go should stop and clean up when the context returned by New() is canceled. If the func accepts a context argument, it will be passed the context returned by New().

WithTimeout() can be used to set a maximum amount of time, starting with the context returned by New() is canceled, that Wait will wait before returning.

The returned err is the first non-nil error returned by any func registered with Go or Defer, otherwise nil.

Types

type ErrSignal

type ErrSignal struct {
	os.Signal
}

ErrSignal is returned by Wait if the reason it returned was because a signal was caught

func (ErrSignal) Error

func (e ErrSignal) Error() string

type Option

type Option func(*manager)

An Option is used to configure the lifecycle manager

func WithSignals

func WithSignals(val ...os.Signal) Option

WithSignals causes Handle to wait for Go funcs to finish, if WhenDone was used or until a signal is received. The signals it will wait for can be defined with WithSigs or will default to DefaultSignals

func WithTimeout

func WithTimeout(val time.Duration) Option

WithTimeout sets an upper limit for how much time Handle will wait to return. After the Go funcs finish, if WhenDone was used, or after a signal is received if WhenSignaled was used, this timer starts. From that point, Handle will return if any Go or Defer function takes longer than this value.