|
6 | 6 | //! [dependencies] |
7 | 7 | //! notify = "6.0.0" |
8 | 8 | //! ``` |
9 | | -//! |
| 9 | +//! |
10 | 10 | //! If you want debounced events, see [notify-debouncer-mini](https://github.com/notify-rs/notify/tree/main/notify-debouncer-mini) |
11 | 11 | //! or [notify-debouncer-full](https://github.com/notify-rs/notify/tree/main/notify-debouncer-full). |
12 | | -//! |
| 12 | +//! |
13 | 13 | //! ## Features |
14 | | -//! |
| 14 | +//! |
15 | 15 | //! List of compilation features, see below for details |
16 | | -//! |
| 16 | +//! |
17 | 17 | //! - `serde` for serialization of events |
18 | 18 | //! - `macos_fsevent` enabled by default, for fsevent backend on macos |
19 | 19 | //! - `macos_kqueue` for kqueue backend on macos |
|
26 | 26 | //! ```toml |
27 | 27 | //! notify = { version = "6.0.0", features = ["serde"] } |
28 | 28 | //! ``` |
29 | | -//! |
| 29 | +//! |
30 | 30 | //! ### Crossbeam-Channel & Tokio |
31 | | -//! |
| 31 | +//! |
32 | 32 | //! By default crossbeam-channel is used internally by notify. |
33 | 33 | //! This can [cause issues](https://github.com/notify-rs/notify/issues/380) when used inside tokio. |
34 | | -//! |
| 34 | +//! |
35 | 35 | //! You can disable crossbeam-channel, letting notify fallback to std channels via |
36 | | -//! |
| 36 | +//! |
37 | 37 | //! ```toml |
38 | 38 | //! notify = { version = "6.0.0", default-features = false, features = ["macos_kqueue"] } |
39 | 39 | //! // Alternatively macos_fsevent instead of macos_kqueue |
40 | 40 | //! ``` |
41 | 41 | //! Note the `macos_kqueue` requirement here, otherwise no backend is available on macos. |
42 | | -//! |
| 42 | +//! |
43 | 43 | //! # Known Problems |
44 | | -//! |
| 44 | +//! |
45 | 45 | //! ### Docker with Linux on MacOS M1 |
46 | | -//! |
| 46 | +//! |
47 | 47 | //! Docker on macos M1 [throws](https://github.com/notify-rs/notify/issues/423) `Function not implemented (os error 38)`. |
48 | 48 | //! You have to manually use the [PollWatcher], as the native backend isn't available inside the emulation. |
49 | | -//! |
| 49 | +//! |
50 | 50 | //! ### MacOS, FSEvents and unowned files |
51 | | -//! |
| 51 | +//! |
52 | 52 | //! Due to the inner security model of FSEvents (see [FileSystemEventSecurity](https://developer.apple.com/library/mac/documentation/Darwin/Conceptual/FSEvents_ProgGuide/FileSystemEventSecurity/FileSystemEventSecurity.html)), |
53 | 53 | //! some events cannot be observed easily when trying to follow files that do not |
54 | 54 | //! belong to you. In this case, reverting to the pollwatcher can fix the issue, |
55 | 55 | //! with a slight performance cost. |
56 | | -//! |
| 56 | +//! |
57 | 57 | //! ### Editor Behaviour |
58 | | -//! |
| 58 | +//! |
59 | 59 | //! If you rely on precise events (Write/Delete/Create..), you will notice that the actual events |
60 | 60 | //! can differ a lot between file editors. Some truncate the file on save, some create a new one and replace the old one. |
61 | 61 | //! See also [this](https://github.com/notify-rs/notify/issues/247) and [this](https://github.com/notify-rs/notify/issues/113#issuecomment-281836995) issues for example. |
62 | 62 | //! |
63 | 63 | //! ### Parent folder deletion |
64 | | -//! |
| 64 | +//! |
65 | 65 | //! If you want to receive an event for a deletion of folder `b` for the path `/a/b/..`, you will have to watch its parent `/a`. |
66 | 66 | //! See [here](https://github.com/notify-rs/notify/issues/403) for more details. |
67 | | -//! |
| 67 | +//! |
68 | 68 | //! ### Pseudo Filesystems like /proc,/sys |
69 | | -//! |
| 69 | +//! |
70 | 70 | //! Some filesystems like `/proc` and `/sys` on *nix do not emit change events or use correct file change dates. |
71 | 71 | //! To circumvent that problem you can use the [PollWatcher] with the `compare_contents` option. |
72 | | -//! |
| 72 | +//! |
73 | 73 | //! ### Linux: Bad File Descriptor / No space left on device |
74 | | -//! |
| 74 | +//! |
75 | 75 | //! This may be the case of running into the max-files watched limits of your user or system. |
76 | 76 | //! (Files also includes folders.) Note that for recursive watched folders each file and folder inside counts towards the limit. |
77 | | -//! |
| 77 | +//! |
78 | 78 | //! You may increase this limit in linux via |
79 | 79 | //! ```sh |
80 | 80 | //! sudo sysctl fs.inotify.max_user_instances=8192 # example number |
81 | 81 | //! sudo sysctl fs.inotify.max_user_watches=524288 # example number |
82 | 82 | //! sudo sysctl -p |
83 | 83 | //! ``` |
84 | | -//! |
| 84 | +//! |
85 | 85 | //! Note that the [PollWatcher] is not restricted by this limitation, so it may be an alternative if your users can't increase the limit. |
86 | | -//! |
| 86 | +//! |
87 | 87 | //! # Examples |
88 | | -//! |
| 88 | +//! |
89 | 89 | //! For more examples visit the [examples folder](https://github.com/notify-rs/notify/tree/main/examples) in the repository. |
90 | 90 | //! |
91 | 91 | //! ```rust,no_exec |
|
0 commit comments