PSA: Splitting up fuchsia_async::Executor

[Adam Perry]

You can skip reading this email if you don't interact with the fuchsia_async crate's executors.

TLDR: Instead of a single Executor, there will now be a single-threaded LocalExecutor, a single-threaded TestExecutor, and a multi-threaded SendExecutor.

Problem

Currently fuchsia_async::Executor supports several modes at runtime:

* single-threaded or multi-threaded

* runs tasks to completion or to the first yield

* schedules waits using kernel monotonic time or a synthetic test timeline

This has a few effects we don't like:

* errors from misuse occur at runtime instead of compile-time

* it's not possible to optimize for single-threaded behavior in safe Rust

* test-only functions that can cause serious task scheduling bugs when misused are available to compile and use in production build targets

* the implementation is much more complex to support transitioning into/out of each of these modes

What's changing?

I'm removing the Executor type in favor of three distinct executor types:

* LocalExecutor: a single-threaded production task executor

  * supports run_singlethreaded(task)

* SendExecutor: a multi-threaded production task executor

  * supports run(task, num_threads)

* TestExecutor: a single-threaded executor for testing which can change its notion of time and schedule partial tasks

   * supports run_singlethreaded, run_until_stalled, run_one_step, set_fake_time

I've already introduced the necessary aliases to do this as a soft migration, and I've opened a large migration CL moving our explicit executor usage to what I believe to be the correct API in each case. You may want to see if any of your binaries or tests are affected. If I've made an error in selecting the executor type there should be no impact and it's safe to clean up after the fact if you don't catch me in time with a Gerrit comment.

Once all callers have been migrated, I have a CL to delete Executor and further follow-ups to require correct use of each executor type. After those changes land, you won't be able to call incorrect methods on a non-test executor anymore. (There's some follow-up work to make sure that the test executor can statically restrict use of faked time.)

What's not changing?

All three executor types are still backed by the same code they were before my changes. There should be no observable runtime change from these CLs.

This series of patches does not include any optimizations, which I expect to come after further refactoring of fuchsia_async's internals.

Only a single executor can still be in use at a time on a given thread, regardless of type. This limitation stems from how the executors share their internals today, but it is likely to be necessary for the immediate future even after refactoring there.

Questions? Concerns?

You've come to the right place! Please note that this announcement has been sent to a public mailing list.

--

Adam Perry

[Mukesh Agrawal]

Thank you for making the API of the Executor(s) narrower, and harder to mis-use!

--
All posts must follow the Fuchsia Code of Conduct https://fuchsia.dev/fuchsia-src/CODE_OF_CONDUCT or may be removed.
---
You received this message because you are subscribed to the Google Groups "rust-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to rust-users+...@fuchsia.dev.
To view this discussion on the web visit https://groups.google.com/a/fuchsia.dev/d/msgid/rust-users/CA%2BvriKdUk2%2B5UnHPzif%2BJRVa2pXXwDb%2BithqWpegbY%2B1HFb9jg%40mail.gmail.com.

--

Our nation’s summers of riots are caused by our nation’s winters of delay. (MLK)

[Adam Perry]

You're welcome! As it turns out, there was only one place in the repo where these APIs were in danger of being really mis-used, and I wrote it. Oops! At least the blast radius seems to have been mostly limited to development-time confusion.

The migration CL has now landed. You can start writing new code using the more specific executor types, and if you copy/paste any existing examples or tests you'll get the right thing. I hope to land the follow-up CLs to statically restrict usage later today.

--

Adam Perry