package fsrun

import "go.abhg.dev/fsrun"

Package fsrun provides the ability to concurrently traverse a filesystem.

Index

Variables

var SkipDir = fs.SkipDir

SkipDir indicates that the children of a directory should be skipped during a traversal.

If the path being inspected is not a directory, the value is ignored.

Functions

func WalkDir

func WalkDir(fsys fs.FS, root string, fn fs.WalkDirFunc) error

WalkDir walks the file tree starting at root concurrently, calling fn for each file or directory in the tree (including root).

There are no ordering guarantees except that fn is called for a directory before its descendants.

fn may return SkipDir to skip a directory's descendants. SkipDir will be ignored if the entry is a file.

fn may return any other non-nil error to stop the traversal.

This is a near drop-in concurrent replacement for fs.WalkDir with one difference: SkipDir is respected only if the entry is a directory, and it's ignored for files.

See also Config.Run.

Types

type Config

type Config struct {
	// Concurrency specifies the maximum number of concurrent visitors
	// in a traversal.
	//
	// Defaults to GOMAXPROCS.
	Concurrency int
}

Config specifies the configuration for a concurrent filesystem traversal.

For simple use cases, you may prefer to use WalkDir.

func (*Config) Run

func (cfg *Config) Run(fsys fs.FS, root string, v Visitor) error

Run traverses the file tree rooted at root concurrently, calling the visitor on each file and directory in the tree including root.

There are no ordering guarantees except that we will visit a directory before its descendants.

If a Visitor returns SkipDir, Run will not visit that directory's descendants. SkipDir will be ignored if the path visited was not a directory.

If Run encounters an error inspecting a path after visiting it, it may invoke Visitor again for that path with the failure. The Visitor may return SkipDir at this point to ignore the error.

If a Visitor returns any other error, Run will halt the traversal and return that error.

type Func

type Func func(path string, ent fs.DirEntry, err error) error

Func is called during a traversal with the path of a file and its directory entry. It may be called by multiple goroutines concurrently.

path is the path to the file joined with the root provided at the start of the traversal.

The provided err is non-nil if an error was encountered while inspecting this path. If err is non-nil, ent may be nil.

The function may return SkipDir to skip a directory during the traversal.

func (Func) Visit

func (f Func) Visit(path string, ent fs.DirEntry, err error) error

Visit implements Visitor for Func. Use this implementation to pass a Func into Config.Run. 

cfg := Config{...}
cfg.Run(fsys, root, fsrun.Func(
	func(path string, ent fs.DirEntry, err error) error {
		// ...
	}))

type Visitor

type Visitor interface {
	// Visit visits a single file or directory in a traversal.
	//
	// path is the path to the file, joined with the root directory.
	// err is non-nil if there was an error inspecting a file or directory.
	Visit(path string, ent fs.DirEntry, err error) error
}

Visitor visits files and directories during a concurrent traversal. It is invoked with the path and DirEntry for each file or directory in a file tree starting at the root provided to Config.Run. It may be called by multiple goroutines concurrently.

Visitor is passed a non-nil error if an error was encountered while inspecting a path. In such a scenario, be aware that: