File lock API

[cberner]

Proposal

Problem statement

Provide an API to lock files (i.e. flock)

Motivating examples or use cases

redb contains unsafe code and requires a dependency on libc to lock and unlock files, as well as implementations for both Linux and Windows.

It looks like Cargo similarly has its own file locking code.

Having a file lock API for each platform, similar to the existing support for raw fds and API likes read_exact_at, would allow std to be used instead of unsafe invocations of libc.

Solution sketch

I have two ideas, but would be happy to implement any API that's desired:

1. A trait like std::os::unix::fs::FileExt that contains lock() and unlock() APIs.
2. A LockedFile struct, which own a File object and ensure that the lock was released with a Drop implementation, and provide accessors to the file.

Alternatives

I've worked around it by using the libc crate

Links and related work

• Link to Cargo's FileLock implementation

What happens now?

This issue contains an API change proposal (or ACP) and is part of the libs-api team feature lifecycle. Once this issue is filed, the libs-api team will review open proposals as capability becomes available. Current response times do not have a clear estimate, but may be up to several months.

Possible responses

The libs team may respond in various different ways. First, the team will consider the problem (this doesn't require any concrete solution or alternatives to have been proposed):

• We think this problem seems worth solving, and the standard library might be the right place to solve it.
• We think that this probably doesn't belong in the standard library.

Second, if there's a concrete solution:

• We think this specific solution looks roughly right, approved, you or someone else should implement this. (Further review will still happen on the subsequent implementation PR.)
• We're not sure this is the right solution, and the alternatives or other materials don't give us enough information to be sure about that. Here are some questions we have that aren't answered, or rough ideas about alternatives we'd want to see discussed.

[Amanieu]

We discussed this in the libs-api meeting today. We agree that file locking should be supporting in the standard library. However these should be directly exposed on File rather than in OS-specific traits. This makes the API more useful for users who need simple file locking support and OSes without such support can just return ErrorKind::Unsupported.

Here's an API overview:

impl File {
    fn lock(&self) -> io::Result<()>;
    fn lock_shared(&self) -> io::Result<()>;
    fn try_lock(&self) -> io::Result<bool>;
    fn try_lock_shared(&self) -> io::Result<bool>;
    fn unlock(&self) -> io::Result<()>;
}

These should be carefully documented to ensure they work on all platforms. For example:

• We don't make any guarantees as to whether the lock is advisory or mandatory.
• Double check behavior when recursively locking the same file.
• All locks are dropped when the file is closed. However cloning a file (via dup or DuplicateHandle) keeps the file open.
• etc.

Feel free to open a tracking issue and open a PR to rust-lang/rust to add it as an unstable feature.

[cberner]

Sounds good. Thanks for the feedback!