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

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

Planned for 1.1 beta

• str_words -- see #15628

Planned for 1.1 stable

• thread::catch_panic
• time::Duration
• 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

[alexcrichton]

triage: P-high (1.1)

[steveklabnik]

str_words is very small, might be worthwhile :)

[bstrie]

std::str::from_utf8 is marked stable, but it can return std::str::Utf8Error which is still unstable. Need to correct this oversight, as well as be sure to audit all stable functions to make sure their return types are stable.

[mitsuhiko]

push_all on vectors really needs to become stable. I'm trying to replace my uses with that extend/into_iter or iter/cloned dance currently and it's not just slow, it's also terrible to look at.

[BurntSushi]

I second @bstrie's suggestion of str::Utf8Error. It's definitely weird for that to be unstable.

Some nice-to-haves:

• char::width
• accessed and modified on fs::Metadata (I guess this is probably blocking on stabilizing some kind of Duration type.)

[kinghajj]

Any chance that alloc::heap can be made stable? The deque crate uses this to allocate its buffers.

[vhbit]

convert for passing Path -> OsStr -> CString -> C code.

[sfackler]

I'd like to stabilize the debug builders.

[mrmonday]

I'm not sure that this is the right place to mention it, but http://doc.rust-lang.org/std/io/struct.Error.html#method.from_os_error is marked with "unclear whether this function is necessary" - I would argue it is necessary for the following reasons:

• The standard library does not (and probably should not) provide abstractions for all OS APIs
• Many libraries/miscellaneous kernel modules (not just OS APIs) return OS error codes
• Third party libraries (i.e. not standard library) that wrap these APIs should be able to provide an API which is consistent with what the standard library offers (having to duplicate std::io::Error for each different library would be a shame).

Arguments against:

• Users could mistakenly try to use it for any FFI error codes, not just OS error codes, leading to confusion. I'm not sure if/how this could be avoided.

[skade]

I had to do a change because type_name is exported into std, but not marked stable. It's not that I absolutely need it, but I have a usecase for something with it's guarantees: a stable identifier for a specific type between versions. I'd prefer using it.

[pyfisch]

• FromPrimitive - e.g. casting from an integer to an enum

Great, that it will be added again. Hyper used it for both HTTP status codes and quality values, it was removed to make hyper run on beta. But Hyper also needs ToPrimitive, will this also stabilized, or is it planned to deprecate it?

[tomaka]

Read::chars is very useful when you want to lex/parse some UTF-8 input.

[mvdnes]

Something stabilizing #![no_std] and extern crate core; would be great.
For normal crates it isn't very useful, but it would be nice to compile my 'kernel' with a stable compiler.

Also the value field of UnsafeCell. This is necessary to create a static initializer. Constant expressions would also be able to solve this though

[nagisa]

accessed and modified on fs::Metadata (I guess this is probably blocking on stabilizing some kind of Duration type.)

Duration for an absolute time stamp sounds odd.

[mhristache]

I also need char::width

[apasel422]

std::collections::Bound and its variants have no stability marker, but I assume this is waiting on changes or additions to the Range types.

[jedisct1]

collections::BitVec would be nice to stabilize.

Also, what prevents core::iter::StepBy from being stabilized?

[dnaq]

std::intrinsics::volatile_set_memory

[skade]

test, because #[bench] requires "test::Bencher" for its function signatures.

[ghost]

std::sync::Semaphore

[SimonSapin]

str_words

I think we should just remove this one. It’s unclear what "a word" is or should be. Unicode has an entire document (UAX #29 Text Segmentation) with a non-trivial algorithm to standardize this, but I think an implementation of it belongs more on crates.io than in std.

Instead, we could have "split a string on whitespace" in std, based on char::is_whitespace. This is much less ambiguous. It could be either a stand-alone method, or a custom std::str::Pattern implementation to be used with str::split.

[skade]

I agree with @SimonSapin there. I think a good crates.io library is what we need. rust-lang/rfcs#797 (comment)

[anonova]

Vec::from_raw_buf

[skade]

@anonova This is quite well expressed by from_raw_parts combined with to_vec

use std::slice::from_raw_parts;
from_raw_parts(value, length as usize).to_vec()

[reem]

@skade that requires a copy of all the contents, which is often not desirable.

[jedisct1]

I would really love to see Vec::from_raw_buf() to be stabilized as well.

[ubsan]

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.

[ubsan]

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.

[ubsan]

@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)
    })
}

[ubsan]

@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<T: Zeroable> 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
#24028 (comment).

"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!