Make all of the methods in `std::num::Float` take `self` and their other parameters by value.
Some of the `Float` methods took their parameters by value, and others took them by reference. This standardises them to one convention. The `Float` trait is intended for the built in IEEE 754 numbers only so we don't have to worry about the trait serving types of larger sizes.
[breaking-change]
The original text stated that one should only return a unique or managed pointer if you were given one in the first place. This makes it sound as if the function *should* return a unique pointer if it were given a unique pointer. The rest of the section goes on to describe why this is bad, and the example of bad code does exactly what the rule just said to do.
I reworded the original rule into a reference to the more concise rule mentioned at the bottom of the section, which helps add emphasis (a la 'it bears repeating').
This removes the `priv` keyword from the language and removes private enum
variants as a result. The remaining use cases of private enum variants were all
updated to be a struct with one private field that is a private enum.
RFC: 0006-remove-priv
Closes#13535
Before, the `--crate-file-name` flag only checked crate attributes for
possible crate types. Now, if any type is specified by one or more
`--crate-type` flags, only the filenames for those types will be
emitted, and any types specified by crate attributes will be ignored.
This is intended to be the first thing somebody new to the language reads about Rust. It is supposed to be simple and intriguing, to give the user an idea of whether Rust is appropriate for them, and to hint that there's a lot of cool stuff to learn if they just keep diving deeper.
I'm particularly happy with the sequence of concurrency examples.
Before, normal compilation and the --crate-file-name flag would
generate output based on both #![crate_type] attributes and
--crate-type flags. Now, if one or more flag is specified by command
line, only those will be used.
Closes#11573.
`Reader`, `Writer`, `MemReader`, `MemWriter`, and `MultiWriter` now work with `Vec<u8>` instead of `~[u8]`. This does introduce some extra copies since `from_utf8_owned` isn't usable anymore, but I think that can't be helped until `~str`'s representation changes.
In summary these are some example transitions this change makes:
'a || => ||: 'a
proc:Send() => proc():Send
The intended syntax for closures is to put the lifetime bound not at the front
but rather in the list of bounds. Currently there is no official support in the
AST for bounds that are not 'static, so this case is currently specially handled
in the parser to desugar to what the AST is expecting. Additionally, this moves
the bounds on procedures to the correct position, which is after the argument
list.
The current grammar for closures and procedures is:
procedure := 'proc' [ '<' lifetime-list '>' ] '(' arg-list ')'
[ ':' bound-list ] [ '->' type ]
closure := [ 'unsafe' ] ['<' lifetime-list '>' ] '|' arg-list '|'
[ ':' bound-list ] [ '->' type ]
lifetime-list := lifetime | lifetime ',' lifetime-list
arg-list := ident ':' type | ident ':' type ',' arg-list
bound-list := bound | bound '+' bound-list
bound := path | lifetime
This does not currently handle the << ambiguity in `Option<<'a>||>`, I am
deferring that to a later patch. Additionally, this removes the support for the
obsolete syntaxes of ~fn and &fn.
Closes#10553Closes#10767Closes#11209Closes#11210Closes#11211
Work on #13287
This is not ready for a merge yet, but I wanted to get some eyes on what I have done so far.
As of right now, all references in the text to managed boxes or pointers are removed. Code associated with those specific sections of text have likewise been altered. I also removed all references to managed closures.
There is a small change I would like to add to the work done in 3137cd5, on the new lines 1495 and 1496, I would like to change those values to 10 and 20. I did the same in a later change on lines 1596 and 1508.
There are still bits of sample code that use managed pointers and the sigil @. Those are next on my list to remove, but I wanted to have the outstanding changes reviewed first. The uses of @ in the code samples are a bit more embedded, and I will need to be more careful changing them as to not change the purpose of the code examples.
I ensured that make check still passes, although I'm not sure if that actually tests the code in tutorial.md.
One issues I ran into, and tried to avoid, was that `tutorial.md` is formatted with a nice column limit. I was unsure how this was enforced, so wherever I edited a line, I did my best to keep edits on the line they previously existed on. As such, the plain text of `tutorial.md` looks a bit strange as I've left it, and I will clean that up as suggested. The rendered markdown output should not be affected.
Closes#13285 (rustc: Stop using LLVMGetSectionName)
Closes#13280 (std: override clone_from for Vec.)
Closes#13277 (serialize: add a few missing pubs to base64)
Closes#13275 (Add and remove some ignore-win32 flags)
Closes#13273 (Removed managed boxes from libarena.)
Closes#13270 (Minor copy-editing for the tutorial)
Closes#13267 (fix Option<~ZeroSizeType>)
Closes#13265 (Update emacs mode to support new `#![inner(attribute)]` syntax.)
Closes#13263 (syntax: Remove AbiSet, use one Abi)
Note: "different to" is not exactly incorrect, but "different from" is more
commonly accepted in both US and Commonwealth English, and also more
consistent with other usage within this tutorial.
The `Float` trait methods will be usable as functions via UFCS, and
we came to a consensus to remove duplicate functions like this a long
time ago.
It does still make sense to keep the duplicate functions when the trait
methods are static, unless the decision to leave out the in-scope trait
name resolution for static methods changes.
The `Float` trait methods will be usable as functions via UFCS, and
we came to a consensus to remove duplicate functions like this a long
time ago.
It does still make sense to keep the duplicate functions when the trait
methods are static, unless the decision to leave out the in-scope trait
name resolution for static methods changes.
This fixes some problems with
make verify-grammar
llnextgen still reports a lot of errors
FYI: My build directory /my-test/build is different from the source directory /my-test/rust.
cd /my-test/build
/my-test/rust/configure --prefix=/my-test/bin
make
make install
make verify-grammar
Summary:
So far, we've used the term POD "Plain Old Data" to refer to types that
can be safely copied. However, this term is not consistent with the
other built-in bounds that use verbs instead. This patch renames the Pod
kind into Copy.
RFC: 0003-opt-in-builtin-traits
Test Plan: make check
Reviewers: cmr
Differential Revision: http://phabricator.octayn.net/D3
When calling
make verify-grammar
a lot of errors are reported by llnextgen.
Only simple errors like:
missing semicolons,
missing single quotes,
usage of parentheses instead of squared brackets or
usage of single quote instead of double quote
are fixed by this patch.
This can only be tested, when llnextgen is installed.
Signed-off-by: Jan Kobler <eng1@koblersystems.de>
When calling
make verify-grammar
or when llnextgen is not installed:
python2.7 src/etc/extract_grammar.py <src/doc/rust.md
an error is reported by extract_grammar.py that the
keyword "crate" is not defined.
This patch adds the keyword "crate" to the grammar in rust.md.
Signed-off-by: Jan Kobler <eng1@koblersystems.de>
* Include tip given by Leo Testard in mailing list about labeled `break`
and `continue`:
https://mail.mozilla.org/pipermail/rust-dev/2014-March/009145.html
* cross-reference named lifetimes in tutorial -> lifetimes guide
* Broke named lifetimes section into two sub-sections.
* Added mention of `'static` lifetime.
* Remove clone-ability from all primitives. All shared state will now come
from the usage of the primitives being shared, not the primitives being
inherently shareable. This allows for fewer allocations for stack-allocated
primitives.
* Add `Mutex<T>` and `RWLock<T>` which are stack-allocated primitives for purely
wrapping a piece of data
* Remove `RWArc<T>` in favor of `Arc<RWLock<T>>`
* Remove `MutexArc<T>` in favor of `Arc<Mutex<T>>`
* Shuffle around where things are located
* The `arc` module now only contains `Arc`
* A new `lock` module contains `Mutex`, `RWLock`, and `Barrier`
* A new `raw` module contains the primitive implementations of `Semaphore`,
`Mutex`, and `RWLock`
* The Deref/DerefMut trait was implemented where appropriate
* `CowArc` was removed, the functionality is now part of `Arc` and is tagged
with `#[experimental]`.
* The crate now has #[deny(missing_doc)]
* `Arc` now supports weak pointers
This is not a large-scale rewrite of the functionality contained within the
`sync` crate, but rather a shuffling of who does what an a thinner hierarchy of
ownership to allow for better composability.
While double-checking my understanding of the meaning of `'static`,
I made the following test program:
```rust
fn foo<X:'static>(_x: X) { }
#[cfg(not(acceptable))]
fn bar() {
let a = 3;
let b = &a;
foo(b);
}
#[cfg(acceptable)]
fn bar() {
static c : int = 4;;
let d : &'static int = &c;
foo(d);
}
fn main() {
bar();
}
```
Transcript of compiling above program, illustrating that the `--cfg
acceptable` variant of `bar` compiles successfully, showing that the
`'static` kind bound only disallows non-`static` references, not *all*
references:
```
% rustc --version
/Users/fklock/opt/rust-dbg/bin/rustc 0.10-pre (caf17fe 2014-03-21 02:21:50 -0700)
host: x86_64-apple-darwin
% rustc /tmp/s.rs
/tmp/s.rs:7:5: 7:8 error: instantiating a type parameter with an incompatible type `&int`, which does not fulfill `'static`
/tmp/s.rs:7 foo(b);
^~~
error: aborting due to previous error
% rustc --cfg acceptable /tmp/s.rs
% ./s
%
```
(Note that the explicit type annotation on `let d : &'static int` is
necessary; it did not suffice for me to just write `let d = &'static
c;`. That might be a latent bug, I am not sure yet.)
Anyway, a fix to the documentation seemed prudent.
* Include tip given by Leo Testard in mailing list about labeled `break`
and `continue`:
https://mail.mozilla.org/pipermail/rust-dev/2014-March/009145.html
* cross-reference named lifetimes in tutorial -> lifetimes guide
* Broke named lifetimes section into two sub-sections.
* Added mention of `'static` lifetime.
This commit switches over the backtrace infrastructure from piggy-backing off
the RUST_LOG environment variable to using the RUST_BACKTRACE environment
variable (logging is now disabled in libstd).
This commit moves all logging out of the standard library into an external
crate. This crate is the new crate which is responsible for all logging macros
and logging implementation. A few reasons for this change are:
* The crate map has always been a bit of a code smell among rust programs. It
has difficulty being loaded on almost all platforms, and it's used almost
exclusively for logging and only logging. Removing the crate map is one of the
end goals of this movement.
* The compiler has a fair bit of special support for logging. It has the
__log_level() expression as well as generating a global word per module
specifying the log level. This is unfairly favoring the built-in logging
system, and is much better done purely in libraries instead of the compiler
itself.
* Initialization of logging is much easier to do if there is no reliance on a
magical crate map being available to set module log levels.
* If the logging library can be written outside of the standard library, there's
no reason that it shouldn't be. It's likely that we're not going to build the
highest quality logging library of all time, so third-party libraries should
be able to provide just as high-quality logging systems as the default one
provided in the rust distribution.
With a migration such as this, the change does not come for free. There are some
subtle changes in the behavior of liblog vs the previous logging macros:
* The core change of this migration is that there is no longer a physical
log-level per module. This concept is still emulated (it is quite useful), but
there is now only a global log level, not a local one. This global log level
is a reflection of the maximum of all log levels specified. The previously
generated logging code looked like:
if specified_level <= __module_log_level() {
println!(...)
}
The newly generated code looks like:
if specified_level <= ::log::LOG_LEVEL {
if ::log::module_enabled(module_path!()) {
println!(...)
}
}
Notably, the first layer of checking is still intended to be "super fast" in
that it's just a load of a global word and a compare. The second layer of
checking is executed to determine if the current module does indeed have
logging turned on.
This means that if any module has a debug log level turned on, all modules
with debug log levels get a little bit slower (they all do more expensive
dynamic checks to determine if they're turned on or not).
Semantically, this migration brings no change in this respect, but
runtime-wise, this will have a perf impact on some code.
* A `RUST_LOG=::help` directive will no longer print out a list of all modules
that can be logged. This is because the crate map will no longer specify the
log levels of all modules, so the list of modules is not known. Additionally,
warnings can no longer be provided if a malformed logging directive was
supplied.
The new "hello world" for logging looks like:
#[phase(syntax, link)]
extern crate log;
fn main() {
debug!("Hello, world!");
}
This commit shreds all remnants of libextra from the compiler and standard
distribution. Two modules, c_vec/tempfile, were moved into libstd after some
cleanup, and the other modules were moved to separate crates as seen fit.
Closes#8784Closes#12413Closes#12576
docs: begin a "low-level & unsafe code" guide.
This aims to cover the basics of writing safe unsafe code. At the moment
it is just designed to be a better place for the `asm!()` docs than the
detailed release notes wiki page, and I took the time to write up some
other things.
More examples are needed, especially of things that can subtly go wrong;
and vast areas of `unsafe`-ty aren't covered, e.g. `static mut`s and
thread-safety in general.
This aims to cover the basics of writing safe unsafe code. At the moment
it is just designed to be a better place for the `asm!()` docs than the
detailed release notes wiki page, and I took the time to write up some
other things.
More examples are needed, especially of things that can subtly go wrong;
and vast areas of `unsafe`-ty aren't covered, e.g. `static mut`s and
thread-safety in general.
This commit shreds all remnants of libextra from the compiler and standard
distribution. Two modules, c_vec/tempfile, were moved into libstd after some
cleanup, and the other modules were moved to separate crates as seen fit.
Closes#8784Closes#12413Closes#12576
The `Float` trait provides correct `min` and `max` methods on floating
point types, providing a consistent result regardless of the order the
parameters are passed.
These generic functions do not take the necessary performance hit to
correctly support a partial order, so the true requirement should be
given as a type bound.
Closes#12712
The `Float` trait provides correct `min` and `max` methods on floating
point types, providing a consistent result regardless of the order the
parameters are passed.
These generic functions do not take the necessary performance hit to
correctly support a partial order, so the true requirement should be
given as a type bound.
Closes#12712
`prep.js` outputs its own HTML directives, which `pandoc` cannot
recognize when converting the document into LaTeX (this is why the
PDF docs have never been highlighted as of now).
Note that if we were to add the `.rust` class to snippets, we could
probably use pandoc's native highlighting capatibilities i.e. Kate.
parsing limitations.
Sundown parses
```
~~~
as a valid codeblock (i.e. mismatching delimiters), which made using
rustdoc on its own documentation impossible (since it used nested
codeblocks to demonstrate how testable codesnippets worked).
This modifies those snippets so that they're delimited by indentation,
but this then means they're tested by `rustdoc --test` & rendered as
Rust code (because there's no way to add `notrust` to
indentation-delimited code blocks). A comment is added to stop the
compiler reading the text too closely, but this unfortunately has to be
visible in the final docs, since that's the text on which the
highlighting happens.
This is meant to be compiling a crate, but the crate_id attribute seems
to be upsetting it if the attribute is actually on the crate. I.e. this
makes this test compile by putting the crate_id attribute on a function
and so it's ignored. Such a hack. :(
This converts it to be very similar to crates.mk, with a single list of
the documentation items creating all the necessary bits and pieces.
Changes include:
- rustdoc is used to render HTML & test standalone docs
- documentation building now obeys NO_REBUILD=1
- testing standalone docs now obeys NO_REBUILD=1
- L10N is slightly less broken (in particular, it shares dependencies
and code with the rest of the code)
- PDFs can be built for all documentation items, not just tutorial and
manual
- removes the obsolete & unused extract-tests.py script
- adjust the CSS for standalone docs to use the rustdoc syntax
highlighting
The changes are basically just because rustdoc runs tests/rendering on
more snippets by default (i.e. everything without a `notrust` tag), and
not anything significant.
This theoretically gives rustdoc the ability to render our guides,
tutorial and manual (not in practice, since the files themselves need to
be adjusted slightly to use Sundown-compatible functionality).
Fixes#11392.
Formatting via reflection has been a little questionable for some time now, and
it's a little unfortunate that one of the standard macros will silently use
reflection when you weren't expecting it. This adds small bits of code bloat to
libraries, as well as not always being necessary. In light of this information,
this commit switches assert_eq!() to using {} in the error message instead of
{:?}.
In updating existing code, there were a few error cases that I encountered:
* It's impossible to define Show for [T, ..N]. I think DST will alleviate this
because we can define Show for [T].
* A few types here and there just needed a #[deriving(Show)]
* Type parameters needed a Show bound, I often moved this to `assert!(a == b)`
* `Path` doesn't implement `Show`, so assert_eq!() cannot be used on two paths.
I don't think this is much of a regression though because {:?} on paths looks
awful (it's a byte array).
Concretely speaking, this shaved 10K off a 656K binary. Not a lot, but sometime
significant for smaller binaries.
Closes#12546 (Add new target 'make dist-osx' to create a .pkg installer for OS X) r=brson
Closes#12575 (rustc: Move local native libs back in link-args) r=brson
Closes#12587 (Provide a more helpful error for tests that fail due to noexec) r=brson
Closes#12589 (rustc: Remove codemap and reachable from metadata encoder) r=alexcrichton
Closes#12591 (Fix syntax::ext::deriving{,::*} docs formatting.) r=huonw
Closes#12592 (Miscellaneous Vim improvements) r=alexcrichton
Closes#12596 (path: Implement windows::make_non_verbatim()) r=alexcrichton
Closes#12598 (Improve the ctags function regular expression) r=alexcrichton
Closes#12599 (Tutorial improvement (new variant of PR #12472).) r=pnkfelix
Closes#12603 (std: Export the select! macro) r=pcwalton
Closes#12605 (Fix typo in doc of Binary trait in std::fmt) r=alexcrichton
Closes#12613 (Fix bytepos_to_file_charpos) r=brson
Refactoring examples on implementation of generics for linked list.
Fixing typo of 'Note's for coherancy.
Adding internal links inside the tutorial example with traits,
generics etc...
- "Lending an immutable pointer" might be confusing. It was not discussed why borrowed pointers are immutable in the first place.
- Make it clear that the borrowed pointers are immutable even if the variable was declared with `mut`.
- Make it clear that we cannot even assign anything to the variable while its value is being borrowed.
tutorial: change "--" to an em-dash.
tutorial: change instances of "--" to em-dash.
- "Lending an immutable pointer" might be confusing. It was not discussed why borrowed pointers are immutable in the first place.
- Make it clear that the borrowed pointers are immutable even if the variable was declared with `mut`.
- Make it clear that we cannot even assign anything to the variable while its value is being borrowed.
tutorial: change "--" to an em-dash.
tutorial: change instances of "--" to em-dash.
This commit changes the ToStr trait to:
impl<T: fmt::Show> ToStr for T {
fn to_str(&self) -> ~str { format!("{}", *self) }
}
The ToStr trait has been on the chopping block for quite awhile now, and this is
the final nail in its coffin. The trait and the corresponding method are not
being removed as part of this commit, but rather any implementations of the
`ToStr` trait are being forbidden because of the generic impl. The new way to
get the `to_str()` method to work is to implement `fmt::Show`.
Formatting into a `&mut Writer` (as `format!` does) is much more efficient than
`ToStr` when building up large strings. The `ToStr` trait forces many
intermediate allocations to be made while the `fmt::Show` trait allows
incremental buildup in the same heap allocated buffer. Additionally, the
`fmt::Show` trait is much more extensible in terms of interoperation with other
`Writer` instances and in more situations. By design the `ToStr` trait requires
at least one allocation whereas the `fmt::Show` trait does not require any
allocations.
Closes#8242Closes#9806
These two containers are indeed collections, so their place is in
libcollections, not in libstd. There will always be a hash map as part of the
standard distribution of Rust, but by moving it out of the standard library it
makes libstd that much more portable to more platforms and environments.
This conveniently also removes the stuttering of 'std::hashmap::HashMap',
although 'collections::HashMap' is only one character shorter.
This is PR is the beginning of a complete rewrite and ultimate removal of the `std::num::strconv` module (see #6220), and the removal of the `ToStrRadix` trait in favour of using the `std::fmt` functionality directly. This should make for a cleaner API, encourage less allocation, and make the implementation more comprehensible .
The `Formatter::{pad_integral, with_padding}` methods have also been refactored make things easier to understand.
The formatting tests for integers have been moved out of `run-pass/ifmt.rs` in order to provide more immediate feedback when building using `make check-stage2-std NO_REBUILD=1`.
Arbitrary radixes are now easier to use in format strings. For example:
~~~rust
assert_eq!(format!("{:04}", radix(3, 2)), ~"0011");
~~~
The benchmarks have been standardised between `std::num::strconv` and `std::num::fmt` to make it easier to compare the performance of the different implementations.
~~~
type | radix | std::num::strconv | std::num::fmt
======|=======|========================|======================
int | bin | 1748 ns/iter (+/- 150) | 321 ns/iter (+/- 25)
int | oct | 706 ns/iter (+/- 53) | 179 ns/iter (+/- 22)
int | dec | 640 ns/iter (+/- 59) | 207 ns/iter (+/- 10)
int | hex | 637 ns/iter (+/- 77) | 205 ns/iter (+/- 19)
int | 36 | 446 ns/iter (+/- 30) | 309 ns/iter (+/- 20)
------|-------|------------------------|----------------------
uint | bin | 1724 ns/iter (+/- 159) | 322 ns/iter (+/- 13)
uint | oct | 663 ns/iter (+/- 25) | 175 ns/iter (+/- 7)
uint | dec | 613 ns/iter (+/- 30) | 186 ns/iter (+/- 6)
uint | hex | 519 ns/iter (+/- 44) | 207 ns/iter (+/- 20)
uint | 36 | 418 ns/iter (+/- 16) | 308 ns/iter (+/- 32)
~~~
This is in preparation to remove the implementations of ToStrRadix in integers, and to remove the associated logic from `std::num::strconv`.
The parts that still need to be liberated are:
- `std::fmt::Formatter::runplural`
- `num::{bigint, complex, rational}`
Added allow(non_camel_case_types) to librustc where necesary
Tried to fix problems with non_camel_case_types outside rustc
fixed failing tests
Docs updated
Moved #[allow(non_camel_case_types)] a level higher.
markdown.rs reverted
Fixed timer that was failing tests
Fixed another timer
I just started learning Rust and the absence of an explanation of the for-loop in the beginning really bugged me about the tutorial. Hence I simply added these lines, where I would have expected them. I know that there is something later on in the section on traits. However, this simple iteration scheme feels like something that you should be aware of right away.
The 'do' keyword was deprecated in 0.10 #11868 , and is keep as
reserved keyword #12157 .
So the tutorial part about it doesn't make sense.
The spawning explanation was move into '15.2 Closure compatibility'.
The 'do' keyword was deprecated in 0.10 #11868 , and is keep as
reserved keyword #12157 .
So the tutorial part about it doesn't make sense.
The spawning explanation was move into '15.2 Closure compatibility'.
Fixing misspelling.
Thanks for precisions.
Moved from 15.2 to 15.1.
Fixed typo, and apply pnkfelix advices.
It's too easy to forget the `rust` tag to have a code example tested, and it's
far more common to have testable code than untestable code.
This alters rustdoc to have only two directives, `ignore` and `should_fail`. The
`ignore` directive ignores the code block entirely, and the `should_fail`
directive has been fixed to only fail the test if the code execution fails, not
also compilation.
This, the Nth rewrite of channels, is not a rewrite of the core logic behind
channels, but rather their API usage. In the past, we had the distinction
between oneshot, stream, and shared channels, but the most recent rewrite
dropped oneshots in favor of streams and shared channels.
This distinction of stream vs shared has shown that it's not quite what we'd
like either, and this moves the `std::comm` module in the direction of "one
channel to rule them all". There now remains only one Chan and one Port.
This new channel is actually a hybrid oneshot/stream/shared channel under the
hood in order to optimize for the use cases in question. Additionally, this also
reduces the cognitive burden of having to choose between a Chan or a SharedChan
in an API.
My simple benchmarks show no reduction in efficiency over the existing channels
today, and a 3x improvement in the oneshot case. I sadly don't have a
pre-last-rewrite compiler to test out the old old oneshots, but I would imagine
that the performance is comparable, but slightly slower (due to atomic reference
counting).
This commit also brings the bonus bugfix to channels that the pending queue of
messages are all dropped when a Port disappears rather then when both the Port
and the Chan disappear.
These are ancient. I removed a bunch of questions that are less relevant - or completely unrelevant, updated other entries, and removed things that are already better expressed elsewhere.
- Convert the formatting traits to `&self` rather than `_: &Self`
- Rejig `syntax::ext::{format,deriving}` a little in preparation
- Implement `#[deriving(Show)]`
Part of #8784
Changes:
- Everything labeled under collections in libextra has been moved into a new crate 'libcollection'.
- Renamed container.rs to deque.rs, since it was no longer 'container traits for extra', just a deque trait.
- Crates that depend on the collections have been updated and dependencies sorted.
- I think I changed all the imports in the tests to make sure it works. I'm not entirely sure, as near the end of the tests there was yet another `use` that I forgot to change, and when I went to try again, it started rebuilding everything, which I don't currently have time for.
There will probably be incompatibility between this and the other pull requests that are splitting up libextra. I'm happy to rebase once those have been merged.
The tests I didn't get to run should pass. But I can redo them another time if they don't.
This has been a long time coming. Conditions in rust were initially envisioned
as being a good alternative to error code return pattern. The idea is that all
errors are fatal-by-default, and you can opt-in to handling the error by
registering an error handler.
While sounding nice, conditions ended up having some unforseen shortcomings:
* Actually handling an error has some very awkward syntax:
let mut result = None;
let mut answer = None;
io::io_error::cond.trap(|e| { result = Some(e) }).inside(|| {
answer = Some(some_io_operation());
});
match result {
Some(err) => { /* hit an I/O error */ }
None => {
let answer = answer.unwrap();
/* deal with the result of I/O */
}
}
This pattern can certainly use functions like io::result, but at its core
actually handling conditions is fairly difficult
* The "zero value" of a function is often confusing. One of the main ideas
behind using conditions was to change the signature of I/O functions. Instead
of read_be_u32() returning a result, it returned a u32. Errors were notified
via a condition, and if you caught the condition you understood that the "zero
value" returned is actually a garbage value. These zero values are often
difficult to understand, however.
One case of this is the read_bytes() function. The function takes an integer
length of the amount of bytes to read, and returns an array of that size. The
array may actually be shorter, however, if an error occurred.
Another case is fs::stat(). The theoretical "zero value" is a blank stat
struct, but it's a little awkward to create and return a zero'd out stat
struct on a call to stat().
In general, the return value of functions that can raise error are much more
natural when using a Result as opposed to an always-usable zero-value.
* Conditions impose a necessary runtime requirement on *all* I/O. In theory I/O
is as simple as calling read() and write(), but using conditions imposed the
restriction that a rust local task was required if you wanted to catch errors
with I/O. While certainly an surmountable difficulty, this was always a bit of
a thorn in the side of conditions.
* Functions raising conditions are not always clear that they are raising
conditions. This suffers a similar problem to exceptions where you don't
actually know whether a function raises a condition or not. The documentation
likely explains, but if someone retroactively adds a condition to a function
there's nothing forcing upstream users to acknowledge a new point of task
failure.
* Libaries using I/O are not guaranteed to correctly raise on conditions when an
error occurs. In developing various I/O libraries, it's much easier to just
return `None` from a read rather than raising an error. The silent contract of
"don't raise on EOF" was a little difficult to understand and threw a wrench
into the answer of the question "when do I raise a condition?"
Many of these difficulties can be overcome through documentation, examples, and
general practice. In the end, all of these difficulties added together ended up
being too overwhelming and improving various aspects didn't end up helping that
much.
A result-based I/O error handling strategy also has shortcomings, but the
cognitive burden is much smaller. The tooling necessary to make this strategy as
usable as conditions were is much smaller than the tooling necessary for
conditions.
Perhaps conditions may manifest themselves as a future entity, but for now
we're going to remove them from the standard library.
Closes#9795Closes#8968
This has been a long time coming. Conditions in rust were initially envisioned
as being a good alternative to error code return pattern. The idea is that all
errors are fatal-by-default, and you can opt-in to handling the error by
registering an error handler.
While sounding nice, conditions ended up having some unforseen shortcomings:
* Actually handling an error has some very awkward syntax:
let mut result = None;
let mut answer = None;
io::io_error::cond.trap(|e| { result = Some(e) }).inside(|| {
answer = Some(some_io_operation());
});
match result {
Some(err) => { /* hit an I/O error */ }
None => {
let answer = answer.unwrap();
/* deal with the result of I/O */
}
}
This pattern can certainly use functions like io::result, but at its core
actually handling conditions is fairly difficult
* The "zero value" of a function is often confusing. One of the main ideas
behind using conditions was to change the signature of I/O functions. Instead
of read_be_u32() returning a result, it returned a u32. Errors were notified
via a condition, and if you caught the condition you understood that the "zero
value" returned is actually a garbage value. These zero values are often
difficult to understand, however.
One case of this is the read_bytes() function. The function takes an integer
length of the amount of bytes to read, and returns an array of that size. The
array may actually be shorter, however, if an error occurred.
Another case is fs::stat(). The theoretical "zero value" is a blank stat
struct, but it's a little awkward to create and return a zero'd out stat
struct on a call to stat().
In general, the return value of functions that can raise error are much more
natural when using a Result as opposed to an always-usable zero-value.
* Conditions impose a necessary runtime requirement on *all* I/O. In theory I/O
is as simple as calling read() and write(), but using conditions imposed the
restriction that a rust local task was required if you wanted to catch errors
with I/O. While certainly an surmountable difficulty, this was always a bit of
a thorn in the side of conditions.
* Functions raising conditions are not always clear that they are raising
conditions. This suffers a similar problem to exceptions where you don't
actually know whether a function raises a condition or not. The documentation
likely explains, but if someone retroactively adds a condition to a function
there's nothing forcing upstream users to acknowledge a new point of task
failure.
* Libaries using I/O are not guaranteed to correctly raise on conditions when an
error occurs. In developing various I/O libraries, it's much easier to just
return `None` from a read rather than raising an error. The silent contract of
"don't raise on EOF" was a little difficult to understand and threw a wrench
into the answer of the question "when do I raise a condition?"
Many of these difficulties can be overcome through documentation, examples, and
general practice. In the end, all of these difficulties added together ended up
being too overwhelming and improving various aspects didn't end up helping that
much.
A result-based I/O error handling strategy also has shortcomings, but the
cognitive burden is much smaller. The tooling necessary to make this strategy as
usable as conditions were is much smaller than the tooling necessary for
conditions.
Perhaps conditions may manifest themselves as a future entity, but for now
we're going to remove them from the standard library.
Closes#9795Closes#8968
This commit removes the -c, --emit-llvm, -s, --rlib, --dylib, --staticlib,
--lib, and --bin flags from rustc, adding the following flags:
* --emit=[asm,ir,bc,obj,link]
* --crate-type=[dylib,rlib,staticlib,bin,lib]
The -o option has also been redefined to be used for *all* flavors of outputs.
This means that we no longer ignore it for libraries. The --out-dir remains the
same as before.
The new logic for files that rustc emits is as follows:
1. Output types are dictated by the --emit flag. The default value is
--emit=link, and this option can be passed multiple times and have all options
stacked on one another.
2. Crate types are dictated by the --crate-type flag and the #[crate_type]
attribute. The flags can be passed many times and stack with the crate
attribute.
3. If the -o flag is specified, and only one output type is specified, the
output will be emitted at this location. If more than one output type is
specified, then the filename of -o is ignored, and all output goes in the
directory that -o specifies. The -o option always ignores the --out-dir
option.
4. If the --out-dir flag is specified, all output goes in this directory.
5. If -o and --out-dir are both not present, all output goes in the directory of
the crate file.
6. When multiple output types are specified, the filestem of all output is the
same as the name of the CrateId (derived from a crate attribute or from the
filestem of the crate file).
Closes#7791Closes#11056Closes#11667
This commit removes the -c, --emit-llvm, -s, --rlib, --dylib, --staticlib,
--lib, and --bin flags from rustc, adding the following flags:
* --emit=[asm,ir,bc,obj,link]
* --crate-type=[dylib,rlib,staticlib,bin,lib]
The -o option has also been redefined to be used for *all* flavors of outputs.
This means that we no longer ignore it for libraries. The --out-dir remains the
same as before.
The new logic for files that rustc emits is as follows:
1. Output types are dictated by the --emit flag. The default value is
--emit=link, and this option can be passed multiple times and have all
options stacked on one another.
2. Crate types are dictated by the --crate-type flag and the #[crate_type]
attribute. The flags can be passed many times and stack with the crate
attribute.
3. If the -o flag is specified, and only one output type is specified, the
output will be emitted at this location. If more than one output type is
specified, then the filename of -o is ignored, and all output goes in the
directory that -o specifies. The -o option always ignores the --out-dir
option.
4. If the --out-dir flag is specified, all output goes in this directory.
5. If -o and --out-dir are both not present, all output goes in the current
directory of the process.
6. When multiple output types are specified, the filestem of all output is the
same as the name of the CrateId (derived from a crate attribute or from the
filestem of the crate file).
Closes#7791Closes#11056Closes#11667
- `extra::json` didn't make the cut, because of `extra::json` required
dep on `extra::TreeMap`. If/when `extra::TreeMap` moves out of `extra`,
then `extra::json` could move into `serialize`
- `libextra`, `libsyntax` and `librustc` depend on the newly created
`libserialize`
- The extensions to various `extra` types like `DList`, `RingBuf`, `TreeMap`
and `TreeSet` for `Encodable`/`Decodable` were moved into the respective
modules in `extra`
- There is some trickery, evident in `src/libextra/lib.rs` where a stub
of `extra::serialize` is set up (in `src/libextra/serialize.rs`) for
use in the stage0 build, where the snapshot rustc is still making
deriving for `Encodable` and `Decodable` point at extra. Big props to
@huonw for help working out the re-export solution for this
extra: inline extra::serialize stub
fix stuff clobbered in rebase + don't reexport serialize::serialize
no more globs in libserialize
syntax: fix import of libserialize traits
librustc: fix bad imports in encoder/decoder
add serialize dep to librustdoc
fix failing run-pass tests w/ serialize dep
adjust uuid dep
more rebase de-clobbering for libserialize
fixing tests, pushing libextra dep into cfg(test)
fix doc code in extra::json
adjust index.md links to serialize and uuid library
