Merge pull request #368 from nikomatsakis/semver-policy

adopt stricter semver policy around unstable features

.travis.yml

@@ -15,24 +15,24 @@ env:
 matrix:
   include:
   - rust: stable
-    env: FEATURES=unstable
+    env: RUSTFLAGS='--cfg rayon_unstable'
     os: linux
   - rust: stable
-    env: FEATURES=unstable
+    env: RUSTFLAGS='--cfg rayon_unstable'
     os: osx
   - rust: nightly
-    env: FEATURES=unstable
+    env: RUSTFLAGS='--cfg rayon_unstable'
     os: linux
   - rust: nightly
-    env: FEATURES=unstable
+    env: RUSTFLAGS='--cfg rayon_unstable'
     os: osx
 
 script:
-  - cargo build --features="$FEATURES"
+  - cargo build
   - |
     if [ $TRAVIS_RUST_VERSION == nightly ]; then
-      cargo test --features="$FEATURES" &&
-      cargo test --features="$FEATURES" -p rayon-core &&
-      cargo test --features="$FEATURES" -p rayon-demo &&
+      cargo test &&
+      cargo test -p rayon-core &&
+      cargo test -p rayon-demo &&
       ./ci/highlander.sh
     fi

Cargo.toml

@@ -21,8 +21,3 @@ docopt = "0.7"
 futures = "0.1.7"
 rand = "0.3"
 rustc-serialize = "0.3"
-
-[features]
-# Unstable APIs that have not yet
-# proven their utility.
-unstable = ["rayon-core/unstable"]

README.md

@@ -32,6 +32,33 @@ integers, please see the [notes on atomicity](#atomicity).
 
 Rayon currently requires `rustc 1.12.0` or greater.
 
+### Using Rayon
+
+[Rayon is available on crates.io](https://crates.io/crates/rayon). The
+recommended way to use it is to add a line into your Cargo.toml such
+as:
+
+```rust
+[dependencies]
+rayon = 0.8.0
+```
+
+and then add the following to to your `lib.rs`:
+
+```rust
+extern crate rayon;
+```
+
+To use the Parallel Iterator APIs, a number of traits have to be in
+scope. The easiest way to bring those things into scope is to use the
+[Rayon prelude](https://docs.rs/rayon/*/rayon/prelude/index.html).
+In each module where you would like to use the parallel iterator APIs,
+just add:
+
+```rust
+use rayon::prelude::*;
+```
+
 ### Contribution
 
 Rayon is an open source project! If you'd like to contribute to Rayon, check out [the list of "help wanted" issues](https://github.com/nikomatsakis/rayon/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22). These are all (or should be) issues that are suitable for getting started, and they generally include a detailed set of instructions for what to do. Please ask questions if anything is unclear! Also, check out the [Guide to Development](https://github.com/nikomatsakis/rayon/wiki/Guide-to-Development) page on the wiki. Note that all code submitted in PRs to Rayon is assumed to [be licensed under Rayon's dual MIT/Apache2 licensing](https://github.com/nikomatsakis/rayon/blob/master/README.md#license).
@@ -395,6 +422,34 @@ fn search(path: &Path, cost_so_far: usize, best_cost: &Arc<AtomicUsize>) {
 Now in this case, we really WANT to see results from other threads
 interjected into our execution!
 
+## Semver policy, the rayon-core crate, and unstable features
+
+Rayon follows semver versioning. However, we also have APIs that are
+still in the process of development and which may break from release
+to release -- those APIs are not subject to semver. To use them,
+you have to set the cfg flag `rayon_unstable`. The easiest way to do this
+is to use the `RUSTFLAGS` environment variable:
+
+```
+RUSTFLAGS='--cfg rayon_unstable' cargo build
+```
+
+Note that this must not only be done for your crate, but for any crate
+that depends on your crate. This infectious nature is intentional, as
+it serves as a reminder that you are outside of the normal semver
+guarantees. **If you see unstable APIs that you would like to use,
+please request stabilization on the correspond tracking issue!**
+
+Rayon itself is internally split into two crates. The `rayon` crate is
+intended to be the main, user-facing crate, and hence all the
+documentation refers to `rayon`. This crate is still evolving and
+regularly goes through (minor) breaking changes. The `rayon-core`
+crate contains the global thread-pool and defines the core APIs: we no
+longer permit breaking changes in this crate (except to unstable
+features). The intention is that multiple semver-incompatible versions
+of the rayon crate can peacefully coexist; they will all share one
+global thread-pool through the `rayon-core` crate.
+
 ## License
 
 Rayon is distributed under the terms of both the MIT license and the

appveyor.yml

@@ -8,19 +8,19 @@ environment:
       CHANNEL: stable
     - TARGET: x86_64-pc-windows-gnu
       CHANNEL: stable
-      FEATURES: unstable
+      RUSTFLAGS: --cfg rayon_unstable
 
     - TARGET: x86_64-pc-windows-gnu
       CHANNEL: beta
     - TARGET: x86_64-pc-windows-gnu
       CHANNEL: beta
-      FEATURES: unstable
+      RUSTFLAGS: --cfg rayon_unstable
 
     - TARGET: x86_64-pc-windows-gnu
       CHANNEL: nightly
     - TARGET: x86_64-pc-windows-gnu
       CHANNEL: nightly
-      FEATURES: unstable
+      RUSTFLAGS: --cfg rayon_unstable
 
 
     - TARGET: x86_64-pc-windows-msvc
@@ -30,19 +30,19 @@ environment:
       CHANNEL: stable
     - TARGET: x86_64-pc-windows-msvc
       CHANNEL: stable
-      FEATURES: unstable
+      RUSTFLAGS: --cfg rayon_unstable
 
     - TARGET: x86_64-pc-windows-msvc
       CHANNEL: beta
     - TARGET: x86_64-pc-windows-msvc
       CHANNEL: beta
-      FEATURES: unstable
+      RUSTFLAGS: --cfg rayon_unstable
 
     - TARGET: x86_64-pc-windows-msvc
       CHANNEL: nightly
     - TARGET: x86_64-pc-windows-msvc
       CHANNEL: nightly
-      FEATURES: unstable
+      RUSTFLAGS: --cfg rayon_unstable
 
 install:
   - curl -sSf -o rustup-init.exe https://win.rustup.rs
@@ -54,8 +54,8 @@ install:
 build: false
 
 test_script:
-  - cargo build --features="%FEATURES%"
+  - cargo build
   - if [%CHANNEL%]==[nightly] (
-      cargo test --features="%FEATURES%" -p rayon-core &&
-      cargo test --features="%FEATURES%" -p rayon-demo
+      cargo test -p rayon-core &&
+      cargo test -p rayon-demo
     )

examples/cpu_monitor.rs

@@ -77,16 +77,16 @@ fn task_stall_root(args: &Args) {
     rayon::join(|| task(args), || wait_for_user());
 }
 
-#[cfg(feature = "unstable")]
+#[cfg(rayon_unstable)]
 fn task_stall_scope(args: &Args) {
     rayon::scope(|scope| {
                      scope.spawn(move |_| task(args));
                      scope.spawn(move |_| wait_for_user());
                  });
 }
 
-#[cfg(not(feature = "unstable"))]
+#[cfg(not(rayon_unstable))]
 fn task_stall_scope(_args: &Args) {
-    println!("try `cargo run` with `--features unstable`");
+    println!("try `RUSTFLAGS='--cfg rayon_unstable' cargo run`");
     process::exit(1);
 }

rayon-core/Cargo.toml

@@ -16,11 +16,8 @@ num_cpus = "1.2"
 coco = "0.1.1"
 libc = "0.2.16"
 lazy_static = "0.2.2"
-futures = { version = "0.1.7", optional = true }
 
-[dev-dependencies]
+# only if #[cfg(rayon_unstable)], will be removed eventually
+futures = "0.1.7"
 
-[features]
-# Unstable APIs that have not yet
-# proven their utility.
-unstable = ["futures"]
+[dev-dependencies]

rayon-core/src/lib.rs

@@ -38,7 +38,7 @@ use std::fmt;
 extern crate coco;
 #[macro_use]
 extern crate lazy_static;
-#[cfg(feature = "unstable")]
+#[cfg(rayon_unstable)]
 extern crate futures;
 extern crate libc;
 extern crate num_cpus;
@@ -51,11 +51,11 @@ mod latch;
 mod join;
 mod job;
 mod registry;
-#[cfg(feature = "unstable")]
+#[cfg(rayon_unstable)]
 mod future;
 mod scope;
 mod sleep;
-#[cfg(feature = "unstable")]
+#[cfg(rayon_unstable)]
 mod spawn;
 mod test;
 mod thread_pool;
@@ -67,11 +67,11 @@ pub use thread_pool::current_thread_index;
 pub use thread_pool::current_thread_has_pending_tasks;
 pub use join::join;
 pub use scope::{scope, Scope};
-#[cfg(feature = "unstable")]
+#[cfg(rayon_unstable)]
 pub use spawn::spawn;
-#[cfg(feature = "unstable")]
+#[cfg(rayon_unstable)]
 pub use spawn::spawn_future;
-#[cfg(feature = "unstable")]
+#[cfg(rayon_unstable)]
 pub use future::RayonFuture;
 
 /// Returns the number of threads in the current registry. If this

rayon-core/src/scope/mod.rs

@@ -1,4 +1,4 @@
-#[cfg(feature = "unstable")]
+#[cfg(rayon_unstable)]
 use future::{self, Future, RayonFuture};
 use latch::{Latch, CountLatch};
 use log::Event::*;
@@ -284,7 +284,7 @@ impl<'scope> Scope<'scope> {
         }
     }
 
-    #[cfg(feature = "unstable")]
+    #[cfg(rayon_unstable)]
     pub fn spawn_future<F>(&self, future: F) -> RayonFuture<F::Item, F::Error>
         where F: Future + Send + 'scope
     {

rayon-core/src/thread_pool/mod.rs

@@ -1,13 +1,13 @@
 use Configuration;
-#[cfg(feature = "unstable")]
+#[cfg(rayon_unstable)]
 use future::{Future, RayonFuture};
 use latch::LockLatch;
 #[allow(unused_imports)]
 use log::Event::*;
 use job::StackJob;
 use join;
 use {scope, Scope};
-#[cfg(feature = "unstable")]
+#[cfg(rayon_unstable)]
 use spawn;
 use std::sync::Arc;
 use std::error::Error;
@@ -68,7 +68,7 @@ impl ThreadPool {
     /// `rayon::initialize()` function][f] to do so.
     ///
     /// [f]: fn.initialize.html
-    #[cfg(feature = "unstable")]
+    #[cfg(rayon_unstable)]
     pub fn global() -> &'static Arc<ThreadPool> {
         lazy_static! {
             static ref DEFAULT_THREAD_POOL: Arc<ThreadPool> =
@@ -208,7 +208,7 @@ impl ThreadPool {
     /// Execute `oper_a` and `oper_b` in the thread-pool and return
     /// the results. Equivalent to `self.install(|| join(oper_a,
     /// oper_b))`.
-    #[cfg(feature = "unstable")]
+    #[cfg(rayon_unstable)]
     pub fn join<A, B, RA, RB>(&self, oper_a: A, oper_b: B) -> (RA, RB)
         where A: FnOnce() -> RA + Send,
               B: FnOnce() -> RB + Send,
@@ -224,7 +224,7 @@ impl ThreadPool {
     /// See also: [the `scope()` function][scope].
     ///
     /// [scope]: fn.scope.html
-    #[cfg(feature = "unstable")]
+    #[cfg(rayon_unstable)]
     pub fn scope<'scope, OP, R>(&self, op: OP) -> R
         where OP: for<'s> FnOnce(&'s Scope<'scope>) -> R + 'scope + Send, R: Send
     {
@@ -239,7 +239,7 @@ impl ThreadPool {
     /// See also: [the `spawn()` function defined on scopes][spawn].
     ///
     /// [spawn]: struct.Scope.html#method.spawn
-    #[cfg(feature = "unstable")]
+    #[cfg(rayon_unstable)]
     pub fn spawn<OP>(&self, op: OP)
         where OP: FnOnce() + Send + 'static
     {
@@ -278,7 +278,7 @@ impl ThreadPool {
     /// See also: [the `spawn_future()` function defined on scopes][spawn_future].
     ///
     /// [spawn_future]: struct.Scope.html#method.spawn_future
-    #[cfg(feature = "unstable")]
+    #[cfg(rayon_unstable)]
     pub fn spawn_future<F>(&self, future: F) -> RayonFuture<F::Item, F::Error>
         where F: Future + Send + 'static
     {

rayon-demo/Cargo.toml

@@ -18,6 +18,3 @@ regex = "0.2"
 
 [dev-dependencies]
 num = "0.1.30"
-
-[features]
-unstable = ["rayon/unstable"]

src/lib.rs

@@ -40,9 +40,9 @@ pub use rayon_core::initialize;
 pub use rayon_core::ThreadPool;
 pub use rayon_core::join;
 pub use rayon_core::{scope, Scope};
-#[cfg(feature = "unstable")]
+#[cfg(rayon_unstable)]
 pub use rayon_core::spawn;
-#[cfg(feature = "unstable")]
+#[cfg(rayon_unstable)]
 pub use rayon_core::spawn_future;
-#[cfg(feature = "unstable")]
+#[cfg(rayon_unstable)]
 pub use rayon_core::RayonFuture;

src/test.rs

@@ -19,7 +19,7 @@ fn negative_tests_compile_fail() {
 }
 
 #[test]
-#[cfg(feature = "unstable")]
+#[cfg(rayon_unstable)]
 fn negative_tests_compile_fail_unstable() {
     run_compiletest("compile-fail", "tests/compile-fail-unstable");
 }
@@ -30,7 +30,7 @@ fn negative_tests_run_fail() {
 }
 
 #[test]
-#[cfg(feature = "unstable")]
+#[cfg(rayon_unstable)]
 fn negative_tests_run_fail_unstable() {
     run_compiletest("run-fail", "tests/run-fail-unstable");
 }
@@ -41,7 +41,7 @@ fn positive_test_run_pass() {
 }
 
 #[test]
-#[cfg(feature = "unstable")]
+#[cfg(rayon_unstable)]
 fn positive_test_run_pass_unstable() {
     run_compiletest("run-pass", "tests/run-pass-unstable");
 }