08ce178866
This commit is a reimplementation of `std::sync` to be based on the
system-provided primitives wherever possible. The previous implementation was
fundamentally built on top of channels, and as part of the runtime reform it has
become clear that this is not the level of abstraction that the standard level
should be providing. This rewrite aims to provide as thin of a shim as possible
on top of the system primitives in order to make them safe.
The overall interface of the `std::sync` module has in general not changed, but
there are a few important distinctions, highlighted below:
* The condition variable type, `Condvar`, has been separated out of a `Mutex`.
A condition variable is now an entirely separate type. This separation
benefits users who only use one mutex, and provides a clearer distinction of
who's responsible for managing condition variables (the application).
* All of `Condvar`, `Mutex`, and `RWLock` are now directly built on top of
system primitives rather than using a custom implementation. The `Once`,
`Barrier`, and `Semaphore` types are still built upon these abstractions of
the system primitives.
* The `Condvar`, `Mutex`, and `RWLock` types all have a new static type and
constant initializer corresponding to them. These are provided primarily for C
FFI interoperation, but are often useful to otherwise simply have a global
lock. The types, however, will leak memory unless `destroy()` is called on
them, which is clearly documented.
* The fundamental architecture of this design is to provide two separate layers.
The first layer is that exposed by `sys_common` which is a cross-platform
bare-metal abstraction of the system synchronization primitives. No attempt is
made at making this layer safe, and it is quite unsafe to use! It is currently
not exported as part of the API of the standard library, but the stabilization
of the `sys` module will ensure that these will be exposed in time. The
purpose of this layer is to provide the core cross-platform abstractions if
necessary to implementors.
The second layer is the layer provided by `std::sync` which is intended to be
the thinnest possible layer on top of `sys_common` which is entirely safe to
use. There are a few concerns which need to be addressed when making these
system primitives safe:
* Once used, the OS primitives can never be **moved**. This means that they
essentially need to have a stable address. The static primitives use
`&'static self` to enforce this, and the non-static primitives all use a
`Box` to provide this guarantee.
* Poisoning is leveraged to ensure that invalid data is not accessible from
other tasks after one has panicked.
In addition to these overall blanket safety limitations, each primitive has a
few restrictions of its own:
* Mutexes and rwlocks can only be unlocked from the same thread that they
were locked by. This is achieved through RAII lock guards which cannot be
sent across threads.
* Mutexes and rwlocks can only be unlocked if they were previously locked.
This is achieved by not exposing an unlocking method.
* A condition variable can only be waited on with a locked mutex. This is
achieved by requiring a `MutexGuard` in the `wait()` method.
* A condition variable cannot be used concurrently with more than one mutex.
This is guaranteed by dynamically binding a condition variable to
precisely one mutex for its entire lifecycle. This restriction may be able
to be relaxed in the future (a mutex is unbound when no threads are
waiting on the condvar), but for now it is sufficient to guarantee safety.
* Condvars support timeouts for their blocking operations. The
implementation for these operations is provided by the system.
Due to the modification of the `Condvar` API, removal of the `std::sync::mutex`
API, and reimplementation, this is a breaking change. Most code should be fairly
easy to port using the examples in the documentation of these primitives.
[breaking-change]
Closes #17094
Closes #18003
|
||
|---|---|---|
| man | ||
| mk | ||
| src | ||
| .gitattributes | ||
| .gitignore | ||
| .gitmodules | ||
| .mailmap | ||
| .travis.yml | ||
| AUTHORS.txt | ||
| configure | ||
| CONTRIBUTING.md | ||
| COPYRIGHT | ||
| LICENSE-APACHE | ||
| LICENSE-MIT | ||
| Makefile.in | ||
| README.md | ||
| RELEASES.md | ||
The Rust Programming Language
This is a compiler for Rust, including standard libraries, tools and documentation.
Quick Start
- Download a binary installer for your platform.
- Read the guide.
- Enjoy!
Note: Windows users can read the detailed using Rust on Windows notes on the wiki.
Building from Source
-
Make sure you have installed the dependencies:
g++4.7 orclang++3.xpython2.6 or later (but not 3.x)perl5.0 or later- GNU
make3.81 or later curlgit
-
Download and build Rust:
You can either download a tarball or build directly from the repo.
To build from the tarball do:
$ curl -O https://static.rust-lang.org/dist/rust-nightly.tar.gz $ tar -xzf rust-nightly.tar.gz $ cd rust-nightlyOr to build from the repo do:
$ git clone https://github.com/rust-lang/rust.git $ cd rustNow that you have Rust's source code, you can configure and build it:
$ ./configure $ make && make installNote: You may need to use
sudo make installif you do not normally have permission to modify the destination directory. The install locations can be adjusted by passing a--prefixargument toconfigure. Various other options are also supported, pass--helpfor more information on them.When complete,
make installwill place several programs into/usr/local/bin:rustc, the Rust compiler, andrustdoc, the API-documentation tool. -
Read the guide.
-
Enjoy!
Building on Windows
To easily build on windows we can use MSYS2:
-
Grab the latest MSYS2 installer and go through the installer.
-
Now from the MSYS2 terminal we want to install the mingw64 toolchain and the other tools we need.
$ pacman -S mingw-w64-i686-toolchain $ pacman -S base-devel -
With that now start
mingw32_shell.batfrom where you installed MSYS2 (i.e.C:\msys). -
From there just navigate to where you have Rust's source code, configure and build it:
$ ./configure $ make && make install
Notes
Since the Rust compiler is written in Rust, it must be built by a precompiled "snapshot" version of itself (made in an earlier state of development). As such, source builds require a connection to the Internet, to fetch snapshots, and an OS that can execute the available snapshot binaries.
Snapshot binaries are currently built and tested on several platforms:
- Windows (7, 8, Server 2008 R2), x86 and x86-64 (64-bit support added in Rust 0.12.0)
- Linux (2.6.18 or later, various distributions), x86 and x86-64
- OSX 10.7 (Lion) or greater, x86 and x86-64
You may find that other platforms work, but these are our officially supported build environments that are most likely to work.
Rust currently needs about 1.5 GiB of RAM to build without swapping; if it hits swap, it will take a very long time to build.
There is a lot more documentation in the wiki.
Getting help and getting involved
The Rust community congregates in a few places:
- StackOverflow - Get help here.
- /r/rust - General discussion.
- discuss.rust-lang.org - For development of the Rust language itself.
License
Rust is primarily distributed under the terms of both the MIT license and the Apache License (Version 2.0), with portions covered by various BSD-like licenses.
See LICENSE-APACHE, LICENSE-MIT, and COPYRIGHT for details.