Component used:androidx.room:room-*
Version used: 2.3.0, 2.4.0-alpha02
Devices/Android versions reproduced on: N/A -> code-gen error (kapt)

The documentation on @Transaction states:

If the query is asynchronous (e.g. returns a LiveData or RxJava Flowable), the transaction is properly handled when the query is run, not when the method is called.

But unless I'm misunderstanding what this is trying to communicate, reality seems to be different.

Given the following dao:

@Dao
interface ExampleDao {

    @Query("SELECT * FROM table_example")
    fun allFlow(): Flow<List<ExampleEntity>>

    @Query("SELECT * FROM table_example")
    fun allLiveData(): LiveData<List<ExampleEntity>>

    @Query("SELECT * FROM table_example")
    fun allRx(): Flowable<List<ExampleEntity>>

    @Transaction
    fun transactionFlow() = allFlow()

    @Transaction
    fun transactionLiveData() = allLiveData()    // <-- Nope

    @Transaction
    fun transactionRx() = allRx()                // <-- Nope
}

Although implementations are generated, errors are thrown for the @Transaction annotated functions returning LiveData and Flowable:

error: Method annotated with @Transaction must not return deferred/async return type <type>. Since transactions are thread confined and Room cannot guarantee that all queries in the method implementation are performed on the same thread, only synchronous @Transaction implemented methods are allowed. If a transaction is started and a change of thread is done and waited upon then a database deadlock can occur if the additional thread attempts to perform a query. This restrictions prevents such situation from occurring.

This seems to contradict the earlier statement from the documentation on @Transaction? Is there another way to use @Transaction with a deferred/async return type?

What's also interesting is that the @Transaction annotated function returning a Flow does not yield any errors. Isn't Flow also a deferred/async return type? Does this mean that Room can in fact guarantee that all queries in the method are performed on the same thread? If so, how?

The generated code looks like this:

@Override
public Flow<List<ExampleEntity>> transactionFlow() {
  __db.beginTransaction();
  try {
    Flow<List<ExampleEntity>> _result = ExampleDao.DefaultImpls.transactionFlow(ExampleDao_Impl.this);
    __db.setTransactionSuccessful();
    return _result;
  } finally {
    __db.endTransaction();
  }
}

This function is no longer deferred, because the transactional operations involve blocking I/O, and there are assertions in place that will fail if this is called from the main thread. And even if we were to make this function suspendable (we would then have a suspendable function returning a Flow?🤨), it would still not be main-safe.

In conclusion, I suspect:

the documentation for @Transaction is no longer accurate?
a function with @Transaction annotation returning a Flow should also yield a code-gen error?