=begin pod :kind("Type") :subkind("class") :category("domain-specific")

=TITLE class Supplier

=SUBTITLE Live Supply factory

    class Supplier { }

This is a factory for I<live> L<Supply|/type/Supply> objects, which
provides the mechanism for emitting new values onto the supplies:

    my $supplier = Supplier.new;
    my $supply_1 = $supplier.Supply;
    $supply_1.tap(-> $v { say "One $v" });
    my $supply_2 = $supplier.Supply;
    $supply_2.tap(-> $v { say "Two $v" });
    $supplier.emit(42);

Will output:

=for code :lang<text>
One 42
Two 42

I<on demand> supplies are created by the factory methods of the L<Supply|/type/Supply>
class or by the C<supply> keyword. A mixture of a live and on-demand C<Supply> can
be created with a L<Supplier::Preserving|/type/Supplier::Preserving>.

=head1 Methods

=head2 method new

    method new()

The C<Supplier> constructor.

=head2 method Supply

    method Supply(Supplier:D: --> Supply)

This creates a new C<Supply> object to which any values which are emitted
on this supplier are passed. This is the factory for all C<live> supplies.

=head2 method emit

    method emit(Supplier:D: Mu \value)

Sends the given value to all of the taps on all of the supplies created by
C<Supply> on this C<Supplier>.

=head2 method done

    method done(Supplier:D:)

Calls the C<done> callback on all the taps that have one.

    my $supplier = Supplier.new;
    my $supply   = $supplier.Supply;
    $supply.tap(-> $v { say $v }, done => { say "no more answers" });
    $supplier.emit(42);
    $supplier.done;

Will output:

=for code :lang<text>
42
no more answers

=head2 method quit

    multi method quit(Supplier:D: Exception $ex)
    multi method quit(Supplier:D: Str() $message)

Calls the C<quit> callback on all the taps that have one, passing the
exception to them. If called with a L<Str|/type/Str> the exception will be an
L<X::AdHoc|/type/X::AdHoc> with the supplied message.

This is meant for shutting down a supply with an error.

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
