fwatch

README

the design of file watch

Background

I'd like to automatically operate all these files with a given suffix in a directory and all sub-directories. These files not being updated for a long time should be excluded, but need to be included if them being updated in a later time.

Features

• recursively list all file with given suffix in directory/sub-directories.
• send event when file created in directory/sub-directories.
• send event when file being inactive/silence.

Design

• directories: directory/sub-directories being watched.
• files: all active/inactive files, not include deleted or silence files.
• file event channel: channel for file events, include create, write, remove, inactive, and silence.
• error channel: channel for watch error.
• FsDirWatcher: a watcher to watch file create/remove events using fsnotify.
• TimerDirWatcher: a watcher periodically to scan files under directories.
• TimerFileWatcher: a watcher periodically to read and compare the stat of files to judge whether file is created/removed/inactive/silence.
• Timer Goroutine: using one goroutine to run directory and file watcher.

Usage

// method: `fs` or `timer`, `fs` uses `fsnotify` to watch file create/remove events,
//    while `timer` periodically reads and compares the stat of files to judge whether file is created/removed/inactive/silence.
// inactive duration: a file is considered to be inactive if it's not being updated in the given duration.
// silence duration: a file is considered to be silence and removed from watching files if it's not being updated in the given duration.
fileWatcher, err := fwatch.New(method, inactiveDuration, silenceDuration)
if err != nil {
    fmt.Println(err)
	return
}

go func() {
	for {
		select {
		case <-fileWatcher.Runner.C:
			return
		case f := <-fileWatcher.Events:
			fmt.Printf("--> events : %s, %v", f.Name, f.Event)
		}
	}
}()

// only watch log files.
matcher := func(s string) bool {
    return strings.HasSuffix(s, ".log")
}

if err = fileWatcher.WatchDir(tempDir, true, matcher); err != nil {
	fmt.Println(err)
	return
}

Documentation

Index

• Constants
• Variables
• func IsDir(name string) bool
• type DirStat
• type Event
  • func (e Event) String() string
• type FileMatcher
• type FileStat
• type FileWatcher
  • func New(watchMethod WatchMethod, inactiveDeadline, silenceDeadline time.Duration) (*FileWatcher, error)
  • func (fw *FileWatcher) SetDirFileCountLimit(count int)
  • func (fw *FileWatcher) Stop() error
  • func (fw *FileWatcher) WatchDir(dir string, includeSub bool, fileMatcher FileMatcher) error
• type WatchEvent
• type WatchMethod

Constants

const (

	// FileCreateEvents events for file create, unix.NOTE_WRIT is the event of file create/write,
	// there is not a event only to notify file create.
	FileCreateEvents = unix.IN_CREATE

	// FileWriteEvents events for file write.
	FileWriteEvents = unix.IN_MODIFY

	// FileRenameEvents events for file rename.
	FileRenameEvents = unix.IN_MOVE | unix.IN_MOVED_TO | unix.IN_MOVED_FROM | unix.IN_MOVE_SELF

	// FileRemoveEvents events for file remove.
	FileRemoveEvents = unix.IN_DELETE | unix.IN_DELETE_SELF

	// FileCreateRemoveEvents events for file create and remove.
	FileCreateRemoveEvents = FileCreateEvents | FileRemoveEvents | FileRenameEvents

	// FileWriteRemoveEvents events for file write and remove.
	FileWriteRemoveEvents = FileWriteEvents | FileRemoveEvents | FileRenameEvents
)

Variables

var ErrTooManyDirFile = errors.New("too many files under directory")

Functions

func IsDir

func IsDir(name string) bool

Types

type DirStat

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

DirStat dir stat.

type Event

type Event uint32

Event describes a set of file event.

const (
	Create Event = 1 << iota
	Write
	Remove
	Inactive
	Silence
)

These are file events that can trigger a notification.

func (Event) String

func (e Event) String() string

String event desc.

type FileMatcher

type FileMatcher func(string) bool

FileMatcher whether a file name matches.

type FileStat

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

FileStat file stat.

type FileWatcher

type FileWatcher struct {

	// Runner to control watching goroutines.
	Runner *gorun.Runner

	// a channel to notify active files.
	Events chan *WatchEvent

	// a channel to notify errors.
	Errors chan error
	// contains filtered or unexported fields
}

FileWatcher a file watcher, watch change event in directory/sub-directories. Note: the change event may be duplicated.

func New

func New(watchMethod WatchMethod, inactiveDeadline, silenceDeadline time.Duration) (*FileWatcher, error)

New create a new file watcher.

func (*FileWatcher) SetDirFileCountLimit

func (fw *FileWatcher) SetDirFileCountLimit(count int)

SetDirFileCountLimit allow user to config directory file count limit.

func (*FileWatcher) Stop

func (fw *FileWatcher) Stop() error

func (*FileWatcher) WatchDir

func (fw *FileWatcher) WatchDir(dir string, includeSub bool, fileMatcher FileMatcher) error

type WatchEvent

type WatchEvent struct {
	Name  string
	Event Event
}

WatchEvent file watch event.

type WatchMethod

type WatchMethod string

const (
	// WatchMethodFS using os file system api to watch file events.
	WatchMethodFS WatchMethod = "fs"

	// WatchMethodTimer interval schedule check stat of files and trigger file change events.
	WatchMethodTimer WatchMethod = "timer"
)