ding

README

ding

ding is a tiny Go library for graceful, ordered shutdown of background goroutines.

Goroutines are grouped into priority rings. When you trigger a shutdown, ding cancels and drains the rings one at a time, from the lowest priority to the highest, waiting for each ring to fully finish before moving on to the next. This lets you control teardown order — for example, stop accepting new requests before flushing critical state to disk.

Installation

go get github.com/steveiliop56/ding

Rings

There are four rings, ordered from highest to lowest priority. Each has a numeric name and a friendlier alias:

Alias	Value	Shuts down
RingCritical	Ring0	last
RingMajor	Ring1	third
RingNormal	Ring2	second
RingMinor	Ring3	first

Lower-priority rings (RingMinor first) are drained before higher-priority ones, so your most important work gets the most time to wind down.

Usage

package main

import (
	"context"
	"fmt"
	"os/signal"
	"syscall"

	"github.com/steveiliop56/ding"
)

func main() {
	// Cancel the context on Ctrl+C / SIGTERM to start the shutdown.
	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
	defer stop()

	d := ding.New(ctx)

	// Critical work drains last.
	d.Go(func(c context.Context) {
		<-c.Done()
		fmt.Println("flushing state...")
	}, ding.RingCritical)

	// Less important work drains first.
	d.Go(func(c context.Context) {
		<-c.Done()
		fmt.Println("stopping metrics reporter...")
	}, ding.RingMinor)

	// Block until every ring has drained.
	d.Wait()
}

API

• New(ctx context.Context) *Ding — creates a Ding. When ctx is cancelled, the rings are drained in priority order.
• (*Ding) Go(f func(ctx context.Context), ring Ring) — runs f on the given ring. The ctx passed to f is cancelled when that ring shuts down.
• (*Ding) Wait() — blocks until every ring has finished.

Examples

Runnable examples live in the examples directory:

• examples/basic — a single worker stopped by a signal.
• examples/rings — workers on every ring, showing the shutdown order.

go run ./examples/rings

Development

go test -race -cover ./...   # run tests with the race detector and coverage
go vet ./...                 # static analysis

License

MIT

Documentation

Index

• Constants
• type Ding
  • func New(ctx context.Context) *Ding
  • func (d *Ding) Go(f func(ctx context.Context), ring Ring)
  • func (d *Ding) Wait()
• type Ring

Constants

const (
	// RingCritical is the highest priority, it will get canceled last
	RingCritical = Ring0
	// RingMajor is the second highest priority, it will get canceled before RingCritical
	RingMajor = Ring1
	// RingNormal is the third highest priority, it will get canceled before RingMajor
	RingNormal = Ring2
	// RingMinor is the lowest priority, it will get canceled first
	RingMinor = Ring3
)

Types

type Ding

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

Ding is a struct that manages multiple rings of tasks with different priorities. Each ring has its own context and wait group.

func New

func New(ctx context.Context) *Ding

New creates a new Ding instance with the provided context. It initializes the rings and starts a goroutine to handle cancellation when the context is done.

func (*Ding) Go

func (d *Ding) Go(f func(ctx context.Context), ring Ring)

Go starts a new goroutine for the provided function f with the context of the specified ring. It works in the same way the standard library's sync.WaitGroup works, but it also takes into account the priority of the ring and cancels the context of the ring when the main context is done. Unlike the standard library's sync.WaitGroup, Ding's Go function also provides the f function with a context to watch so it can gracefully shutdown.

func (*Ding) Wait

func (d *Ding) Wait()

Wait blocks until all tasks in all rings have completed.

type Ring

type Ring int

Ring represents the priority of a task. Lower numbers indicate higher priority meaning they will be canceled later. For example, Ring 0 is the highest priority and will be canceled last, while Ring 3 is the lowest priority and will be canceled first.

const (
	// Ring 0 is the highest priority, it will get canceled last
	Ring0 Ring = iota
	// Ring 1 is the second highest priority, it will get canceled before Ring 0
	Ring1
	// Ring 2 is the third highest priority, it will get canceled before Ring 1
	Ring2
	// Ring 3 is the lowest priority, it will get canceled first
	Ring3
)