Wait for file to be created

Rust crate implementing robust waiting for file to be created.

About

If your application has to wait for another application to create a file at certain path it's not entirely obvious how to do it without race conditions. This crate helps with that and provides a very simple API. See the shorthand functions provided in this crate first - you likely only need one of them.

It uses inotify which is available in Linux only to wait for the file. notify crate was specifically not used to ensure high robustness. PRs to add other platforms will be accepted if I can not see race conditions or other bugs in them.

Example

    use std::io::Read;

    let mut file = wait_file_created::robust_wait_read("my/expected/file").unwrap();
    let mut contents = String::new();
    file.read_to_string(&mut contents).unwrap();

As you can see the function returns an already-opened file which minimizes risk of race conditions. Unfortunately it can not be entirely elliminated in all scenarios.

Limitations

This library can not guarantee that the file opened was written completely. Specifically, if the application writing it has created it before your application attempted to open it but is still writing after that time then your application will observe incomplete data.

You must ensure that your application can handle incomplete data or (much better) ensure that the application creating the file does so atomically - that is create a temporary file first, write to it and then move it over to the final destination. The library is specifically designed to handle this scenario so you may rely on that.

Note that in Linux there is another mechanism for atomically creating files. A file can be opened using O_TMPFILE which creates an anonymous file. After populating it it can be linked to the directory using linkat() syscall.

If an application is using this method the notfication will only be received after the file descriptor is closed even though it would be safe to open it after it was created. The assume_create_is_atomic() method can be used to indicate that and request the file to be opened right away. This may improve performance or in case the application wants to keep the file descriptor opened it ensures the code functions at all. The same method can be used if the file is supposed to be empty.

License

MITNFA