Add FlatMapStrategy.throttle

[inamiy]

This PR adds FlatMapStrategy.first that works as a lightweight ReactiveSwift.Action and is equivalent to RxSwift.flatMapFirst.

This PR is related to FlatMapStrategy.race #233 which works quite differently as follows:

(Marble diagram, `|` as completed)

// stream of producers
S : --P1--P2--P3--------|

// producers
P1:   --1--2-|
P2:       ----3---4-|
P3:           --5---6-|

// flatten(.merge)
FM: ----1--2--3-5-4-6---|

// flatten(.first)
FF: ----1--2----5---6---|

// flatten(.race)
FR: ----1--2------------|

As we can see in flatten(.first) that only P2 is not handled due to P1 still active (first inner producer) but P3 is well handled, this new strategy works as a lightweight Action:

let inputSignal: Signal<Input, NoError> = ...
let exec: (Input) -> SignalProducer<Output, NoError> = ...

let outputSignal = inputSignal.flatMap(.first, exec)

// ...is essentially equal to:

let action = Action(execute: exec)
inputSignal.observeValues(action.apply)

let outputSignal = action.values

Please note that if returning producer of exec can emit error, inputSignal.flatMap(.first, exec) will terminate but action.values will not.
(But I think it's also possible to fully simulate action.errors as well, by using materialize / dematerialize to pattern-match and keep the stream alive)

Checklist

• Updated CHANGELOG.md.

[inamiy]

I'm still wondering if .first is really a proper term to use for this operator since it makes us confuse a lot with .race and also SignalProducer.first.

Any thoughts on this?

[inamiy]

This PR is ready to review, but requires write permission to move on ("Ready for review" button doesn't appear in my screen):

https://github.blog/changelog/2019-03-08-expand-ready-for-review-permissions-for-draft-pull-requests/

[leonid-s-usov]

maybe this should be called .oldest vs the existing .latest?

[andersio]

@leonid-s-usov This is not exactly "oldest", in the sense that it only drops upstream values when the inner producer is still active. If we have to coin an accurate term in Swift collection terms, it would be like skipWhenActive.

[andersio]

I would propose to name this throttle given throttle(_:on:) having a similar semantic but instead in the time domain.

[inamiy]

Renamed to FlattenStrategy.throttle in 1f241b6 .

[mluisbrown]

As we can see in flatten(.first) that only P2 is not handled due to P1 still active (first inner producer) but P3 is well handled

This makes no sense to me at all. P1 completes before P2 has emitted any values, so P1 still active is not true.

Also, since P1 completes before P2 has emitted any values, P2 should take precedence, so I would expect the output to be:

FF: ----1--2--3-5---6---|

[mluisbrown]

the "first inner stream" that sends an event if not exists.

What does that mean? If what "not exists" (doesn't exist) ?

[mluisbrown]

Again, don't understand if exists here.

[mluisbrown]

streams is disposed of

streams are disposed of