Documentation
¶
Overview ¶
Package watchfs provides a file-system watcher for Linux and macOS.
Index ¶
- Constants
- Variables
- func NewIterator(path string, filter Op, ignores *regexp.Regexp, ctx ...context.Context) (iterator iters.Iterator[*WatchEvent])
- func UnpackEvents(anyEvent any) (watchEvent *WatchEvent, watchEvents []*WatchEvent)
- type Iterator
- type Op
- type WatchEvent
- type Watcher
- type WatcherCh
- type WatcherShim
Constants ¶
View Source
const ( // Create|Write|Remove|Rename|Chmod WatchOpAll Op = 0 Create = Op(fsnotify.Create) Write = Op(fsnotify.Write) Remove = Op(fsnotify.Remove) Rename = Op(fsnotify.Rename) Chmod = Op(fsnotify.Chmod) )
enum bit values for watchfs.Op are the same as fsnotify.Op
Variables ¶
View Source
var NoIgnores *regexp.Regexp
Functions ¶
func NewIterator ¶ added in v0.4.143
func NewIterator(path string, filter Op, ignores *regexp.Regexp, ctx ...context.Context) (iterator iters.Iterator[*WatchEvent])
NewIterator returns a file-system watch-event iterator
- blocking iterator for use with go for-statement
- optional context for cancelation
- filter WatchOpAll (default: 0) is: Create Write Remove Rename Chmod it can also be a bit-coded value.
- ignores is a regexp for the absolute filename. It is applied while scanning directories, not for individual events.
- thread-safe
- consumers are expected to use:
- — NewIterator using a Go for-statement iterative api
- — NewWatcherCh using Go channel api
- — NewWatcher using callback api
Usage:
var iterator = watchfs.NewIterator(somePath, watchfs.WatchOpAll, watchfs.NoIgnores, ctx)
defer iterator.Cancel(&err)
for watchEvent, _ := iterator.Init(); iterator.Cond(&watchEvent); {…
func UnpackEvents ¶ added in v0.4.141
func UnpackEvents(anyEvent any) (watchEvent *WatchEvent, watchEvents []*WatchEvent)
UnpackEvents extracts events and slices from a value received on WatcherCh.Ch
- interface type is any
- runtime type is *WatchEvent or []*WatchEvent
- if watchEvent non-nil, it is the single event returned
- if len(watchEvents) > 0, it holds 2 or more returned events
- if watchEvent and watchEvents are both nil, the watcher has ended
Types ¶
type Iterator ¶ added in v0.4.143
type Iterator struct {
// contains filtered or unexported fields
}
Iterator is a file-system watcher with Go for-statement iterative api
type Op ¶
type Op uint32
Op allows callers to not import fsnotify dependency
- Op value is a bitfield of or of one or more Op enum bits
- Create Write Remove Rename Chmod
type WatchEvent ¶
type WatchEvent struct {
// At is a time with ns resolution in time.Local time-zone
At time.Time
// ID uniquely identifies the event, [16]byte
ID uuid.UUID
// BaseName “filename.ext”
BaseName string
// AbsName: “/absolute-path/filename.ext”
AbsName string
// Op is an or-string of one or more file-system operations:
// - CREATE or
// - CREATE|REMOVE|WRITE|RENAME|CHMOD
Op string
// OpBits is operation bitfield
OpBits Op
}
WatchEvent contains data about a file system event
- ID is unique for the event
- WatchEvent is a value-container that as a local variable, function argument or result is a tuple not causing allocation by using temporary stack storage
- taking the address of a &ResultEntry causes allocation
func (WatchEvent) Dump ¶ added in v0.4.145
func (e WatchEvent) Dump() (s string)
func (WatchEvent) String ¶
func (e WatchEvent) String() (s string)
type Watcher ¶ added in v0.4.26
type Watcher struct {
WatcherShim
// contains filtered or unexported fields
}
Watcher implements a file-system watcher using callback api
- consumers are expected to use:
- — NewIterator using a Go for-statement iterative api
- — NewWatcherCh using Go channel api
- — NewWatcher using callback api
- eventFn receives filtered events and must be thread-safe
- if directories are created, Watcher adds those to being watched
- —
- the fsnotify api provides two channels so threading is required
- the Errors channel is unbuffered
- the Events channel is typically unbuffered but can be buffered
- Events are sent by value with name and Op only
- — no timestamp
- — no unique identifier
- watchers are not recursive into subdirectories
- — to detect new entires, all child-directories must be watched
func NewWatcher ¶ added in v0.4.26
func NewWatcher( filter Op, ignores *regexp.Regexp, eventFn func(event *WatchEvent), errFn func(err error), ) (watcher *Watcher)
NewWatcher provides a channel sending file-system events from a file-system entry and its child directories.
- consider using Iterator or NewWatcherCh for callback-free architecture
- filter WatchOpAll (default: 0) is: Create Write Remove Rename Chmod. it can also be a bit-coded value.
- ignores is a regexp for the absolute filename. it is applied while scanning directories.
- eventFn must be thread-safe. this means that any storing and subsequent retrieval of event must be thread-safe, protected by go, Mutex or atomic
- errFn must be thread-safe.
- Close the watcher by canceling the context or invoking .Shutdown(). This means that any storing and subequent retrieval of the err value must be thread-safe, protected by go, Mutex or atomic
type WatcherCh ¶ added in v0.4.141
type WatcherCh struct {
// contains filtered or unexported fields
}
WatcherCh provides a channel api for a file-system watcher
func NewWatcherCh ¶ added in v0.4.141
func NewWatcherCh( filter Op, ignores *regexp.Regexp, errFn func(err error), ) (watcherCh *WatcherCh)
NewWatcherCh returns a file-system watcher using channel mechanic
- filter WatchOpAll (default: 0) is: Create Write Remove Rename Chmod. it can also be a bit-coded value.
- ignores is a regexp for the absolute filename. it is applied while scanning directories.
- errFn must be thread-safe.
- stores self-referencing pointers
- consumers are expected to use:
- — NewIterator using a Go for-statement iterative api
- — NewWatcherCh using Go channel api
- — NewWatcher using callback api
Usage:
var watcherCh = watchfs.NewWatcherCh(watchfs.WatchOpAll, watchfs.NoIgnores, g.AddError)
defer watcherCh.Shutdown()
if err = watcherCh.Watch(path); err != nil {…
for any := range watcherCh.Ch() {
event, events := watchfs.UnpackEvents(any)
func (*WatcherCh) Get ¶ added in v0.4.141
func (w *WatcherCh) Get() (watchEvent *WatchEvent, watchEvents []*WatchEvent)
Get receives one or more watch events
- blocks until an event is available or the watcher ends. For non-blocking designs, use WatcherCh.Ch
- if watchEvent non-nil, it is the single event returned
- if len(watchEvents) > 0, it holds 2 or more returned events
- if watchEvent and watchEvents are both nil, the watcher has ended
- Thread-safe
type WatcherShim ¶ added in v0.4.141
type WatcherShim struct {
// unique ID 1…
ID uint64
// contains filtered or unexported fields
}
Watcher shim interfaces fsnotify.Watcher
- purpose is to completely encapsulate fsnotify implementation
- portable callback api
- errFn receives:
- — streamed fsnotify api errors
- — eventFunc callback errors
- — runtime errors and
- — fsnotify api close errors
- WatcherShim.Watch launches 2 threads listening to the api channels
- WatcherShim.Add watches individual paths. A watched directory does not watch entries in its subdirectories
- Watcher.Shutdown must be invoked after successful Watch to release resources. Shutdown does not return until resources are released
func NewWatcherShim ¶ added in v0.4.141
func NewWatcherShim( fieldp *WatcherShim, eventFunc func(name string, op Op, t time.Time) (err error), errFn func(err error), ) (watcherShim *WatcherShim)
NewWatcherShim returns a file system watcher using portable types
- NewWatcherShim is an abstraction hiding the file-system watch implementation. Consumers are expected to use:
- — NewIterator using a Go for-statement iterative api
- — NewWatcherCh using Go channel api
- — NewWatcher using callback api
- on any error, the watcherShim shuts down
- WatcherShim.Watch starts watching
- WatcherShim.Add watches a a path
- WatcherShim.List lists watched paths
- WatcherShim.Shutdown must be invoked to release resources
func (*WatcherShim) Add ¶ added in v0.4.141
func (w *WatcherShim) Add(name string) (err error)
Add adds a path for watching
- if anything amiss, error
func (*WatcherShim) List ¶ added in v0.4.141
func (w *WatcherShim) List() (paths []string)
List returns the currently watched paths. Thread-Safe
- if watcher not open or errored or shutdown: nil
func (*WatcherShim) Shutdown ¶ added in v0.4.141
func (w *WatcherShim) Shutdown()
Shutdown closes the watcher
- does not return prior to watcher closed and resources released
- thread-safe
func (*WatcherShim) Watch ¶ added in v0.4.141
func (w *WatcherShim) Watch() (err error)
Watch starts the Watcher. Thread-safe
- may only be invoked once
- fsnotify.NewWatcher launches goroutines
- on success, launches 2 goroutines and sets state to shimOpen
Source Files
Click to show internal directories.
Click to hide internal directories.