vendor/github.com/rjeczalik/notify/watcher.go

   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 }