api

type BasicResult struct {
	Finfo FileInfo
	Msg   string
	Err   error
	Prio  Importance
}

type BasicRunner struct {
	// Items we work on
	Items []string
	// A map of readers which maps from a root to the reader to use to read files that share the same root
	RootedReaders io.RootedReadControllers
	// A channel to let everyone know we should finish as soon as possible - this is done by closing the channel
	Done chan bool

	// our statistics instance
	Stats Stats

	// The maximum log-level. We just keep this value here because the cli makes a difference between CHECK and RUN !
	// This member shouldn't be needed as logging is not done by the runner anyway - it's all done by result handlers.
	// Only they are concerned, which is a function of the CLI entirely
	// TODO(st) Fork codegangsa/CLI and make the fix, use the fork from that point on ... .
	Level   Importance
	Filters []FileFilter
}

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

type FileHashMismatch struct {
	Path string
}

type FileInfo struct {

	// path to file to handle
	Path string

	// Path relative to the directory it was found in
	RelaPath string

	// Provides information about the type of the file
	Mode os.FileMode

	// size of file
	Size int64

	// hashes of file
	Sha1 []byte
	MD5  []byte
}

type FileSizeMismatch struct {
	Path      string
	Want, Got int64
}

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

type Importance uint8

type Result interface {
	// Return a string indicating the result, which can can also state an error
	// The priority show the kind of result messgae, allowing you to filter them effectively
	Info() (string, Importance)

	// Return an error instance indicating what exactly when wrong
	Error() error

	// Return the FileInformation we represent
	FileInformation() *FileInfo
}

type Runner interface {

	// Intialize required members to deal with controlled reading and writing. numReaders and numWriters
	// can be assumed to be valid
	// Sets the items we are supposed to be working on - must be checked by implementation, as they are
	// very generic in nature
	Init(numReaders, numWriters int, items []string, maxLogLevel Importance, filters []FileFilter) error

	// Return the amount of io-channels the runner may be using in parallel per device
	NumChannels() int

	// Return the minimum allowed level for logging
	// TODO(st): get rid of this method !
	LogLevel() Importance

	// Statistics returns the commands shared statistics structure
	Statistics() *Stats

	// CancelChannel returns the channel to close when the operation should stop prematurely
	// NOTE: Only valid after Init was called, and it's an error to call it beforehand
	CancelChannel() chan bool

	// Launches generators, gatherers and an aggregator, setting up their connections to fit.
	// Must close FileInfo channel when done
	// Must listen for SIGTERM|SIGINT signals and abort if received
	// May report errrors or information about the progress through generateResult, which must NOT be closed when done. Return nothing
	// if there is nothing to report
	// Must listen on done and return asap
	Generate() (aggregationResult <-chan Result)

	// Will be launched as go routine and perform whichever operation on the FileInfo received from input channel
	// Produces one result per input FileInfo and returns it in the given results channel
	// Must listen for SIGTERM|SIGINT signals
	// Use the wait group to mark when done, which is when the results channel need to be closed.
	// Must listen on done and return asap
	Gather(rctrl *io.ReadChannelController, files <-chan FileInfo, results chan<- Result)

	// Aggregate the result channel and produce whatever you have to produce from the result of the Gather steps
	// When you are done, place a single result instance into accumResult and close the channel
	// You must listen on done to know if the operation was aborted prematurely. This information should be useful
	// for your result.
	Aggregate(results <-chan Result) <-chan Result
}

type StatisticsFilter struct {
	LastResultShownAt    time.Time     // time at which you have used a result, whichever prio
	FirstStatisticsAfter time.Duration // time after which the first message will show
}

type Stats struct {
	io.Stats

	BytesHashed uint64 // Total of bytes hashed so far, counting all active hashers
	NumHashers  uint32 // Amount of hashers running in parallel

	//GENERATOR INFORMATION
	NumSkippedFiles uint32 // Amount of files we skipped right away
	StopTheEngines  uint32 // Amount of gather procs which had write errors on all destinations

	// AGGREGATION
	// Aggregation step is single-threaded - no atomic operation needed
	ErrCount       uint // Amount of errors that hit the aggregation step
	NumUndoneFiles uint // Amout of files removed during undo
	WasCancelled   bool // is true if the user cancelled

}