Vec::try_with_capacity

[kornelski]

Related to #91913

Implements try_with_capacity for Vec, VecDeque, and String. I can follow it up with more collections if desired.

Vec::try_with_capacity() is functionally equivalent to the current stable:

let mut v = Vec::new();
v.try_reserve_exact(n)?

However, try_reserve calls non-inlined finish_grow, which requires old and new Layout, and is designed to reallocate memory. There is benefit to using try_with_capacity, besides syntax convenience, because it generates much smaller code at the call site with a direct call to the allocator. There's codegen test included.

It's also a very desirable functionality for users of no_global_oom_handling (Rust-for-Linux), since it makes a very commonly used function available in that environment (with_capacity is used much more frequently than all (try_)reserve(_exact)).

[rustbot]

r? @joshtriplett

(rustbot has picked a reviewer for you, use r? to override)

[the8472]

I has been a few months since something related came up but my understanding of the api team's position is that adding more try methods is going to face resistance until the fallible Vec / being-generic-over-fallibility question has been settled. Unless it's really important to have that method soon because it's hard to do it with existing code.

[kornelski]

I think this one method is relatively uncontroversial. The try_ pattern is already established. I don't think there are any alternatives to it in the foreseeable future. I'm proposing just try_with_capacity here, not doubling of the rest of the API surface.

Even if something as ambitious as the keyword generics initiative made progress, it's likely that you would still need some syntax to opt in to fallibility and to help type inference, and it's hard to beat the try_ prefix on that. So even if some fancy let v = Vec::<~try>::with_capacity()? became possible, try_with_capacity may remain as a convenient shortcut (similar to the desire to have .collect_vec(), despite the type system already being generic enough not to need that method).

The alternative designs that are possible today don't work well. FallibleVec as a trait doesn't play well with type inference, and a simple let v = FallibleVec::try_with_capacity(n)? doesn't compile.

Fallibility as a type, like TryVec, is incompatible with the ubiquitous Vec type. It's difficult to adopt, because it either requires converting back and forth with regular Vec on API boundaries, or it becomes "infectious" in APIs, like a lesser version of sync vs async APIs problem. Duplication of methods isn't as painful as duplication of types.

Rust currently has a third approach — no_global_oom_handling feature flag. with_capacity is not available in environments using it, like Rust-for-Linux. try_with_capacity brings this useful functionality to the strictly-OOM-handling environments.

[the8472]

I'm proposing just try_with_capacity here, not doubling of the rest of the API surface.

And the next person also only adds one more method 😉

[kornelski]

No, let's be serious. I don't think slippery slope applies here. For example, in #117503 I've added hints that make try_extend_from_slice, try_resize, try_append, and try_insert unnecessary.

Addition of try_with_capacity enables making DIY fallible versions of split_off and shrink_to_fit. Even though that takes a few lines of code, it's probably fine, because these are less used functions.

I don't think try_push is needed, because when used naively it can add a lot of reallocation and error checking overhead. And when allocations are amortized with something like try_with_capacity, then regular push can be safe to use. push_in_capacity or some other safe abstraction for filling spare_capacity_mut would work better.

[the8472]

I don't think slippery slope applies here.

I... see the picture differently. Several people have made RFCs and several PRs to add those APIs. Very large API surface, not just 1 or 2 methods. It's listed as a RfL wanted feature. There's an entire crew of slope connoisseurs just waiting to slide it down.
And I even agree that we should have a fallible interface! But I also think salami slicing (intentionally or not) doesn't get us a good design.

And this addition doesn't even seem all that valuable.

Addition of try_with_capacity enables making DIY fallible versions of split_off and shrink_to_fit.

You can do that also with new + try_reserve. Yeah, those won't optimize as well. But various other methods won't either without access to e.g. specialization. I understand the status quo sucks. But imo just one more method won't fix that.

[kornelski]

Those big PRs have been rejected or stalled, so we already know there's a limit to this slope.

This method enables several other Vec methods to become fallible at zero cost. Inclusion of this method could even be an argument against adding other try_ methods, because try_with_capacity() followed by another call can make it fallible for free. For example, try_vec![; n] is not necessary, because try_with_capacity()+resize() compiles to the same code.

Based on quick grep of this repo, outside of tests, there are 524 uses of .with_capacity, 278 uses of .reserve(_exact), 145 .shrink_to_fit, and 17 .split_off. Based on how common these methods are, it's easy to dismiss something like try_split_off as too niche. OTOH, with_capacity is used quite a lot, more than reserve. Given that we have a try_ version of reserve, IMHO it makes sense to have a try_ version of even more common with_capacity.

I think try_with_capacity is a good design for Rust. This method is so obvious that it's been proposed multiple times in the same form. Fallible APIs have been discussed a lot, RFCs have been open for years, and no perfect design has been found. Duplicate try_ methods are not elegant, but they're exceptionally simple and pragmatic. They're backwards-compatible with existing containers, and can be adopted gradually. They don't require any new syntax, and are still locally explicit. They don't require addition of more complex generics to Rust. They work fine with type inference as-is.

[Amanieu]

@bors r+

[bors]

📌 Commit 784e6a1 has been approved by Amanieu

It is now in the queue for this repository.

[Nadrieril]

This had a small perf impact

[Amanieu]

@kornelski Could you look into the perf regressions? This is most likely due to Vec::with_capacity now requiring more monomorphization/inlining, which increases compile times.