`call-with-values` vs. `call-in-continuation`

Questions & Answers
1

Recently, while using call-with-values to invoke a continuation, I encountered
unexpected high-performance costs. After further investigation, I found that
call-in-continuation was actually the correct function to use in this context.

From my current understanding, the difference between call-with-values and
call-in-continuation lies in how they handle the continuation setup:

  • (call-with-values thk k) first evaluates (thk) to produce values, which are
    then passed as arguments to the receiver k.
  • (call-in-continuation k thk), by contrast, sets k as the continuation before
    evaluating (thk), so thk can capture k as its continuation throughout its
    computation.

This distinction is significant when (thk)'s computation captures additional
continuations, making call-in-continuation potentially more efficient in such
scenarios.

I am curious whether there are specific use cases where one might prefer
call-with-values over call-in-continuation, assuming the receiver k is a
continuation. Excluding performance considerations, my understanding is that both
functions behave equivalently. Any insights on this would be greatly appreciated.

I believe it would be helpful if the documentation for call-with-values included
a note suggesting that call-in-continuation might be a better choice in cases
where the receiver is a continuation.