deptask

Documentation

Overview

Package deptask provides a tool, Runner, to run tasks in order according to its dependency.

Runner is designed to handle complex initializing process of large project. All method that executes the tasks follows fail-fast principle.

Index

• Variables
• type ErrMissing
  • func (e ErrMissing) Error() string
• type Runner
  • func New() *Runner
  • func WithHook(pre func(string), post func(string, bool, error)) *Runner
  • func (r *Runner) Add(name string, f task.Task, deps ...string) error
  • func (r *Runner) CopyTo(dst *Runner, names ...string) error
  • func (r *Runner) ListDeps(names ...string) (ret []string)
  • func (r *Runner) MustAdd(name string, f task.Task, deps ...string)
  • func (r *Runner) Run(ctx context.Context) error
  • func (r *Runner) RunSome(ctx context.Context, names ...string) error
  • func (r *Runner) RunSomeSync(ctx context.Context, names ...string) error
  • func (r *Runner) RunSync(ctx context.Context) error
  • func (r *Runner) Skip(names ...string)
  • func (r *Runner) Skipped(name string) (bool, error)
  • func (r *Runner) Validate() error

Examples

• Runner
• Runner.Skip

Variables

var (
	// ErrDup indicates task name is already used.
	ErrDup = errors.New("duplicated task name")
	// ErrCyclic indicates there're cyclic dependencies.
	ErrCyclic = errors.New("cyclic dependencies detected")
)

Types

type ErrMissing

type ErrMissing string

ErrMissing indicates a dependency is missing.

func (ErrMissing) Error

func (e ErrMissing) Error() string

type Runner

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

Runner manages task dependencies and runs the tasks.

Runner is not thread-safe, you MUST NOT share same instance amoung multiple goroutines.

Runner remembers whether a task is executed or not. Take a look at examples for detail.

Zero value denotes an empty Runner, internal data structures are initialized when Runner.Add or Runner.Validate is called.

Example

r := New()
body := func(n string) task.Task {
	return task.Task(func(_ context.Context) error {
		fmt.Println(n)
		return nil
	})
}
r.MustAdd("a", body("a"))
r.MustAdd("b", body("b"), "a")
r.MustAdd("c", body("c"), "b")
r.MustAdd("d", body("d"), "c")
r.MustAdd("e", body("e"), "d")

fmt.Println("RunSomeSync(c):")
r.RunSomeSync(context.TODO(), "c")

fmt.Println("RunSomeSync(e):")
r.RunSomeSync(context.TODO(), "e")

Output:

RunSomeSync(c):
a
b
c
RunSomeSync(e):
d
e

func New

func New() *Runner

New is shortcut to WithHook(nil, nil)

func WithHook

func WithHook(pre func(string), post func(string, bool, error)) *Runner

WithHook creates a Runner with two hooks.

pre is called right before actually executing the task. post is called after the execution, or everytime a skipped task is detected.

This was originally designed to show debug log.

func (*Runner) Add

func (r *Runner) Add(name string, f task.Task, deps ...string) error

Add adds a task to Runner, will return ErrDup if name has been used.

func (*Runner) CopyTo

func (r *Runner) CopyTo(dst *Runner, names ...string) error

CopyTo copies specified tasks and their deps to dst using dst.Add. Useful when testing.

Non-exist tasks are ignored silently. Say you have a Runner contains four tasks: a, b, c (depends b) and d. Calling with a, c, f will add task a, b and c into dst.

ErrDup returned by dst.Add is silently ignored.

It will call Runner.Validate on r (and returns error if any) before actually coping tasks.

State is not copied! Use with caution!

func (*Runner) ListDeps

func (r *Runner) ListDeps(names ...string) (ret []string)

ListDeps lists the dependencies of given tasks, or all tasks if no task is given. Order is unspecified.

func (*Runner) MustAdd

func (r *Runner) MustAdd(name string, f task.Task, deps ...string)

MustAdd is like Add, but panics instead of returning error.

func (*Runner) Run

func (r *Runner) Run(ctx context.Context) error

Run is shortcut to "RunSome(ctx)"

func (*Runner) RunSome

func (r *Runner) RunSome(ctx context.Context, names ...string) error

RunSome validates dependencies and runs some tasks (and deps) concurrently.

When an error occured, other tasks are canceled, prevents further execution.

func (*Runner) RunSomeSync

func (r *Runner) RunSomeSync(ctx context.Context, names ...string) error

RunSomeSync validates dependencies and runs some tasks (and deps) synchronously. The order is unspecified, only dependencies are ensured.

It returns immediately after first error.

func (*Runner) RunSync

func (r *Runner) RunSync(ctx context.Context) error

RunSync is shortcut to "RunSomesync(ctx)"

func (*Runner) Skip

func (r *Runner) Skip(names ...string)

Mark some tasks to be skipped. Skipped task will not be executed, just pretends that it has finished. Other tasks in dependency tree are unaffected.

Unknown task is ignored silently.

Example

r := New()
body := func(n string) task.Task {
	return task.Task(func(_ context.Context) error {
		fmt.Println(n)
		return nil
	})
}
r.MustAdd("a", body("a"))
r.MustAdd("b", body("b"), "a")
r.MustAdd("c", body("c"), "b")
r.MustAdd("d", body("d"), "c")
r.MustAdd("e", body("e"), "d")
r.Skip("s", "e", "a")

fmt.Println("RunSomeSync(e):")
r.RunSomeSync(context.TODO(), "e")

Output:

RunSomeSync(e):
b
c
d

func (*Runner) Skipped

func (r *Runner) Skipped(name string) (bool, error)

Skipped check if named task is marked as skip. If the task does not exist, ErrMissing is returned.

func (*Runner) Validate

func (r *Runner) Validate() error

Validate validates the Runner, reports following errors if any:

• ErrMissing: one or more dependecy is missing.
• ErrCyclic: there are cyclic dependencies.

It caches the result until you call Runner.Add. Feel free to run it multiple times.