stager

README

Stager

Stager is a library to help write code where you are in control of start and shutdown of concurrent operations. I.e. you know when goroutines start and stop and in which order.

An example is below:

package main

import (
  "context"
  "log"
  "time"

  "github.com/ash2k/stager"
)

func main() {
  defer log.Print("Exiting main")
  st := stager.New()

  s := st.NextStage()
  s.Go(func(ctx context.Context) error {
    log.Print("Start 1.1")
    defer log.Print("Stop 1.1")
    <-ctx.Done()
    return nil
  })
  s.Go(func(ctx context.Context) error {
    log.Print("Start 1.2")
    defer log.Print("Stop 1.2")
    <-ctx.Done()
    return nil
  })

  s = st.NextStage()
  s.Go(func(ctx context.Context) error {
    log.Print("Start 2")
    defer log.Print("Stop 2")
    <-ctx.Done()
    return nil
  })

  s = st.NextStage()
  s.Go(func(ctx context.Context) error {
    log.Print("Start 3")
    defer log.Print("Stop 3")
    <-ctx.Done()
    return nil
  })

  ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
  defer cancel()
  err := st.Run(ctx)
  if err != nil {
    log.Fatal(err)
  }
}

Output:

2020/12/15 15:34:41 Start 3
2020/12/15 15:34:41 Start 1.2
2020/12/15 15:34:41 Start 1.1
2020/12/15 15:34:41 Start 2
2020/12/15 15:34:46 Stop 3
2020/12/15 15:34:46 Stop 2
2020/12/15 15:34:46 Stop 1.2
2020/12/15 15:34:46 Stop 1.1
2020/12/15 15:34:46 Exiting main

Note the following:

• Shutdown order is deterministic - 3, 2, and then 1.
• Shutdown order within a stage is not deterministic - 1.1 and 1.2 are not ordered.

Documentation

Index

• func RunStages(ctx context.Context, stages ...StageFunc) error
• type Stage
• type StageFunc
• type Stager
  • func New() Stager

Functions

func RunStages

func RunStages(ctx context.Context, stages ...StageFunc) error

RunStages is a helper that ensures Run() is always executed and there is no chance of early exit so that goroutines from stages don't leak.

Types

type Stage

type Stage interface {
	// Go starts f in a new goroutine attached to the Stage.
	// Stage context is passed to f as an argument. f should stop when context signals done.
	// If f returns a non-nil error, the stager starts performing shutdown.
	Go(f func(context.Context) error)
	// GoWhenDone starts f in a new goroutine attached to the Stage when the stage starts shutting down.
	// Stage shutdown waits for f to exit.
	GoWhenDone(f func() error)
}

type StageFunc

type StageFunc func(Stage)

StageFunc is a function that uses the provided Stage to start goroutines.

type Stager

type Stager interface {
	// NextStage adds a new stage to the Stager.
	NextStage() Stage
	// NextStageWithContext adds a new stage to the Stager. Provided ctxParent is used as the parent context for the
	// Stage's context.
	NextStageWithContext(ctxParent context.Context) Stage
	// Run blocks until ctx signals done or a function in a stage returns a non-nil error.
	// When it unblocks, it iterates Stages in reverse order. For each stage it cancels
	// it's context and waits for all started goroutines of that stage to finish.
	// Then it proceeds to the next stage.
	Run(ctx context.Context) error
}

func New

func New() Stager