fileperf

README

fileperf

The fileperf package provides a library and command line tool for testing file system performance. It was written for use on Windows file systems but it may be of use on other platforms as well.

This library is a work-in-progress.

Documentation

Index

• Variables
• type Dir
  • func (dir Dir) FilePath(name string) string
  • func (dir Dir) Open(name string) (fs.File, error)
  • func (dir Dir) Stat(name string) (fs.FileInfo, error)
• type File
  • func (f File) String() string
• type FileIter
  • func ScanDir(ctx context.Context, root Dir) *FileIter
  • func (iter *FileIter) Close() error
  • func (iter *FileIter) Duration() time.Duration
  • func (iter *FileIter) Err() error
  • func (iter *FileIter) File() File
  • func (iter *FileIter) Scan(ctx context.Context) bool
  • func (iter *FileIter) Stats() JobStats
• type JobStats
  • func (s JobStats) String() string
• type Pattern
  • func (p Pattern) String() string
  • func (p *Pattern) UnmarshalText(text []byte) error
• type Scanner
  • func (s Scanner) ScanDir(root Dir) *FileIter

Variables

var ErrScanCancelled = errors.New("the scan has been cancelled")

ErrScanCancelled is reported by FileIter.Err() if it's been cancelled.

Types

type Dir

type Dir string

Dir is a file directory path accessible via operating system API acalls.

func (Dir) FilePath

func (dir Dir) FilePath(name string) string

FilePath returns the full path of the given file name by joining it with dir.

func (Dir) Open

func (dir Dir) Open(name string) (fs.File, error)

Open opens the named file.

func (Dir) Stat

func (dir Dir) Stat(name string) (fs.FileInfo, error)

Stat returns a FileInfo describing the file.

type File

type File struct {
	// Scanned file location
	Root    Dir
	Path    string
	Index   int
	Skipped bool

	// Error handling
	Err error

	// FileInfo values collected during a scan (may be empty)
	Name    string
	Size    int64
	Mode    fs.FileMode
	ModTime time.Time

	// File performance results
	Start, End time.Time
}

File describes a file that has been scanned.

func (File) String

func (f File) String() string

String returns a string representation of f, including its index and path.

type FileIter

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

FileIter is a file iterator returned by a Scanner. It's used to step through the results of a Scanner as they're produced.

func ScanDir

func ScanDir(ctx context.Context, root Dir) *FileIter

ScanDir scans the given file system directory for issues.

func (*FileIter) Close

func (iter *FileIter) Close() error

Close causes the iterator's job to stop running. It always returns nil.

func (*FileIter) Duration

func (iter *FileIter) Duration() time.Duration

Duration returns the duration of the iterator's job.

func (*FileIter) Err

func (iter *FileIter) Err() error

Err returns a non-nil error if the iterator's job encountered an error and stopped. It should be called after Scan() returns false. It returns nil if the job completed successfully.

func (*FileIter) File

func (iter *FileIter) File() File

File returns the most recently matched file. It is updated each time Scan() returns true. Scan() must be called at least once before calling this funcion.

func (*FileIter) Scan

func (iter *FileIter) Scan(ctx context.Context) bool

Scan waits for the next file to become available from the iterator. It returns false if the context is cancelled, the scanner encounters an error, or the end of the stream is reached.

When Scan returns false, check iter.Err() for a non-nil error to understand the cause.

func (*FileIter) Stats

func (iter *FileIter) Stats() JobStats

Stats returns the statistics for the iterator's job.

type JobStats

type JobStats struct {
	// ElapsedRead is the total time spent reading files.
	ElapsedRead time.Duration

	// TotalBytes is the total number of bytes read.
	TotalBytes int64

	// Read is the number of files read without issue.
	Read int

	// Errors is the number of files that encountered an error.
	Errors int

	// Scanned is the number of files scanned.
	Scanned int

	// Skipped is the number of files not scanned due to filters.
	Skipped int
}

JobStats report scanning tallies during and at the completion of scanning.

func (JobStats) String

func (s JobStats) String() string

String returns a string representation of the job statistics.

type Pattern

type Pattern struct {
	Expression *regexp.Regexp
}

Pattern is a file matching pattern based on regular expressions.

func (Pattern) String

func (p Pattern) String() string

String returns a string representation of the pattern.

func (*Pattern) UnmarshalText

func (p *Pattern) UnmarshalText(text []byte) error

UnmarshalText unmarshals the given text as a pattern in p.

type Scanner

type Scanner struct {

	// Include is a filter that limits the number of files scanned. If
	// provided, only files with names matching at least one pattern will
	// be scanned.
	Include []Pattern

	// Exclude is a filter that limits the number of files scanned. If
	// provided, only files with names that don't match any of its patterns
	// will be scanned.
	Exclude []Pattern
}

Scanner scans a set of files for issues identified by its issue handlers.

func (Scanner) ScanDir

func (s Scanner) ScanDir(root Dir) *FileIter

ScanDir causes the scanner to scan the given file system directory.