APIs stabilization metabug

[alexcrichton]

We will eventually need a process for API stabilization planning and discussion, but while we're first getting used to the 6 week cadence, we'll use this issue for tracking.

Planned for 1.0 stable

• [x] str::Utf8Error (switch from enum to opaque struct, with accessor for "last valid byte position")
• [x] io::Error::from_raw_os_error
• [x] Clone::clone_from (likely)

  Planned for 1.1 beta

• [x] str_words -- see #15628

  Planned for 1.1 stable

• [ ] thread::catch_panic
• [ ] time::Duration
• [x] debug builders
• [ ] collections::Bound
• [ ] One/Zero + .sum / .product
• [ ] iter::StepBy -- decide what to do on a negative step
• [ ] Box::from_raw, boxed::into_raw
• [ ] char::encode_utf{8,16}

  APIs with known problems/requiring more thought

• [ ] iter::order -- would prefer to use comparison operators
• [ ] alloc::heap -- huge risks for future tracing support etc.
• [ ] IteratorExt::{min,max}_by -- #15311
• [ ] <[_]>::position_elem
• [ ] #[bench] -- want more pluggable framework
• [ ] std::slice::bytes -- wants more design work
• [ ] char::width
• [ ] Read::chars -- has problematic error type; should this even be provided given how slow it is?
• [ ] iter::range_inclusive -- replace with adapters
• [ ] collections::{BitVec, VecMap} -- need clearer policy on what ships in collections
• [ ] mem::copy{,_mut}_lifetime, ptr::Unique -- wants more general design for "safer unsafe patterns"

  Slated for eventual deprecation/removal (if unstable)

• [ ] Vec::push_all
• [ ] Vec::from_raw_buf
• [ ] FromPrimitive/ToPrimitive/NumCast (will be replaced with more general failable cast)

  Far-future

• [ ] raw::TraitObject
• [ ] intrinsics::volatile_set_memory
• [ ] intrinsics::type_name

[daboross]

@BurntSushi Oh, I guess they are. For some reason I assumed that there would have to be some custom implementations of Into like there were listed on IntoCow<> for it to work, but Into<Cow<'static, str>> seems to work fine. Thanks!

[TyOverby]

@SimonSapin In unicode, I'm just using the str::utf8_char_witdth function.

[dirvine]

I would like to add a request for std::sync::Weak if at all possible.

[carllerche]

I need Error::from_os_error. This allows me to convert from a nix error -> io::Error

This is actually really important to me because right now there is no way to create an io::Error without allocating, which isn't really appropriate for libraries like mio.

[cgaebel]

The following need to be stabilized before I can ship iobuf working on rustc beta:

test::{black_box, Bencher} alloc::heap::allocate alloc::heap::deallocate core::nonzero #![feature(unsafe_no_drop_flag)] needs to either be stabilized, or removed. There will be a perf cost if removed before non-filling drop lands.

[bfops]

I get the impression the entry API was never really stabilized? entry should take a reference to a key, and only do a (potentially expensive) clone when VacantEntry::insert is called.

[daboross]

@carllerche Does io::Error::last_os_error() not do what is needed? It literally just calls from_os_error with the last error. I'm not experienced with working with system APIs at all, but I think that might be usable for a situation where you have a nix error.

[carllerche]

@daboross it does not. By the time I need it, There is no guarantee that the last error is the right one.

[daboross]

Ah, ok - just wondering, thanks!

[wackywendell]

I have now run into needing something like stepBy in two different crates. Is there a stable way of doing (1..10).step_by that isn't too annoying?

[ruuda]

A program of mine is blocked on AdditiveIterator. A library of mine is blocked on AdditiveIterator and From/ToPrimitive. AdditiveIterator can easily be worked around, but it would be nice to have.

[aturon]

It's going to take a few release cycles before we fully hit our stride and have a good process for stabilization planning. For the time being, I've cleaned up this issue after discussion with @alexcrichton. This should now give you a clearer picture for the immediate plans.

[drewcrawford]

Is there any way to get separate issues to track these? I want to subscribe to like 3 of them but I don't want to pile on with everybody who wants every API stabilized in one issue.

[SimonSapin]

str_words -- see #15628

Please see https://github.com/rust-lang/rfcs/pull/1054

[bstrie]

std::rc::Weak. The reason given for instability, "weak pointers may not belong in this module", seems easy enough to address. An example of a project blocked on this: https://github.com/aepsil0n/carboxyl/issues/47 (from http://blog.ebopp.de/blog/2015/04/23/interactive-2d-apps/).

[strega-nil]

Vote for collections::VecMap, it's really useful one of my projects.

[TyOverby]

Another vote for VecMap.

[nwin]

It is a while since I looked last time into this issue, but is the current plan really to remove push_all(slice). Only to replace it with extend(slice.iter().cloned()) or extend(slice.iter().map(|&v| v))? That looks overly verbose and ambiguous.

[bluss]

There's an RFC to make .extend(slice) work (while still keeping the present extend impls too). We need that as soon as possble.

[bluss]

I'd propose these as APIs with problems:

• slice::permutations, Permutations, ElementSwaps
• slice::next_permutation, slice::prev_permutation

They have unclear performance impact and utility. Possible candidates for moving to a third party crate.

As noted on the forum thread, on my wishlist for (not far) future stabilization:

• intrinsics::unreachable
• slice::clone_from_slice
  • We don't have a simple method to copy data from one slice to another. Of course, we need this to be a memmove when possible.

[abonander]

I can't build img_hash on Stable without BitVec unless it gets externalized.

[abonander]

Also need UnsafeCell::value

[bluss]

@cybergeek94 bitvec is now on crates.io, crate bit-vec (also bit-set)

[TyOverby]

I'd also really like net::lookup_host.

[reem]

@bluss and others, the unreachable crates.io crate now provides a works-on-stable version of intrinsics::unreachable based on the void crate and should have a similar affect on code generation.

[strega-nil]

Could we add core::nonzero::NonZero to the list, to add to std and stabilize? It's super useful, and I can't think of any reason to not stabilize it. It's not like it will change.

[bluss]

@alexcrichton @reem The adjustments to new llvm in issue #26025 might affect the codegen for match Void { /* empty */ }, it least changes the IR emitted.

Edit: Seems fine, though

[eddyb]

@GBGamer NonZero doesn't have a serious API at the moment, there's no way the current hacky state would be stabilized.

[strega-nil]

@eddyb It would be nice to at least re-export from std, if possible, even if it is unstable. Having to extern crate core is just an annoyance that could easily be fixed.

Also, what kind of API could we design around NonZero? Serious question, I can't think of anything besides new(x: T) //-> panics if x is zero and new_unchecked(x: T) // UB if x is zero.

[eddyb]

@GBGamer first off, the Deref impl is just broken, it doesn't really fit attaching metadata to loads the way it's supposed to be. A get method (like Cell has) is much better suited.

And then, there's the following constructor:

impl<T: Zeroable> NonZero<T> {
    fn new(x: T) -> Option<NonZero<T>> {
        if x.is_zero() {
            None
        } else {
            Some(NonZero(x))
        }
    }
}

Completely safe, should compile down to nothing, and the panic behaviour you describe could be achieved by just calling .unwrap() on the result.

It could be used like this:

extern {
    fn malloc(NonZero<usize>) -> *mut u8;
}

fn oom() -> ! { print_oom_message(); abort() }

const EMPTY: *mut u8 = 1 as *mut u8;
fn alloc(size: usize) -> NonZero<*mut u8> {
    NonZero::new(size).map_or(EMPTY, |size| {
        NonZero::new(malloc(size)).or_else(oom)
    })
}

[strega-nil]

@eddyb alright, makes total sense. I would like to start working on that soon, then, perhaps after finals.

On Tue, Jun 16, 2015 at 11:26 PM, Eduard Burtescu notifications@github.com wrote:

@GBGamer https://github.com/GBGamer first off, the Deref impl is just broken, it doesn't really fit attaching metadata to loads the way it's supposed to be. A get method (like Cell has) is much better suited.

And then, there's the following constructor:

impl NonZero { fn new(x: T) -> Option<NonZero> { if x.is_zero() { None } else { Some(NonZero(x)) } } }

Completely safe, should compile down to nothing, and the panic behaviour you describe could be achieved by just calling .unwrap() on the result.

It could be used like this:

extern { fn malloc(NonZero) -> _mut u8; } fn oom() -> ! { print_oom_message(); abort() } const EMPTY: mut u8 = 1 as mut u8;fn alloc(size: usize) -> NonZero<_mut u8> { NonZero::new(size).map_or(EMPTY, |size| { NonZero::new(malloc(size)).or_else(oom) }) }

— Reply to this email directly or view it on GitHub https://github.com/rust-lang/rust/issues/24028#issuecomment-112670509.

"Unjust laws exist; shall we be content to obey them, or shall we endeavor to amend them, and obey them until we have succeeded, or shall we transgress them at once?" -- Henry David Thoreau

[abonander]

Is there anything blocking the new static methods on Rc from being stabilized? There's no notes for them.

[abonander]

Same with slice::position_elem.

[bluss]

@cybergeek94 For position_elem I just guess that it's related to the want for a more extended searching API for slices. For string slices we have patterns, and you can .find() a char, substring, set of chars etc. The question is what we want to do with &[_] and stabilizing position_elem is affected by that.

[mitsuhiko]

Not sure if this is the right place to bring it up, but catch_panic seems a bit misplaced in the thread module given that it does not actually have anything directly to do with threads. Would it not make sense to put this somewhere else? I thought from reading the docs that it spawns a thread and captures the panic.

[sfackler]

That's what it used to do! But yeah, it should probably be moved (maybe to ffi?)

[aturon]

Discussion of catch_panic is here.

[aturon]

I'm going to close this issue out in favor of per-feature tracking issues, which have now been created for the bulk of unstable std APIs. Please comment on the individual issues with your use cases, stabilization desire, and feedback!