vendor/github.com/rjeczalik/notify/doc.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 implements access to filesystem events.
   6 //
   7 // Notify is a high-level abstraction over filesystem watchers like inotify,
   8 // kqueue, FSEvents, FEN or ReadDirectoryChangesW. Watcher implementations are
   9 // split into two groups: ones that natively support recursive notifications
  10 // (FSEvents and ReadDirectoryChangesW) and ones that do not (inotify, kqueue, FEN).
  11 // For more details see watcher and recursiveWatcher interfaces in watcher.go
  12 // source file.
  13 //
  14 // On top of filesystem watchers notify maintains a watchpoint tree, which provides
  15 // a strategy for creating and closing filesystem watches and dispatching filesystem
  16 // events to user channels.
  17 //
  18 // An event set is just an event list joint using bitwise OR operator
  19 // into a single event value.
  20 // Both the platform-independent (see Constants) and specific events can be used.
  21 // Refer to the event_*.go source files for information about the available
  22 // events.
  23 //
  24 // A filesystem watch or just a watch is platform-specific entity which represents
  25 // a single path registered for notifications for specific event set. Setting a watch
  26 // means using platform-specific API calls for creating / initializing said watch.
  27 // For each watcher the API call is:
  28 //
  29 //   - FSEvents: FSEventStreamCreate
  30 //   - inotify:  notify_add_watch
  31 //   - kqueue:   kevent
  32 //   - ReadDirectoryChangesW: CreateFile+ReadDirectoryChangesW
  33 //   - FEN:      port_get
  34 //
  35 // To rewatch means to either shrink or expand an event set that was previously
  36 // registered during watch operation for particular filesystem watch.
  37 //
  38 // A watchpoint is a list of user channel and event set pairs for particular
  39 // path (watchpoint tree's node). A single watchpoint can contain multiple
  40 // different user channels registered to listen for one or more events. A single
  41 // user channel can be registered in one or more watchpoints, recursive and
  42 // non-recursive ones as well.
  43 package notify