There are hundreds of stackoverflow answers, reddit posts and blog
articles that link to these documents, so it's a nicer user experience
if they're not plain 404s.
The intention is to let these hang around only for relatively short
while. The alpha is likely to bring in many new users and they will be
reading the documents mentioned above.
This pulls all of our long-form documentation into a single document,
nicknamed "the book" and formally titled "The Rust Programming
Language."
A few things motivated this change:
* People knew of The Guide, but not the individual Guides. This merges
them together, helping discoverability.
* You can get all of Rust's longform documentation in one place, which
is nice.
* We now have rustbook in-tree, which can generate this kind of
documentation. While its style is basic, the general idea is much
better: a table of contents on the left-hand side.
* Rather than a almost 10,000-line guide.md, there are now smaller files
per section.
This pass performs a second pass of stabilization through the `std::sync`
module, avoiding modules/types that are being handled in other PRs (e.g.
mutexes, rwlocks, condvars, and channels).
The following items are now stable
* `sync::atomic`
* `sync::atomic::ATOMIC_BOOL_INIT` (was `INIT_ATOMIC_BOOL`)
* `sync::atomic::ATOMIC_INT_INIT` (was `INIT_ATOMIC_INT`)
* `sync::atomic::ATOMIC_UINT_INIT` (was `INIT_ATOMIC_UINT`)
* `sync::Once`
* `sync::ONCE_INIT`
* `sync::Once::call_once` (was `doit`)
* C == `pthread_once(..)`
* Boost == `call_once(..)`
* Windows == `InitOnceExecuteOnce`
* `sync::Barrier`
* `sync::Barrier::new`
* `sync::Barrier::wait` (now returns a `bool`)
* `sync::Semaphore::new`
* `sync::Semaphore::acquire`
* `sync::Semaphore::release`
The following items remain unstable
* `sync::SemaphoreGuard`
* `sync::Semaphore::access` - it's unclear how this relates to the poisoning
story of mutexes.
* `sync::TaskPool` - the semantics of a failing task and whether a thread is
re-attached to a thread pool are somewhat unclear, and the
utility of this type in `sync` is question with respect to
the jobs of other primitives. This type will likely become
stable or move out of the standard library over time.
* `sync::Future` - futures as-is have yet to be deeply re-evaluated with the
recent core changes to Rust's synchronization story, and will
likely become stable in the future but are unstable until
that time comes.
[breaking-change]
This commit is part of a series that introduces a `std::thread` API to
replace `std::task`.
In the new API, `spawn` returns a `JoinGuard`, which by default will
join the spawned thread when dropped. It can also be used to join
explicitly at any time, returning the thread's result. Alternatively,
the spawned thread can be explicitly detached (so no join takes place).
As part of this change, Rust processes now terminate when the main
thread exits, even if other detached threads are still running, moving
Rust closer to standard threading models. This new behavior may break code
that was relying on the previously implicit join-all.
In addition to the above, the new thread API also offers some built-in
support for building blocking abstractions in user space; see the module
doc for details.
Closes#18000
[breaking-change]
https://github.com/rust-lang/rfcs/pull/221
The current terminology of "task failure" often causes problems when
writing or speaking about code. You often want to talk about the
possibility of an operation that returns a Result "failing", but cannot
because of the ambiguity with task failure. Instead, you have to speak
of "the failing case" or "when the operation does not succeed" or other
circumlocutions.
Likewise, we use a "Failure" header in rustdoc to describe when
operations may fail the task, but it would often be helpful to separate
out a section describing the "Err-producing" case.
We have been steadily moving away from task failure and toward Result as
an error-handling mechanism, so we should optimize our terminology
accordingly: Result-producing functions should be easy to describe.
To update your code, rename any call to `fail!` to `panic!` instead.
Assuming you have not created your own macro named `panic!`, this
will work on UNIX based systems:
grep -lZR 'fail!' . | xargs -0 -l sed -i -e 's/fail!/panic!/g'
You can of course also do this by hand.
[breaking-change]
1000 tasks * 2MiB stack size -> 2GiB of virtual memory
On a 64-bit OS, a 32-bit executable has 4GiB available, but the kernel
gets half of the available address space so the limit is 2GiB on 32-bit.
Closes#17044
This cleans up blatant lies in the concurrency guide, and modernizes it
a bit. There's a lot more to do, but until I get to it, let's make it a
little bit better.
* channel() - #[unstable]. This will likely remain forever
* sync_channel(n: int) - #[unstable with comment]. Concerns have ben raised
about the usage of the term "synchronous channel" because that generally only
applies to the case where n == 0. If n > 0 then these channels are often
referred to as buffered channels.
* Sender::send(), SyncSender::send(), Receiver::recv() - #[experimental]. These
functions directly violate the general guideline of not providing a failing
and non-failing variant. These functions were explicitly selected for being
excused from this guideline, but recent discussions have cast doubt on that
decision. These functions are #[experimental] for now until a decision is made
as they are candidates for removal.
* Sender::send_opt(), SyncSender::send_opt(), Receiver::recv_opt() - #[unstable
with a comment]. If the above no-`_opt` functions are removed, these functions
will be renamed to the non-`_opt` variants.
* SyncSender::try_send(), Receiver::try_recv() - #[unstable with a comment].
These return types of these functions to not follow general conventions. They
are consistent with the rest of the api, but not with the rest of the
libraries. Until their return types are nailed down, these functions are
#[unstable].
* Receiver::iter() - #[unstable]. This will likely remain forever.
* std::com::select - #[experimental]. The functionality is likely to remain in
some form forever, but it is highly unlikely to remain in its current form. It
is unknown how much breakage this will cause if and when the api is
redesigned, so the entire module and its components are all experimental.
* DuplexStream - #[deprecated]. This type is not composable with other channels
in terms of selection or other expected locations. It can also not be used
with ChanWriter and ChanReader, for example. Due to it being only lightly
used, and easily replaced with two channels, this type is being deprecated and
slated for removal.
* Clone for {,Sync}Sender - #[unstable]. This will likely remain forever.
This commit is the final step in the libstd facade, #13851. The purpose of this
commit is to move libsync underneath the standard library, behind the facade.
This will allow core primitives like channels, queues, and atomics to all live
in the same location.
There were a few notable changes and a few breaking changes as part of this
movement:
* The `Vec` and `String` types are reexported at the top level of libcollections
* The `unreachable!()` macro was copied to libcore
* The `std::rt::thread` module was moved to librustrt, but it is still
reexported at the same location.
* The `std::comm` module was moved to libsync
* The `sync::comm` module was moved under `sync::comm`, and renamed to `duplex`.
It is now a private module with types/functions being reexported under
`sync::comm`. This is a breaking change for any existing users of duplex
streams.
* All concurrent queues/deques were moved directly under libsync. They are also
all marked with #![experimental] for now if they are public.
* The `task_pool` and `future` modules no longer live in libsync, but rather
live under `std::sync`. They will forever live at this location, but they may
move to libsync if the `std::task` module moves as well.
[breaking-change]
This commit shuffles around some of the `rand` code, along with some
reorganization. The new state of the world is as follows:
* The librand crate now only depends on libcore. This interface is experimental.
* The standard library has a new module, `std::rand`. This interface will
eventually become stable.
Unfortunately, this entailed more of a breaking change than just shuffling some
names around. The following breaking changes were made to the rand library:
* Rng::gen_vec() was removed. This has been replaced with Rng::gen_iter() which
will return an infinite stream of random values. Previous behavior can be
regained with `rng.gen_iter().take(n).collect()`
* Rng::gen_ascii_str() was removed. This has been replaced with
Rng::gen_ascii_chars() which will return an infinite stream of random ascii
characters. Similarly to gen_iter(), previous behavior can be emulated with
`rng.gen_ascii_chars().take(n).collect()`
* {IsaacRng, Isaac64Rng, XorShiftRng}::new() have all been removed. These all
relied on being able to use an OSRng for seeding, but this is no longer
available in librand (where these types are defined). To retain the same
functionality, these types now implement the `Rand` trait so they can be
generated with a random seed from another random number generator. This allows
the stdlib to use an OSRng to create seeded instances of these RNGs.
* Rand implementations for `Box<T>` and `@T` were removed. These seemed to be
pretty rare in the codebase, and it allows for librand to not depend on
liballoc. Additionally, other pointer types like Rc<T> and Arc<T> were not
supported. If this is undesirable, librand can depend on liballoc and regain
these implementations.
* The WeightedChoice structure is no longer built with a `Vec<Weighted<T>>`,
but rather a `&mut [Weighted<T>]`. This means that the WeightedChoice
structure now has a lifetime associated with it.
* The `sample` method on `Rng` has been moved to a top-level function in the
`rand` module due to its dependence on `Vec`.
cc #13851
[breaking-change]
This commit moves reflection (as well as the {:?} format modifier) to a new
libdebug crate, all of which is marked experimental.
This is a breaking change because it now requires the debug crate to be
explicitly linked if the :? format qualifier is used. This means that any code
using this feature will have to add `extern crate debug;` to the top of the
crate. Any code relying on reflection will also need to do this.
Closes#12019
[breaking-change]
Most of the links I've removed are for types that don't exist anymore with the exception of `SendReceiver` though I'm not sure how useful it is to link to that without the accompanying `Receiver` and `Sender` and I don't know how useful those links are when they're discussed below and `channel`/`sync_channel` is on the `std::comm` page already linked.
Improve tutorial discussion of closures, e.g. with respect to type inference and variable capture.
Fix#13621
---- original description follows
I'd like this pulled to master if possible but if not I'd appreciate comments on what I need to change. I found the closures difficult to understand as they were so I tried to explain it so I would've had an easier time understanding it. I think it's better at least, somewhat.
I don't know that everyone liked the `-> ()` I included but I thought explicit is best to aid understanding. I thought it was much harder to understand than it should have been.
[EDIT] - Clicked too early.
This doesn't `make check` without errors on my Xubuntu on Virtualbox machine. Not sure why. I don't think I changed anything problematic. I'll try `make check` on master tomorrow.
Opened https://github.com/mozilla/rust/issues/13621 regarding this.
This primary fix brought on by this upgrade is the proper matching of the ```
and ~~~ doc blocks. This also moves hoedown to a git submodule rather than a
bundled repository.
Additionally, hoedown is stricter about code blocks, so this ended up fixing a
lot of invalid code blocks (ending with " ```" instead of "```", or ending with
"~~~~" instead of "~~~").
Closes#12776
This pull request:
- Merges the `Round` trait into the `Float` trait, continuing issue #10387.
- Has floating point functions take their parameters by value.
- Cleans up the formatting and organisation in the definition and implementations of the `Float` trait.
More information on the breaking changes can be found in the commit messages.
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 `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
