Includes only fixes.

Fixes

• AsyncSeek impl for File (#1986).
• rt: shutdown deadlock in threaded_scheduler (#2074, #2082).
• rt: memory ordering when dropping JoinHandle (#2044).
• docs: misc API documentation fixes and improvements.

A breaking change was accidentally introduced in tokio-macros. The breaking change was reverted and Tokio v0.2.8 depends on the correct version of tokio-macros.

Fixes

• depend on new version of tokio-macros.

This release includes both bug fixes and incremental improvements across most of Tokio. The primary bug fixes are to Runtime configured with basic_scheduler and task::LocalSet.

Fixes

• potential deadlock when dropping basic_scheduler Runtime.
• calling spawn_blocking from within a spawn_blocking (#2006).
• storing a Runtime instance in a thread-local (#2011).
• miscellaneous documentation fixes.
• rt: fix Waker::will_wake to return true when tasks match (#2045).
• test-util: time::advance runs pending tasks before changing the time (#2059).

Added

• net::lookup_host maps a T: ToSocketAddrs to a stream of SocketAddrs (#1870).
• process::Child fields are made public to match std (#2014).
• impl Stream for sync::broadcast::Receiver (#2012).
• sync::RwLock provides an asynchonous read-write lock (#1699).
• runtime::Handle::current returns the handle for the current runtime (#2040).
• StreamExt::filter filters stream values according to a predicate (#2001).
• StreamExt::filter_map simultaneously filter and map stream values (#2001).
• StreamExt::try_next convenience for streams of Result<T, E> (#2005).
• StreamExt::take limits a stream to a specified number of values (#2025).
• StreamExt::take_while limits a stream based on a predicate (#2029).
• StreamExt::all tests if every element of the stream matches a predicate (#2035).
• StreamExt::any tests if any element of the stream matches a predicate (#2034).
• task::LocalSet.await runs spawned tasks until the set is idle (#1971).
• time::DelayQueue::len returns the number entries in the queue (#1755).
• expose runtime options from the #[tokio::main] and #[tokio::test] (#2022).

This release fixes an API regression introduced as part of v0.2.5.

Fixes

• fs::File::seek API regression (#1991).

Includes new APIs, utilities, and fixes. Some highlights:

tokio::sync::broadcast

A multi-producer, multi-consumer channel where each sent value is sent to all consumers (fan-out). The channel is bounded and when consumers lag, they will receive an error indicating they have lagged too far behind.

use tokio::sync::broadcast;

#[tokio::main]
async fn main() {
    let (tx, mut rx1) = broadcast::channel(16);
    let mut rx2 = tx.subscribe();

    tokio::spawn(async move {
        assert_eq!(rx1.recv().await.unwrap(), 10);
        assert_eq!(rx1.recv().await.unwrap(), 20);
    });

    tokio::spawn(async move {
        assert_eq!(rx2.recv().await.unwrap(), 10);
        assert_eq!(rx2.recv().await.unwrap(), 20);
    });

    tx.send(10).unwrap();
    tx.send(20).unwrap();
}

Senders never block. When the channel is full, the oldest value still held by the channel is overwritten. This tends to be the desired behavior in order to prevent slow consumers from blocking the entire system. However, you can use a Semaphore (also added in this release) to ensure that all consumers see all messages.

tokio::sync::Semaphore

A counting synchronization primitive. It is used to limit a critical section to 1 or more concurrent tasks. For example, assume we wish to limit the number of in-flight database queries, we could do something like:

struct MyDbClient {
    db: MyDbHandle,
    semaphore: tokio::sync:Semaphore,
}

async fn query(client: &MyDbClient, query: Query) -> QueryResult {
     let _permit = client.semaphore.acquire().await;
     client.db.query(query).await
}

There may be any number of concurrent calls to query, but the semaphore will limit the number that are able to concurrently perform the query.

Added

• io::AsyncSeek trait (#1924).
• Mutex::try_lock (#1939)
• mpsc::Receiver::try_recv and mpsc::UnboundedReceiver::try_recv (#1939).
• writev support for TcpStream (#1956).
• time::throttle for throttling streams (#1949).
• implement Stream for time::DelayQueue (#1975).
• sync::broadcast provides a fan-out channel (#1943).
• sync::Semaphore provides an async semaphore (#1973).
• stream::StreamExt provides stream utilities (#1962).

Fixes

• deadlock risk while shutting down the runtime (#1972).
• panic while shutting down the runtime (#1978).
• sync::MutexGuard debug output (#1961).
• misc doc improvements (#1933, #1934, #1940, #1942).

Changes

• runtime threads are configured with runtime::Builder::core_threads and
  runtime::Builder::max_threads. runtime::Builder::num_threads is
  deprecated (#1977).

A small release to fix a potential deadlock when using Mutex.

Fixes

• sync::Mutex deadlock when lock() future is dropped early (#1898).

Mostly a bug fix, doc improvement, and polish release. The biggest new addition are the new helpers to read and write integers. They are on AsyncReadExt and AsyncWriteExt and can make protocol encoding / decoding easier. For example, working with length delimited payloads might look like:

use tokio::io::{self, AsyncReadExt, AsyncWriteExt, BufStream};
use tokio::net::TcpStream;

async fn read_frame(src: &mut BufStream<TcpStream>) -> io::Result<Vec<u8>> {
     let len = src.read_u32().await?;
     let mut frame = vec![0; len as usize];
     src.read_exact(&mut frame).await?;

    Ok(frame)
}

async fn write_frame(dst: &mut BufStream<TcpStream>, frame: &[u8]) -> io::Result<()> {
    dst.write_u32(frame.len() as u32).await?;
    dst.write_all(frame).await?;
    dst.flush().await?;

    Ok(())
}

Added

• read / write integers using AsyncReadExt and AsyncWriteExt (#1863).
• read_buf / write_buf for reading / writing Buf / BufMut (#1881).
• TcpStream::poll_peek - pollable API for performing TCP peek (#1864).
• sync::oneshot::error::TryRecvError provides variants to detect the error
  kind (#1874).
• LocalSet::block_on accepts !'static task (#1882).
• task::JoinError is now Sync (#1888).
• impl conversions between tokio::time::Instant and
  std::time::Instant (#1904).

Fixes

• calling spawn_blocking after runtime shutdown (#1875).
• LocalSet drop inifinite loop (#1892).
• LocalSet hang under load (#1905).
• improved documentation (#1865, #1866, #1868, #1874, #1876, #1911).

Primarily a release fix for basic_scheduler and task::LocalSet.

task::LocalSet was introduced in v0.2.1 and provides tooling to run !Send tasks. The task::LocalSet structure replaces the need to have separate runtimes. The advantage being that it can be used with the threaded runtime in order to run both Send futures across multiple threads and !Send futures on the current thread.

use tokio::runtime::Runtime;
use tokio::task;

use std::rc::Rc;

let unsend_data = Rc::new("my unsend data...");

let mut rt = Runtime::new().unwrap();

// Construct a local task set that can run `!Send` futures.
let local = task::LocalSet::new();

// Run the local task group.
local.block_on(&mut rt, async move {
    let unsend_data = unsend_data.clone();
    // `spawn_local` ensures that the future is spawned on the local
    // task group.
    task::spawn_local(async move {
        println!("{}", unsend_data);
        // ...
    }).await.unwrap();
});

Fixes

• scheduling with basic_scheduler (#1861).
• update spawn panic message to specify that a task scheduler is required (#1839).
• API docs example for runtime::Builder to include a task scheduler (#1841).
• general documentation (#1834).
• building on illumos/solaris (#1772).
• panic when dropping LocalSet (#1843).
• API docs mention the required Cargo features for Builder::basic_scheduler and Builder::threaded_scheduler (#1858).

Added

• impl Stream for signal::unix::Signal (#1849).
• API docs for platform specific behavior of signal::ctrl_c and signal::unix::Signal (#1854).
• API docs for signal::unix::Signal::{recv, poll_recv} and signal::windows::CtrlBreak::{recv, poll_recv} (#1854).
• File::into_std and File::try_into_std methods (#1856).

Fixes

• API docs for TcpListener::incoming, UnixListener::incoming (#1831).

Added

• tokio::task::LocalSet provides a strategy for spawning !Send tasks (#1733).
• export tokio::time::Elapsed (#1826).
• impl AsRawFd, AsRawHandle for tokio::fs::File (#1827).

A major breaking change. Most implementation and APIs have changed one way or
another. This changelog entry contains a highlight

Changed

• APIs are updated to use async / await.
• most tokio-* crates are collapsed into this crate.
• Scheduler is rewritten.
• tokio::spawn returns a JoinHandle.
• A single I/O / timer is used per runtime.
• I/O driver uses a concurrent slab for allocating state.
• components are made available via feature flag.
• Use bytes 0.5
• tokio::codec is moved to tokio-util.

Removed

• Standalone timer and net drivers are removed, use Runtime instead
• current_thread runtime is removed, use tokio::runtime::Runtime with
  basic_scheduler instead.