NAME
UniEvent::Streamer::Input - base class for custom producers for streamer
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);
...DESCRIPTION
This is base class for custom input streams, meant to be assigned with UniEvent::Streamer. It is assumed, that some external source will generate data and eof event, and via the UniEvent::Streamer::Input it will be fed into UniEvent::Streamer.
Streamer will use input object as follows: it will call start() once and expect you to start reading data from your source and to call handle_read() every time data arrives. Streamer may call stop_reading()/start_reading() many times to temporarily suspend reading process. When you have no more data to read, you must call handle_eof(). In case of any error you must call handle_data() with error. Streamer will call stop() method once when the process finishes successfully or with error.
METHODS
new()
Constructs new input stream.
If you override this method, you MUST proxy to parent and use return value as $self.
start($loop)
This method will be invoked by Streamer upon start. Executed once per object lifetime.
In this method you are expected to start reading data from somewhere and periodically call handle_read() as data arrives.
When data ends you must call handle_eof().
This method should return undef if no error occured or XS::ErrorCode object otherwise.
NOTE: This is a callback, do not call this method by yourself!
stop()
This method is invoked when 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!
stop_reading()
This method is invoked when Streamer asks to stop reading. This happens when the output can't write so fast and the buffer in Streamer is full. Can be executed multiple times during the object lifetime.
You must not call handle_read()/handle_eof() after this method is called (until start_reading() is called).
NOTE: This is a callback, do not call this method by yourself!
start_reading()
This method is invoked when Streamer asks to start reading again after stop_reading(). Can be executed multiple times during the object lifetime.
After this call, you are expected to call handle_read()/handle_eof() in future.
This method should return undef if no error occured or XS::ErrorCode object otherwise.
NOTE: This is a callback, do not call this method by yourself!
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 Streamer stop, calling user callback with supplied error nested in UniEvent::StreamerError::read_error.
$error must be XS::ErrorCode object. You can use UniEvent::SystemError::* constants to create errors.
$self->handle_read(undef, UniEvent::SystemError::timed_out);handle_eof()
Call this method when there will be no more data.