Skip to content

Latest commit

 

History

History
151 lines (98 loc) · 7.81 KB

must_not_await_lint.md

File metadata and controls

151 lines (98 loc) · 7.81 KB

RFC: Must not await lint

Summary

Introduce a #[must_not_await] lint in the compiler that will warn the user when they are incorrectly holding a struct across an await boundary.

Motivation

Enable users to fearlessly write concurrent async code without the need to understand the internals of runtimes and how their code will be affected. The goal is to provide a best effort warning that will let the user know of a possible side effect that is not visible by reading the code right away.

One example of these side effects is holding a MutexGuard across an await bound. This opens up the possibility of causing a deadlock since the future holding onto the lock did not relinquish it back before it yielded control. This is a problem for futures that run on single-threaded runtimes (!Send) where holding a local after a yield will result in a deadlock. Even on multi-threaded runtimes, it would be nice to provide a custom error message that explains why the user doesn't want to do this instead of only a generic message about their future not being Send. Any other kind of RAII guard which depends on behavior similar to that of a MutexGuard will have the same issue.

The big reason for including a lint like this is because under the hood the compiler will automatically transform async fn into a state machine which can store locals. This process is invisible to users and will produce code that is different than what is in the actual rust file. Due to this it is important to inform users that their code may not do what they expect.

Guide-level explanation

Provide a lint that can be attached to structs to let the compiler know that this struct can not be held across an await boundary.

#[must_not_await = "Your error message here"]
struct MyStruct {}

This struct if held across an await boundary would cause a deny-by-default warning:

async fn foo() {
  let my_struct = MyStruct {};
  my_async_op.await;
  println!("{:?}", my_struct);
}

The compiler might output something along the lines of:

TODO: Write a better error message.

warning: Holding `MyStruct` across the await bound on line 3 might cause side effects.

Example use cases for this lint:

  • MutexGuard holding this across a yield boundary in a single threaded executor could cause deadlocks. In a multi-threaded runtime the resulting future would become !Send which will stop the user from spawning this future and causing issues. But in a single threaded runtime which accepts !Send futures deadlocks could happen.

  • The same applies to other such synchronization primitives such as locks from parking-lot.

  • tracing::Span has the ability to enter the span via the tracing::span::Entered guard. While entering a span is totally normal, during an async fn the span only needs to be entered once before the .await call, which might potentially yield the execution.

  • Any RAII guard might possibly create unintended behavior if held across an await boundary.

This lint will enable the compiler to warn the user that the generated MIR could produce unforeseen side effects. Some examples of this are:

This will be a best effort lint to signal the user about unintended side-effects of using certain types across an await boundary.

Reference-level explanation

The must_not_await attribute is used to issue a diagnostic warning when a value is not "used". It can be applied to user-defined composite types (structs, enums and unions), functions and traits.

The must_not_await attribute may include a message by using the MetaNameValueStr syntax such as #[must_not_await = "example message"]. The message will be given alongside the warning.

When used on a user-defined composite type, if the expression of an expression statement has this type and is used across an await point, then this lint is violated.

#[must_not_await = "Your error message here"]
struct MyStruct {}

async fn foo() {
  let my_struct = MyStruct {};
  my_async_op.await;
  println!("{:?}", my_struct);
}

When used on a function, if the expression of an expression statement is a call expression to that function, and the expression is held across an await point, this lint is violated.

#[must_not_await]
fn foo() -> i32 { 5i32 }

async fn foo() {
  let bar = foo();
  my_async_op.await;
  println!("{:?}", bar);
}

When used on a trait declaration, a call expression of an expression statement to a function that returns an impl trait of that trait and if the value is held across an await point, the lint is violated.

trait Trait {
    #[must_not_await]
    fn foo(&self) -> i32;
}

impl Trait for i32 {
    fn foo(&self) -> i32 { 0i32 }
}

async fn foo() {
  let bar = 5i32.foo();
  my_async_op.await;
  println!("{:?}", bar);
}

When used on a function in a trait implementation, the attribute does nothing.

Auto trait vs attribute

#[must_use] is implemented as an attribute, and from prior art and other literature, we can gather that the decision was made due to the complexity of implementing true linear types in Rust. std::panic::UnwindSafe on the other hand is implemented as a marker trait with structural composition.

Drawbacks

  • There is a possibility it can produce a false positive warning and it could get noisy. But using the allow attribute would work similar to other deny-by-default lints.

Rationale and alternatives

Going through the prior are we see two systems currently which provide simailar/semantically similar behavior:

Clippy #[await_holding_lock] lint

This lint goes through all types in generator_interior_types looking for MutexGuard, RwLockReadGuard and RwLockWriteGuard. While this is a first great step, we think that this can be further extended to handle not only the hardcoded lock guards, but any type which is should not be held across an await point. By marking a type as #[must_not_await] we can warn when any arbitrary type is being held across an await boundary. An additional benefit to this approach is that this behaviour can be extended to any type which holds a #[must_not_await] type inside of it.

#[must_use] attribute

The #[must_use] attribute ensures that if a type or the result of a function is not used, a warning is displayed. This ensures that the user is notified about the importance of said value. Currently the attribute does not automatically get applied to any type which contains a type declared as #[must_use], but the implementation for both #[must_not_await] and #[must_use] should be similar in their behavior.

Prior art

Future possibilities

  • Propagate the lint in nested structs/enums. Similar to the use case for the must_use attribute. These likely should be solved together.