docs(std): clarify remove_dir_all errors

[philpax]

When using remove_dir_all, I assumed that the function was idempotent and that I could always call it to remove a directory if it existed. That's not the case and it bit me in production, so I figured I'd submit this to clarify the docs.

[rustbot]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @joshtriplett (or someone else) soon.

Please see the contribution instructions for more information.

[rustbot]

Hey! It looks like you've submitted a new PR for the library teams!

If this PR contains changes to any rust-lang/rust public library APIs then please comment with @rustbot label +T-libs-api -T-libs to tag it appropriately. If this PR contains changes to any unstable APIs please edit the PR description to add a link to the relevant API Change Proposal or create one if you haven't already. If you're unsure where your change falls no worries, just leave it as is and the reviewer will take a look and make a decision to forward on if necessary.

Examples of T-libs-api changes:

• Stabilizing library features
• Introducing insta-stable changes such as new implementations of existing stable traits on existing stable types
• Introducing new or changing existing unstable library APIs (excluding permanently unstable features / features without a tracking issue)
• Changing public documentation in ways that create new stability guarantees
• Changing observable runtime behavior of library APIs

[rbtcollins]

I'm a bit conflicted here. There are a number of other error cases documented at the linked functions. e.g. not being a directory, not having permissions to delete it and so on.

Perhaps instead of that specific a note it should say something like 'remove_dir_all will fail if remove_dir or remove_file fail on any of the paths including the root of the three being deleted?

[philpax]

Hm, that seems reasonable, but I'd want to draw particular attention to it failing if you try to delete a non-existent directory. Perhaps something like

remove_dir_all will fail if remove_dir or remove_file fail on any constituent paths, including the root path. As a result, the directory you are deleting must exist, which means this function is not idempotent.

Consider ignoring the error if validating the removal is not required for your use case.

[pitaj]

I'd prefer to change the behavior instead, if possible. Currently, it appears like this function can easily fail if multiple threads/processes are deleting things. create_dir_all was modified for a similar reason

[philpax]

That would also be fine with me, but what would be the desired behaviour be in the cases of a) another thread/process deleting something that this function is about to delete and b) another thread/process creating something that this function is not aware of in its deletion?

The answers to these seem like they might be difficult/OS-dependent.

[pitaj]

If the directory at path does not exist, immediately exit Ok.

a) another thread/process deleting something that this function is about to delete

Accept ErrorKind::NotFound as if the deletion succeeded.

b) another thread/process creating something that this function is not aware of in its deletion?

If something is created between the read_dir and remove_dir that causes the latter to fail with DirectoryNotEmpty, immediately return that Err.

[philpax]

Seems reasonable to me. I'm not in a position to fix up the implementations, but I'm fine with someone else implementing that.

[jyn514]

rust-lang/libs-team#170 has been closed; if I understand correctly, T-libs-api doesn't want to make that change. So I think this documentation change is an improvement :) Can you change the documentation to what you suggested in #105745 (comment) ? r=me with that done.

[philpax]

@rustbot review

(hope I did this right!)

[jyn514]

Thanks!

@bors r+ rollup

[bors]

📌 Commit d5d2785 has been approved by jyn514

It is now in the queue for this repository.