[−][src]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 |
arch | SIMD and vendor intrinsics module. |
array | Implementations of things like |
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 |
cmp | Functionality for ordering and comparison. |
convert | Traits for conversions between types. |
default | The |
f32 | This module provides constants which are specific to the implementation
of the |
f64 | This module provides constants which are specific to the implementation
of the |
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 |
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 |
assert_ne | Asserts that two expressions are not equal to each other (using |
debug_assert | Asserts that a boolean expression is |
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 |