An initial section for libs docs

[KodrAus]

Recently in Libs we've been talking about putting together some docs with various things we try to keep in mind when working on std (inspired by .NET's runtime developer guide), and we thought the forge here would be a good home.

This PR is an attempt to bootstrap that doc. There's not a lot here yet, and what is there is probably both incomplete and plain incorrect :) It's just a starting point to iterate on, so any suggested corrections/enhancements would be greatly appreciated! Any thoughts on organization would also be good.

cc @rust-lang/libs

Rendered

[jonas-schievink]

I don't think this is limited to generics, right? Can't adding a second impl of some trait always cause inference failures, regardless of whether any of the impls is generic?

[KodrAus]

Ah, I was mostly thinking of the case here where we'll optimistically type things when there's only a single trait impl. Say we have something like:

impl From<&'_ str> for Arc<str> { .. }

let b = Arc::from("a");

then we add:

impl From<&'_ str> for Arc<str> { .. }
+ impl From<&'_ str> for Arc<String> { .. }

then

let b = Arc::from("a");

will no longer compile, because we're relying on inference to figure out the T in Box<T>. I think this sort of thing comes up every now and again with types like Arc, and in new FromIterator impls.

Can we think of any other examples of real inference breakage that could make this section more useful?

[KodrAus]

Another case to consider is deref coersion: rust-lang/rust#51916

[Centril]

cc @rust-lang/wg-unsafe-code-guidelines

[RalfJung]

Seems accurate in general. However, also see these UCG issues. And note that for some instances, we do guarantee things about destructors -- I am talking about the drop guarantee for pinned data. So, just because mem::forget is safe doesn't mean you can just drop arbitrary storage (like stack frames) without running the destructors. mem::forget leaks, that is okay -- but it doesn't deallocate without dropping, which is not (in general) okay.

[KodrAus]

Ah thanks, I wasn't familiar with the drop guarantee for Pin!

The kind of undesirable invariant I was trying to catch with this section was just along the same lines as Vec::drain. Maybe we should reword this one around whether or not there are manual impls for Drop, and some of the things to keep in mind there? Like remembering that leaking is a thing?

[RalfJung]

It is definitely worth mentioning that mem::forget is a thing, and that old Vec::drain and thread::spawn are unsound. But at the same time I think we should remind the reader that everything can leak does not imply that we can just deallocate any storage without calling destructors. This is an incorrect inference I have seen several people make.

[KodrAus]

So what we're saying here is that, in general, you can't guarantee an impl of Drop will get called, but you must ensure that an impl of Drop will get called if its storage is being deallocated/repourposed through something like ptr::write? And that's on the burden of the caller to ptr::write to enforce?

[RalfJung]

Yes. Calling all relevant Drop impls is a precondition to deallocating or repurposing storage.

Or, in other words: there is no guarantee that an impl of Drop will get called. However, if the impl of Drop does not get called, then the memory backing that instance of the type must leak.

Note that this is true in general, i.e., when working with arbitrary T. Under more controlled circumstances, skipping Drop can be fine -- e.g. if you know that there is definitely nothing pinned in that storage you are repurposing.

[alexcrichton]

Thanks for writing this all up @KodrAus!

[KodrAus]

@rust-lang/infra would you be comfortable with @rust-lang/libs pushing to this with impunity? I think we'd like to be able to treat it as a bit of a living document that we can tweak as things come up in a low-ceremony way.

[Mark-Simulacrum]

I think so (speaking personally). The forge is intended to be a place for the teams to gather together internal documentation for processes and other information. I personally think that edits should feel free to be made even without going through the PR process, though I also find that leads to breakage of CI frequently (seems like every time I try to sneak something in), so it may not be a good idea :) In some sense, it should be up to the team how y'all want to manage your pages on the forge.

I think the infra team is not strictly in charge of this area, too; I would feel free to proceed as you wish without gating on "us."

[KodrAus]

Thanks @Mark-Simulacrum! I guess we would need some permission tweaks then so that members of Libs could merge their PRs. I think it's fair to expect a PR to be opened (since that's straightforward to do in GitHub's UI already) and waiting for a green tick before merging.

[XAMPPRocky]

Thank you for your PR! While permissions are being sorted out, for now @KodrAus should we merge this in, so that it's public?

[Mark-Simulacrum]

I have granted the libs and compiler (while I'm at it) teams write access to this repository.