Attempt to document Supply.stable

gistfile1.txt

=head2 method stable

    method stable(Supply:D: $time, :$scheduler = $*SCHEDULER --> Supply:D)

Creates a new supply that only emits a value after no other values have been
emitted for C<$time>. If, during the timeout, changed values are emitted to
the C<Supplier> they will be thrown away and only the last emitted value will
be retained. Each time a changed value is emitted to the C<Supplier>, during the
timeout, C<$time> is reset.

This method can be quite useful when handling UI input, where it is not desired
to perform an operation until the user has stopped typing for a while rather
than on every keystroke.

my $supplier = Supplier.new;
my $supply1 = $supplier.Supply;
$supply1.tap(-> $v { say "Supply1 got: $v" });
$supplier.emit(42);

my Supply $supply2 = $supply1.stable(5);
$supply2.tap(-> $v { say "Supply2 got: $v" });
sleep(3);
$supplier.emit(43);
$supplier.emit(44);
sleep(10);

# OUTPUT: «Supply1 got: 42␤Supply1 got: 43␤Supply1 got: 44␤Supply2 got: 44␤»

As can be seen above, C<$supply1> received all values emitted to the Supplier
while C<$supply2> only received one value. The 43 was thrown away because it
was followed by another 'last' value 44 which was retained and sent to <$supply2>
after approx eight seconds, this due to the fact that the timeout was reset.