riot_wrappers::async_helpers

Trait RiotStyleFuture

Source 
pub(crate) trait RiotStyleFuture {
    type Output;

    // Required method
    fn poll(&mut self, arg: *mut c_void) -> Poll<Self::Output>;
}
Available on riot_module_sock_udp and riot_module_sock_aux_local and crate feature with_embedded_nal_async only.
Expand description

A trait similar to Future that is practical to implement for the typical RIOT situations where a waker needs to be converted into a function and argument pointer.

Wrapped in a RiotStylePollStruct, it implements Future, and the conversion between the arg pointer and the full struct is taken care of. That wrapper may also do any optimizations such as not really storing the waker if it can be compressed to a single word instead.

§Implementing

While this can legally be implemented without unsafe, practical use will require unsafe, and that requires sticking to the rules:

  • Whenever .poll() is called, do whatever the future needs to do after having been awoken. If this returns core::task::Poll::Pending (and the future wants to be polled ever again), it must then pass on the arg to some RIOT callback setter together with a static function of a suitable signature. Conventionally, that function is called Self::callback().

  • When that callback function is called (and has any arguments), it may inspect the arguments to decide to return early (for example, if it receives “chatter” that is unrelated to the completion of the future). If it decides that this is now the callback that should make progress, it must call [RiotStylePollStruct::<Self>::callback(arg)], with arg being the value that was passed around through RIOT from the poll function.

  • To the author’s knowledge, the mechanism itself has no requirements of not shuffling any items in and out of any &mut that are involved (otherwise, they would be pinned). However, the callback mechanism itself may require no such shuffling to occur, in which case it is the implementor’s responsibility to not just move its data around.

Required Associated Types§

Source

type Output

Required Methods§

Source

fn poll(&mut self, arg: *mut c_void) -> Poll<Self::Output>

Implementors§