github.com/FabianKramm/notify@v0.9.3-0.20210719135015-4705c29227a1/watcher.go (about) 1 // Copyright (c) 2014-2015 The Notify Authors. All rights reserved. 2 // Use of this source code is governed by the MIT license that can be 3 // found in the LICENSE file. 4 5 package notify 6 7 import "errors" 8 9 var ( 10 errAlreadyWatched = errors.New("path is already watched") 11 errNotWatched = errors.New("path is not being watched") 12 errInvalidEventSet = errors.New("invalid event set provided") 13 ) 14 15 // Watcher is a intermediate interface for wrapping inotify, ReadDirChangesW, 16 // FSEvents, kqueue and poller implementations. 17 // 18 // The watcher implementation is expected to do its own mapping between paths and 19 // create watchers if underlying event notification does not support it. For 20 // the ease of implementation it is guaranteed that paths provided via Watch and 21 // Unwatch methods are absolute and clean. 22 type watcher interface { 23 // Watch requests a watcher creation for the given path and given event set. 24 Watch(path string, event Event) error 25 26 // Unwatch requests a watcher deletion for the given path and given event set. 27 Unwatch(path string) error 28 29 // Rewatch provides a functionality for modifying existing watch-points, like 30 // expanding its event set. 31 // 32 // Rewatch modifies existing watch-point under for the given path. It passes 33 // the existing event set currently registered for the given path, and the 34 // new, requested event set. 35 // 36 // It is guaranteed that Tree will not pass to Rewatch zero value for any 37 // of its arguments. If old == new and watcher can be upgraded to 38 // recursiveWatcher interface, a watch for the corresponding path is expected 39 // to be changed from recursive to the non-recursive one. 40 Rewatch(path string, old, new Event) error 41 42 // Close unwatches all paths that are registered. When Close returns, it 43 // is expected it will report no more events. 44 Close() error 45 } 46 47 // RecursiveWatcher is an interface for a Watcher for those OS, which do support 48 // recursive watching over directories. 49 type recursiveWatcher interface { 50 RecursiveWatch(path string, event Event) error 51 52 // RecursiveUnwatch removes a recursive watch-point given by the path. For 53 // native recursive implementation there is no difference in functionality 54 // between Unwatch and RecursiveUnwatch, however for those platforms, that 55 // requires emulation for recursive watch-points, the implementation differs. 56 RecursiveUnwatch(path string) error 57 58 // RecursiveRewatcher provides a functionality for modifying and/or relocating 59 // existing recursive watch-points. 60 // 61 // To relocate a watch-point means to unwatch oldpath and set a watch-point on 62 // newpath. 63 // 64 // To modify a watch-point means either to expand or shrink its event set. 65 // 66 // Tree can want to either relocate, modify or relocate and modify a watch-point 67 // via single RecursiveRewatch call. 68 // 69 // If oldpath == newpath, the watch-point is expected to change its event set value 70 // from oldevent to newevent. 71 // 72 // If oldevent == newevent, the watch-point is expected to relocate from oldpath 73 // to the newpath. 74 // 75 // If oldpath != newpath and oldevent != newevent, the watch-point is expected 76 // to relocate from oldpath to the newpath first and then change its event set 77 // value from oldevent to the newevent. In other words the end result must be 78 // a watch-point set on newpath with newevent value of its event set. 79 // 80 // It is guaranteed that Tree will not pass to RecurisveRewatcha zero value 81 // for any of its arguments. If oldpath == newpath and oldevent == newevent, 82 // a watch for the corresponding path is expected to be changed for 83 // non-recursive to the recursive one. 84 RecursiveRewatch(oldpath, newpath string, oldevent, newevent Event) error 85 }