Tracking Issue for File lock API

[cberner]

Feature gate: #![feature(file_lock)]

This is a tracking issue for rust-lang/libs-team#412

This feature exposes advisory file locks on File. They allow a file handle to acquire an exclusive or shared file lock, which blocks other file handles to the same file from acquiring a conflicting lock. Some semantics are platform dependent, and these are documented in the API documentation.

Public API

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<()>;
}

Steps / History

• Implementation: Implement file_lock feature #130999
• Final comment period (FCP)¹
• Stabilization PR
  • Stabilize file_lock #136794

Unresolved Questions

• None yet.

Footnotes

1. https://std-dev-guide.rust-lang.org/feature-lifecycle/stabilization.html ↩

[workingjubilee]

apparently not supported on all tier 2 OS: #132921

[eric-seppanen]

Note that this triggers the unstable_name_collisions lint for code using the fs2/fs3/fs4 crates, all of which have a FileExt trait with methods called lock_shared, try_lock_shared, and unlock.

This lint fires on the 1.84 beta release, so there might be a number of people who discover this once 1.84 stable goes out.

[NilsIrl]

It would also be useful to atomically create and lock a file. This is possible on MacOS using the O_SHLOCK and O_EXLOCK flags on open and on Linux using O_TMPFILE.

[joshtriplett]

While there are more features we may want to add to this in the future, the current state of this seems useful, and works. Stabilizing it would let people who encounter the warnings about a future conflict switch to the new API.

Shall we stabilize the current File locking APIs?

@rfcbot merge

[rfcbot]

Team member @joshtriplett has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @m-ou-se

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[m-ou-se]

I'd like to see some documentation on the lock methods that make it clear that you don't need to manually unlock / that the lock is automatically unlocked when the File is dropped. Right now, that's only documented on the unlock method.

Other than that, the documentation could be made a lot less confusing by adding 'by another process' and 'by the same process' in a few places. Right now, the try methods say "Returns false if the file is locked.", but then go on to say it might deadlock if it's already locked. I assume the former should be "locked by another process" and the latter should be "locked by this process".

[m-ou-se]

The unlock method should document whether it's okay to call it if no locks are held.

If calling unlock() is only acceptable when a lock is actually held, this should probably be a Guard style of API. If it's always okay to call unlock(), the current design makes sense to me.

[m-ou-se]

I'm checking my box with the assumption that these are just small docs changes that we'll do during/before stabilization.

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[joshtriplett]

I've submitted #136288 which should address all the documentation requests.

@m-ou-se wrote:

I'd like to see some documentation on the lock methods that make it clear that you don't need to manually unlock / that the lock is automatically unlocked when the File is dropped. Right now, that's only documented on the unlock method.

Done.

Other than that, the documentation could be made a lot less confusing by adding 'by another process' and 'by the same process' in a few places. Right now, the try methods say "Returns false if the file is locked.", but then go on to say it might deadlock if it's already locked. I assume the former should be "locked by another process" and the latter should be "locked by this process".

"process" isn't the granularity here, but I've added clear distinctions about locks acquired via the same handle/descriptor (may deadlock) vs locks acquired via a different handle/descriptor (will block the blocking methods or make the try_ methods return Ok(false)). I've also clarified the return value documentation to avoid that ambiguity.

The unlock method should document whether it's okay to call it if no locks are held.

It's always safe to call (in the Rust sense). I've documented that it'll either return an error or return without doing anything. It'll never explode.

If calling unlock() is only acceptable when a lock is actually held, this should probably be a Guard style of API. If it's always okay to call unlock(), the current design makes sense to me.

It's always OK (unlike a mutex or similar). It'll never explode.

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.

[quininer]

I think this API needs more warnings for Windows, as LockFile might not be the right choice.
It has many inconsistencies with unix file lock, and using it blindly would be a mistake. like #54118 (comment) and LockFileEx Remarks .

Finally, i used share mode instead of file lock, which is similar to the open options api mentioned by #130994 (comment).

[joshtriplett]

@quininer I don't think share mode is close enough to things available on other platforms that we'd be able to build a common portable API around it, and it doesn't allow keeping a file open and only occasionally locking it. I'd be all for adding a "share mode" option to Windows' OpenOptionsExt, but that'd be a separate feature which we already have.

The issue with append-only files would be worth some documentation on the append method and the locking methods. I don't think that's a blocker. On some platforms, locking won't work at all.

The rest of the "remarks" section on LockFileEx doesn't seem to have any caveats that we should consider a blocker.

[quininer]

@joshtriplett We already have share_mode for Windows, which is good. :D

If the locking process opens the file a second time, it cannot access the specified region through this second handle until it unlocks the region.
Locking a portion of a file for exclusive access denies all other processes both read and write access to the specified region of the file.

This means that the windows file lock is different from unix file lock in that it is not a advisory lock and it blocks file access. This is rather different from what std document implies

Note, this is an advisory lock meant to interact with lock_shared, try_lock, try_lock_shared, and unlock.

I actually think the windows file lock is different enough from unix file lock that it should be in FileExt as well. Even if it isn't, there should be a more document warning.

[cberner]

@quininer the std documentation currently says Its interactions with other methods, such as [read] and [write] are platform specific, and it may or may not cause non-lockholders to block.

That's meant to say that the lock may be mandatory, depending on the platform (i.e. Windows). How would you make it more clear?

[quininer]

@cberner Ha, that's good enough. but I didn't realize it at first. :(

[joshtriplett]

I've clarified the documentation in #136876 to address all of these issues.

[ChrisDenton]

LockFileEx won't work with append only files. You'd need either need to add read or else use write and not append.

[joshtriplett]

@ChrisDenton That's exactly what I've written in #136876.