(Stability note: this feature depends on nightly rust and alpha releases of tokio 0.2 and futures 0.3. Maybe you want to hold off the merge until they are stable. In which case I will try to make sure that this PR is up to date.)

This is a minimal and straightforward update to make inotify up to date with std::task, async-await syntax and next versions of tokio and futures.

API changes

• EventStream is now a futures 0.3 Stream

  A futures 0.3 Stream can be used with async-await directly (cc #121). See the stream example.

• The buffer passed to the event_stream method is now required to be Unpin

Other changes

• Mandatory dependencies is minimized: only tokio-net, tokio-io and futures-core are mandatory dependencies. And for tokio-net unused features are disabled. The full tokio crate and futures-util are dev-dependencies.

• The crate is updated to 2018 edition, so that related tests and examples can be written in async/await.

• The CI config is modified to:

  • Run on nightly
  • Run with --no-default-features as well

This branch changes the implementation of Stream for EventStream to use mio and tokio_reactor to register interest in events on the Inotify file descriptor with the reactor, rather than using task::current().notify() to unpark the task in the executor when polling the fd would block.

Since the reactor is intended to drive all IO resources (such as the inotify FD) and to be the bridge between tasks in the executor and events from the OS, using PollEvented is a more correct way to implement the stream.

This branch shouldn't result in any noticeable changes in behaviour, but will hopefully allow tokio to manage Inotify's IO events more intelligently.

From Stack Overflow:

As noted above, inotify watch descriptor values are scoped per parent inotify file descriptor. This makes the use of [derive(Eq)] on WatchDescriptor highly questionable. Looks like a straight-up bug.

I haven't had the chance to look into the details myself so far, but this seems legit.

This commit improves the close-on-drop behaviour for file descriptors, by adding a FdGuard struct that wraps the file descriptor and is responsible for closing it when it is dropped. Rather than having an Inotify own an Arc<RawFd>, and be responsible for clsoing it, Inotify now owns an Arc<FdGuard>, and the FdGuard is responsible for closing the fd.

This allows us to share the file descriptor between an Inotify and an EventStream, and close the file descriptor only when the Arc is dropped (i.e., when both the Inotify and the EventStream are dropped). This makes the Inotify::into_event_stream I added in #103 unnecessary, so I've gone ahead and deprecated it.

I am using inotify with calloop and one issue I've noticed is the lack of ability to easily convert an event from the methods into an owned event to pass to calloop. Calloop gets kinda messy when an Event in an event source has a lifetime, so getting an owned copy is typically the best way around this issue.

I noticed the presence of into_ownedthat is only available with the streams api, I think we could convert this to delegate to an implementation of ToOwned and made always available.

I've made a new PR after breaking the previous one due to a clunky rebase/squash.

I've added the Hash to the WatchDescriptor struct, to allow it to be used for HashMap lookup.

[0, ..1024] syntax is now deprecated. Fixed using std::iter::repeat.

I tried out Vec::with_capacity instead and passing buffer.capacity() instead of buffer.len() to get rid of initializing the vec with zeros, but got a failed assertion from slice.rs, so I guess the initialization is necessary.

I've derived the Hash trait for WatchDescriptor, so it can be added to HashMaps and used for lookup.

I ran into difficulties while implementing inotify-rs in a project that watches a large number of files. Not being able to match an inotify::Event to a file in a database is crippling for me.

The current API offers both synchronous and asynchronous operation, but it would be better to do that based on futures-rs. I've looked into it, but decided to hold off for the moment, until I had a chance to learn a bit more about futures-rs and experience it from a user's perspective (as opposed to that of a library author).

I've heard of projects, for example Hyper, automatically generating changelogs from Git commits. I haven't looked into the details yet, but I understand that GitCop can be used to enforce the commit message format that's required for that.

Alright, I'm by no means done, but I thought I'd give you a chance to weigh in earlier, rather than later.

Changes

• INotify is no longer cloneable. Therefore the API is essentially single-threaded, enforced by ownership semantics.
• A new method closer() is introduced. Its return value enables asynchronous closing of the inotify fd.
  • To avoid any races, the actual closing is still done by whoever owns the corresponding INotify.
  • This only happens when wait_for_events() is called.
  • To allow wait_for_events() to react to asynchronous closing, it spins in an epoll loop with a smallish timeout.

TODO

• [ ] Look at available_events() wrt asynchronous closing. Currently it does not make sense, because the caller can't determine if the inotify fd was closed without calling a blocking method. Maybe expose the state?
• [ ] Figure out a good epoll timeout (10ms seems a bit high).
• [x] Go over all the unwrap() calls and figure out how to deal with the potential error conditions.
• [ ] More tests
• [ ] Documentation

(ref #28)

panic info:

   5: std::panicking::begin_panic
             at ~/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/std/src/panicking.rs:505:12
   6: tokio::io::driver::Handle::current
             at ~/.cargo/registry/src/github.com-1ecc6299db9ec823/tokio-0.3.5/src/io/driver/mod.rs:277:13
   7: tokio::io::async_fd::AsyncFd<T>::with_interest
             at ~/.cargo/registry/src/github.com-1ecc6299db9ec823/tokio-0.3.5/src/io/async_fd.rs:99:51
   8: tokio::io::async_fd::AsyncFd<T>::new
             at ~/.cargo/registry/src/github.com-1ecc6299db9ec823/tokio-0.3.5/src/io/async_fd.rs:89:9
   9: inotify::stream::EventStream<T>::new
             at ~/.cargo/registry/src/github.com-1ecc6299db9ec823/inotify-0.9.1/src/stream.rs:35:17
  10: inotify::inotify::Inotify::event_stream
             at ~/.cargo/registry/src/github.com-1ecc6299db9ec823/inotify-0.9.1/src/inotify.rs:406:9
  11: controller::sync::Notifier::watch::{{closure}}
             at ~/work/github/cita-cloud/controller_poc/src/sync.rs:128:26

related source code:

        let mut inotify = Inotify::init().expect("Failed to initialize inotify");

        let root_path = Path::new(&self.root);
        let mut wds = Vec::new();
        for dir in SYNC_FOLDERS.iter() {
            let path = root_path.join(dir);
            let wd = inotify.add_watch(path, WatchMask::MOVED_TO).unwrap();
            wds.push(wd);
        }

        let mut buffer = vec![0u8; 4096];
        let mut stream = inotify.event_stream(&mut buffer).unwrap();

        while let Some(event_or_error) = stream.next().await {

This happend when upgrade inotify to latest version (v0.9.1). After back to v0.8.3, it's ok.

(This includes changes from #134.)

This adds an async Inotify type. It has an async fn read_events (close #121):

    pub async fn read_events<'a>(&mut self, buffer: &'a mut [u8])
                           -> io::Result<Events<'a>>

that is basically the same as the original read_events function, but awaits on the read:

    {
        let num_bytes = self.fd.read(buffer).await?;

        if num_bytes == 0 {
            return Err(
                io::Error::new(
                    io::ErrorKind::UnexpectedEof,
                    "`read` return `0`, signaling end-of-file"
                )
            );
        }

        Ok(Events::new(Arc::downgrade(self.fd.get_ref()), buffer, num_bytes))
    }

This addresses the efficiency concern in #112: no additional allocation is required.

The documentation for Inotify::event_stream is out of date.

1. It talks about using an internal buffer, but it no longer does.
2. It could use examples showing the various usage scenarios.

The examples should document what kinds of values can be passes as a buffer. See this comment in #124 and this comment in #125 for more information.

Futures 0.3 will support the Async/Await syntax. One it reaches GA, Tokio will be next. We should investigate what it will require of us to support the new syntax and prepare ourselves for it.

Currently there are two parallel APIs: The original one, and the new future-based one. I think it would be ideal if we could unify those.

One problem I see is efficiency. The stream-based API requires one additional heap allocation for every event that has a name. The reason for this are lifetime issues that probably can't be resolved, at least not in safe Rust.

I think it's best for now to keep things as they are, while keeping a look at how futures develop. Feedback is very welcome!

That would imply to use a select on the inotify's fd waiting for data in the fd or the timeout.

The workaround would be to use the nix crate with Inotify's RawFD and do the select in the application.