12

MutableSharedFlow takes 3 parameters: replay, extraBufferCapacity and onBufferOverflow. What is the difference between replay and extraBufferCapacity?

The documentation mentions the following:

replay - the number of values replayed to new subscribers (cannot be negative, defaults to zero).

extraBufferCapacity - the number of values buffered in addition to replay. emit does not suspend while there is a buffer space remaining (optional, cannot be negative, defaults to zero).

I don't understand exactly the difference between the 2 and when we would need extraBufferCapacity > 0. Is extraBufferCapacity just an additional replay capacity for emitters?

Christian C
  • 369
  • 3
  • 10

1 Answers1

16

Is extraBufferCapacity just an additional replay capacity for emitters?

The "replay" terminology only really makes sense for subscribers, not emitters. The replay parameter defines how many past values new subscribers will receive upon subscribing. It obviously implies that those values need to be stored, so the overall buffer needs to be at least this big.

However, the buffer size (as a whole) impacts emitters. The exact consequence of a full buffer depends on onBufferOverflow, but this buffer size can be used to control backpressure on emitters (slowing them down) or how we drop messages. With a larger buffer, you can allow emitters to have bursts of emissions without slowing them down, like any regular buffer.

Now, choosing to have a larger buffer shouldn't force you to replay those buffered values to new subscribers, hence the extraBufferCapacity. With extraBufferCapacity > 0, you can define a buffer of any desired size without also forcing you to replay as many values, simply by using the formula:

bufferSize = replay + extraBufferCapacity

You could for instance decide to replay no values at all to new subscribers, but still allow bursts from emitters by having some (non-replayed) buffer.

Joffrey
  • 32,348
  • 6
  • 68
  • 100
  • Believe me, if we had this great explanation in the docs we wouldn't get frustrated and ask questions like this (https://github.com/Kotlin/kotlinx.coroutines/issues/2387) and make a whole thread out of it. The point is, this is not even a long explanation. This simple line is just as concise as it can be. "**Now, choosing to have a larger buffer shouldn't force you to replay those buffered values to new subscribers, hence the extraBufferCapacity.**" – Farid Apr 29 '22 at 10:59
  • I find the descriptions of `replay` and `extraBufferCapacity` pretty clear in the docs honestly in this respect: *extraBufferCapacity: the number of values buffered in addition to replay*. Isn't that exactly what the sentence you quoted means? Some values are replayed, and you can choose to have extra buffer capacity on top of that (for values that are not replayed). I agree that some parts of the docs are sometimes unclear, but in this specific case it didn't seem ambiguous to me. – Joffrey Apr 29 '22 at 13:15
  • If the docs were really clear, there woult be no questions about it. – Michael Piefel Jun 15 '23 at 12:26