Crate core_futures_tls

Libcore wrapper allowing async/await

Usage

Put the following in your Cargo.toml:

[dependencies]
core = { package = "core-futures-tls", version = "0.1.0" }

Why

Currently, async/await is not usable from libcore. Attempting to call .await from a no_std crate will yield the following error:

error[E0433]: failed to resolve: could not find `poll_with_tls_context` in `future`
error[E0433]: failed to resolve: could not find `from_generator` in `future`

This is due to await lowering to some code calling the functions ::core::futures::poll_with_tls_context and ::core::futures::from_generator in order to setup a per-thread context containing the current task. Those functions, however, do not exist. The equivalent functions are defined in libstd. They set up a thread-local variable which contains the current task being executed. When polling a future, this task will get retrieved in order to call the future's poll function.

As mentioned, the libstd version of those functions use a thread-local variable, which is only supported in rust's libstd through the thread_local! macro - which doesn't exist in libcore. There is, however, an alternative: The (unstable) #[thread_local] attribute, which uses ELF TLS. Note that ELF TLS is not portable to all targets - it needs to be supported by the OS, the loader, etc...

Here's a small example of the thread_local attribute in action:

#![feature(thread_local)]
use core::cell::Cell;
#[thread_local]
static TLS_CX: Cell<i32> = Cell::new(1);

Using this trick, we can copy paste libstd's implementation of the poll_with_tls_context/from_generator functions, but replacing the thread_local! macro with a #[thread_local] macro. Ez pz.

Wrapping libcore

This trick is nice, but compiling a custom libcore is fastidious. Instead, we're going to wrap libcore, exposing our own libcore that just reexports the real libcore's functions, and adding our own extra stuff. This, surprisingly, can be done simply by declaring a core dependency with the package attribute set to our "real" crates.io package name. This will trick cargo into giving rustc our wrapper core as if it was the real libcore.

So that's it. All this crate does is reexport libcore, adding a couple functions in the future module. You just have to use the following in your Cargo.toml in order to use it, and rust will happily use core-futures-tls as if it was the libcore.

[dependencies]
core = { package = "core-futures-tls", version = "0.1.0" }

Closing thoughts

While this crate still uses TLS, it should be possible to create a version that stores the thread local context in a global for single-threaded systems such as microcontrollers. This is left as an exercise to the reader.

Modules

alloc	Memory allocation APIs
any	This module implements the Any trait, which enables dynamic typing of any 'static type through runtime reflection.
arch	SIMD and vendor intrinsics module.
array	Implementations of things like Eq for fixed-length arrays up to a certain length. Eventually we should able to generalize to all lengths.
ascii	Operations on ASCII strings and characters.
borrow	A module for working with borrowed data.
cell	Shareable mutable containers.
char	A character type.
clone	The Clone trait for types that cannot be 'implicitly copied'.
cmp	Functionality for ordering and comparison.
convert	Traits for conversions between types.
default	The Default trait for types which may have meaningful default values.
f32	This module provides constants which are specific to the implementation of the f32 floating point data type.
f64	This module provides constants which are specific to the implementation of the f64 floating point data type.
ffi	Utilities related to FFI bindings.
fmt	Utilities for formatting and printing strings.
future	Asynchronous values.
future	Asynchronous values.
hash	Generic hashing support.
hint	Hints to compiler that affects how code should be emitted or optimized.
i8	The 8-bit signed integer type.
i16	The 16-bit signed integer type.
i32	The 32-bit signed integer type.
i64	The 64-bit signed integer type.
i128	The 128-bit signed integer type.
isize	The pointer-sized signed integer type.
iter	Composable external iteration.
marker	Primitive traits and types representing basic properties of types.
mem	Basic functions for dealing with memory.
num	Numeric traits and functions for the built-in numeric types.
ops	Overloadable operators.
option	Optional values.
pin	Types that pin data to its location in memory.
prelude	The libcore prelude
ptr	Manually manage memory through raw pointers.
result	Error handling with the Result type.
slice	Slice management and manipulation.
str	String manipulation.
sync	Synchronization primitives
task	Types and Traits for working with asynchronous tasks.
time	Temporal quantification.
u8	The 8-bit unsigned integer type.
u16	The 16-bit unsigned integer type.
u32	The 32-bit unsigned integer type.
u64	The 64-bit unsigned integer type.
u128	The 128-bit unsigned integer type.
usize	The pointer-sized unsigned integer type.
intrinsics	Experimental Compiler intrinsics.
panic	Experimental Panic support in the standard library.
panicking	Experimental Panic support for libcore
raw	Experimental Contains struct definitions for the layout of compiler built-in types.
unicode	Experimental

Macros

assert_eq	Asserts that two expressions are equal to each other (using PartialEq).
assert_ne	Asserts that two expressions are not equal to each other (using PartialEq).
debug_assert	Asserts that a boolean expression is true at runtime.
debug_assert_eq	Asserts that two expressions are equal to each other.
debug_assert_ne	Asserts that two expressions are not equal to each other.
panic	Panics the current thread.
try	Unwraps a result or propagates its error.
unimplemented	Indicates unfinished code.
unreachable	Indicates unreachable code.
write	Writes formatted data into a buffer.
writeln	Write formatted data into a buffer, with a newline appended.
todo	Experimental Indicates unfinished code.
uninitialized_array	Experimental Creates an array of MaybeUninit.