From a46de7a2dd257bebf449d12f8659e2771d1abcf4 Mon Sep 17 00:00:00 2001 From: Niko Matsakis Date: Wed, 14 Jun 2017 05:01:59 -0400 Subject: [PATCH 1/2] document how to use rayon as well as semver policy --- README.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/README.md b/README.md index 011507dea..6168ef14b 100644 --- a/README.md +++ b/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 = XXX # <-- insert latest version of Rayon from crates.io here +``` + +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/0.8.0/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,25 @@ fn search(path: &Path, cost_so_far: usize, best_cost: &Arc) { 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. They are +accessible with the "unstable" cargo feature. Please do give them a +try -- but if you are using them, be aware that you (and all of your +dependencies!) will have to stay current with Rayon. + +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 From 20de1ff12df93c739152e5ccfe48a91a66adac99 Mon Sep 17 00:00:00 2001 From: Niko Matsakis Date: Wed, 14 Jun 2017 10:57:25 -0400 Subject: [PATCH 2/2] adopt new approach to unstable features --- .travis.yml | 16 ++++++++-------- Cargo.toml | 5 ----- README.md | 21 +++++++++++++++------ appveyor.yml | 18 +++++++++--------- examples/cpu_monitor.rs | 6 +++--- rayon-core/Cargo.toml | 9 +++------ rayon-core/src/lib.rs | 12 ++++++------ rayon-core/src/scope/mod.rs | 4 ++-- rayon-core/src/thread_pool/mod.rs | 14 +++++++------- rayon-demo/Cargo.toml | 3 --- src/lib.rs | 6 +++--- src/test.rs | 6 +++--- 12 files changed, 59 insertions(+), 61 deletions(-) diff --git a/.travis.yml b/.travis.yml index 7f9d1006f..8e5bd7a8c 100644 --- a/.travis.yml +++ b/.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 diff --git a/Cargo.toml b/Cargo.toml index ecdc1d08c..78dbaa168 100644 --- a/Cargo.toml +++ b/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"] diff --git a/README.md b/README.md index 6168ef14b..1e3c9f0a2 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ as: ```rust [dependencies] -rayon = XXX # <-- insert latest version of Rayon from crates.io here +rayon = 0.8.0 ``` and then add the following to to your `lib.rs`: @@ -51,7 +51,7 @@ 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/0.8.0/rayon/prelude/index.html). +[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: @@ -426,10 +426,19 @@ interjected into our execution! 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. They are -accessible with the "unstable" cargo feature. Please do give them a -try -- but if you are using them, be aware that you (and all of your -dependencies!) will have to stay current with Rayon. +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 diff --git a/appveyor.yml b/appveyor.yml index 021d05592..640348608 100644 --- a/appveyor.yml +++ b/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 ) diff --git a/examples/cpu_monitor.rs b/examples/cpu_monitor.rs index 0d00eea7f..7c0b2e1da 100644 --- a/examples/cpu_monitor.rs +++ b/examples/cpu_monitor.rs @@ -77,7 +77,7 @@ 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)); @@ -85,8 +85,8 @@ fn task_stall_scope(args: &Args) { }); } -#[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); } diff --git a/rayon-core/Cargo.toml b/rayon-core/Cargo.toml index d357fe2a8..5ec7da063 100644 --- a/rayon-core/Cargo.toml +++ b/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] diff --git a/rayon-core/src/lib.rs b/rayon-core/src/lib.rs index 6cd36e87d..9c750daac 100644 --- a/rayon-core/src/lib.rs +++ b/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 diff --git a/rayon-core/src/scope/mod.rs b/rayon-core/src/scope/mod.rs index e41e5389e..935cb9d82 100644 --- a/rayon-core/src/scope/mod.rs +++ b/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(&self, future: F) -> RayonFuture where F: Future + Send + 'scope { diff --git a/rayon-core/src/thread_pool/mod.rs b/rayon-core/src/thread_pool/mod.rs index 2c9ee9a26..bd05ce686 100644 --- a/rayon-core/src/thread_pool/mod.rs +++ b/rayon-core/src/thread_pool/mod.rs @@ -1,5 +1,5 @@ use Configuration; -#[cfg(feature = "unstable")] +#[cfg(rayon_unstable)] use future::{Future, RayonFuture}; use latch::LockLatch; #[allow(unused_imports)] @@ -7,7 +7,7 @@ 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 { lazy_static! { static ref DEFAULT_THREAD_POOL: Arc = @@ -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(&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(&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(&self, future: F) -> RayonFuture where F: Future + Send + 'static { diff --git a/rayon-demo/Cargo.toml b/rayon-demo/Cargo.toml index f9ac1a654..f3cc98eef 100644 --- a/rayon-demo/Cargo.toml +++ b/rayon-demo/Cargo.toml @@ -18,6 +18,3 @@ regex = "0.2" [dev-dependencies] num = "0.1.30" - -[features] -unstable = ["rayon/unstable"] diff --git a/src/lib.rs b/src/lib.rs index e8788a978..1fd8dc336 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -39,9 +39,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; diff --git a/src/test.rs b/src/test.rs index 50f09c930..a10075769 100644 --- a/src/test.rs +++ b/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"); }