#async #futures #executor #testing #stepping

no-std wookie

Async test/bench toolkit including single stepping executors. No-std compatible.

6 releases

0.3.2 Sep 19, 2021
0.3.1 Aug 24, 2021
0.2.0 Jul 22, 2021
0.1.1 Apr 26, 2021

#97 in Testing

25 downloads per month

Apache-2.0 WITH LLVM-exception

28KB
347 lines

Wookie

License Package Documentation

Async test/bench toolkit including single stepping executors. No-std compatible.

Status: beta

We've done a few iterations now and we quite like it how it is now and believe it to be correct.

Usage

The primary user interface is the wookie! macro, which wraps a future with an executor and pins it on the stack.:

use core::task::Poll;
use wookie::wookie;
wookie!(future: async { true });
assert_eq!(future.poll(), Poll::Ready(true));

// you can also just give a variable name if you have one:
let future = async { true };
wookie!(future);
assert_eq!(future.poll(), Poll::Ready(true));

// we can find out about the state of wakers any time:
assert_eq!(future.cloned(), 0);
assert_eq!(future.dropped(), 0);
assert_eq!(future.woken(), 0);
// or equivalently...
future.stats().assert(0, 0, 0);

If you do not have access to an allocator, you can use the local! macro instead, however, polling is unsafe and you must be very careful to maintain the invariants described in the safety sections of the Local methods.

use core::task::Poll;
use wookie::local;
local!(future: async { true });
assert_eq!(unsafe { future.poll() }, Poll::Ready(true));

// you can also just give a variable name if you have one:
let future = async { true };
local!(future);
assert_eq!(unsafe { future.poll() }, Poll::Ready(true));

// we can find out about the state of wakers any time:
assert_eq!(future.cloned(), 0);
assert_eq!(future.dropped(), 0);
assert_eq!(future.woken(), 0);
// or equivalently...
future.stats().assert(0, 0, 0);

For benchmarking, we provide the dummy! macro, whose waker does nothing, but quite quickly.

use core::task::Poll;
use wookie::dummy;
dummy!(future: async { true });
assert_eq!(future.poll(), Poll::Ready(true));

We have assert_pending! and assert_ready! to save some typing in assertions:

use wookie::*;
use core::task::Poll;
assert_pending!(Poll::<i32>::Pending); // pass
// assert_pending!(Poll::Ready(())); // would fail

// With 1 arg, assert_ready will returning the unwrapped value.
assert_eq!(42, assert_ready!(Poll::Ready(42)));
// assert_ready!(Poll::<i32>::Pending); // would fail

// With 2 args, it's like [`assert_eq`] on the unwrapped value.
assert_ready!(42, Poll::Ready(42));
// assert_ready!(Poll::<i32>::Pending); // would fail
// assert_ready!(42, Poll::Ready(420)); // would fail

MSRV: 1.51.0

Features

Default features: alloc.

  • alloc - enables use of an allocator. Required by Wookie / wookie!.

Copyright and License

Copyright (c) 2021 James Laver, wookie contributors

Licensed under Apache License, Version 2.0 (https://www.apache.org/licenses/LICENSE-2.0), with LLVM Exceptions (https://spdx.org/licenses/LLVM-exception.html).

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.

Dependencies

~60KB