wookie

Crates.iowookie
lib.rswookie
version0.3.2
sourcesrc
created_at2021-04-01 09:43:04.240389
updated_at2021-09-19 16:53:56.896444
descriptionAsync test/bench toolkit including single stepping executors. No-std compatible.
homepagehttps://github.com/irrustible/wookie
repositoryhttps://github.com/irrustible/wookie
max_upload_size
id376534
size40,104
(jjl)

documentation

https://docs.rs/wookie

README

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.

Commit count: 10

cargo fmt