=head1 NAME

UniEvent::Streamer::Input - base class for custom producers for streamer


=head1 SYNOPSYS

    package MyInput;
    use parent 'UniEvent::Streamer::Input';
    use 5.012;
    
    sub new {
        my ($class, ...) = @_;
        my $self = $class->SUPER::new();
        ...
        return $self;
    }
    
    sub start         { ... }
    sub start_reading { ... }
    sub stop_reading  { ... }
    sub stop          { ... }

    ...
    
    my $input = MyInput->new(...);
    my $streamer = UE::Streamer->new($input, $output);
    ...



=head1 DESCRIPTION

This is base class for custom input streams, meant to be assigned with L<UniEvent::Streamer>.
It is assumed, that some external source will generate data and eof event, and
via the L<UniEvent::Streamer::Input> it will be fed into L<UniEvent::Streamer>.

C<Streamer> will use input object as follows: it will call C<start()> once and expect you to start reading data from your source
and to call C<handle_read()> every time data arrives. C<Streamer> may call C<stop_reading()/start_reading()> many times to temporarily suspend reading process.
When you have no more data to read, you must call C<handle_eof()>. In case of any error you must call C<handle_data()> with error. C<Streamer> will call C<stop()>
method once when the process finishes successfully or with error.



=head1 METHODS

=head2 new()

Constructs new input stream.

If you override this method, you MUST proxy to parent and use return value as C<$self>.


=head2 start($loop)

This method will be invoked by C<Streamer> upon start. Executed once per object lifetime.

In this method you are expected to start reading data from somewhere and periodically call C<handle_read()> as data arrives.

When data ends you must call C<handle_eof()>.

This method should return C<undef> if no error occured or L<XS::ErrorCode> object otherwise.

NOTE: This is a callback, do not call this method by yourself!


=head2 stop()

This method is invoked when C<Streamer> finishes. Executed once per object lifetime. No any further I/O is expected.

In this method you are expected to finalize reading and release all resources.

NOTE: This is a callback, do not call this method by yourself!


=head2 stop_reading()

This method is invoked when C<Streamer> asks to stop reading. This happens when the output can't write so fast and the buffer in C<Streamer> is full.
Can be executed multiple times during the object lifetime.

You must not call C<handle_read()>/C<handle_eof()> after this method is called (until C<start_reading()> is called).

NOTE: This is a callback, do not call this method by yourself!


=head2 start_reading()

This method is invoked when C<Streamer> asks to start reading again after C<stop_reading()>. Can be executed multiple times during the object lifetime.

After this call, you are expected to call C<handle_read()>/C<handle_eof()> in future.

This method should return C<undef> if no error occured or L<XS::ErrorCode> object otherwise.

NOTE: This is a callback, do not call this method by yourself!


=head2 handle_read($data, [$error])

You must call this method every time you have another chunk of data read.

If you got an error while reading data, call this method with no data (it is ignored) and error.
This will make C<Streamer> stop, calling user callback with supplied error nested in C<UniEvent::StreamerError::read_error>.

C<$error> must be L<XS::ErrorCode> object. You can use UniEvent::SystemError::* constants to create errors.

    $self->handle_read(undef, UniEvent::SystemError::timed_out);


=head2 handle_eof()

Call this method when there will be no more data.

=cut
