# Presentazione workshop RustLab 2022

## Abstract
You need to query a web API that returns paged data and throttles your
requests? Would you appreciate an abstraction layer that separates getting the
data from handling it? Let’s implement a Stream step by step, learning the
current limitations of the language and how to avoid them.

## Description
It is very common to interact with Web APIs that expose _paged_ data and, at
the same time, use some algorithm like the [leaky
bucket](https://en.wikipedia.org/wiki/Leaky_bucket) in order to limit the
amount of requests per user. Nonetheless, it is not trivial at all to handle
these situations in a _clean_ way, and the ideal solution is to separate the
logic behind requesting the paged data from the processing of the results.

During the workshop we are going to learn how to implement a
[`Stream`](https://docs.rs/futures/latest/futures/prelude/trait.Stream.html) in
order to build an abstraction layer able to perform the right queries with the
right timing. In details, we will learn about:
- expressing a `Stream` as a state machine;
- how `Pin` works in practice;
- the current limitations of the type system and how to avoid them;
- when to use `async` and when to avoid it (and why).

During the event we will not have time to write _everything_,
instead you will be given some basic code to work with, in order to focus on
the implementation of the `Stream`. Moreover, the entire workflow will be
divided in steps and a repository will be available with the code for each
step.

## Workshop agenda
- Brief introduction of the issues when a non-trivial `Stream` has to be
implemented.
- Clone of the basic structure to start working on the implementation without
worrying on details not relevant for us.
- Incremental implementation of a working `Stream`, using naive approaches.
- Removal of an allocation for an `!Unpin` structure with the help of
`pin-project`.
- Further removal of an allocation, taking advantage of careful usage of `async`
in a non-trivial context.
- Final thoughts of future possibilities in the short and long term.

# What I will learn
- How the `Stream` trait works.
- What is `Pin`, why it is important, what is `Unpin` and how to handle both
concepts.
- The concept of _pin projection_ and how to taking advantage of it.
- How to take advantage of `async` and how to overcome cryptic lifetime errors
in non-trivial contexts.
- How to build an extremely reliable asynchronous abstraction with a very small
overhead.

# What I will need
- A laptop
- The Rust toolchain, both stable and recent nightly
- Your favorite editor
- A browser and git