github.com/FabianKramm/notify@v0.9.3-0.20210719135015-4705c29227a1/notify.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 // BUG(rjeczalik): Notify does not collect watchpoints, when underlying watches 6 // were removed by their os-specific watcher implementations. Instead users are 7 // advised to listen on persistent paths to have guarantee they receive events 8 // for the whole lifetime of their applications (to discuss see #69). 9 10 // BUG(ppknap): Linux (inotify) does not support watcher behavior masks like 11 // InOneshot, InOnlydir etc. Instead users are advised to perform the filtering 12 // themselves (to discuss see #71). 13 14 // BUG(ppknap): Notify was not tested for short path name support under Windows 15 // (ReadDirectoryChangesW). 16 17 // BUG(ppknap): Windows (ReadDirectoryChangesW) cannot recognize which notification 18 // triggers FileActionModified event. (to discuss see #75). 19 20 package notify 21 22 var defaultTree = newTree() 23 24 // Watch sets up a watchpoint on path listening for events given by the events 25 // argument. 26 // 27 // File or directory given by the path must exist, otherwise Watch will fail 28 // with non-nil error. Notify resolves, for its internal purpose, any symlinks 29 // the provided path may contain, so it may fail if the symlinks form a cycle. 30 // It does so, since not all watcher implementations treat passed paths as-is. 31 // E.g. FSEvents reports a real path for every event, setting a watchpoint 32 // on /tmp will report events with paths rooted at /private/tmp etc. 33 // 34 // The c almost always is a buffered channel. Watch will not block sending to c 35 // - the caller must ensure that c has sufficient buffer space to keep up with 36 // the expected event rate. 37 // 38 // It is allowed to pass the same channel multiple times with different event 39 // list or different paths. Calling Watch with different event lists for a single 40 // watchpoint expands its event set. The only way to shrink it, is to call 41 // Stop on its channel. 42 // 43 // Calling Watch with empty event list does not expand nor shrink watchpoint's 44 // event set. If c is the first channel to listen for events on the given path, 45 // Watch will seamlessly create a watch on the filesystem. 46 // 47 // Notify dispatches copies of single filesystem event to all channels registered 48 // for each path. If a single filesystem event contains multiple coalesced events, 49 // each of them is dispatched separately. E.g. the following filesystem change: 50 // 51 // ~ $ echo Hello > Notify.txt 52 // 53 // dispatches two events - notify.Create and notify.Write. However, it may depend 54 // on the underlying watcher implementation whether OS reports both of them. 55 // 56 // Windows and recursive watches 57 // 58 // If a directory which path was used to create recursive watch under Windows 59 // gets deleted, the OS will not report such event. It is advised to keep in 60 // mind this limitation while setting recursive watchpoints for your application, 61 // e.g. use persistent paths like %userprofile% or watch additionally parent 62 // directory of a recursive watchpoint in order to receive delete events for it. 63 func Watch(path string, c chan<- EventInfo, events ...Event) error { 64 return defaultTree.Watch(path, c, events...) 65 } 66 67 // Stop removes all watchpoints registered for c. All underlying watches are 68 // also removed, for which c was the last channel listening for events. 69 // 70 // Stop does not close c. When Stop returns, it is guaranteed that c will 71 // receive no more signals. 72 func Stop(c chan<- EventInfo) { 73 defaultTree.Stop(c) 74 }