—

              
HideShow 78 lines of Pod
=head1 NAME
UniEvent::Streamer - generic connector for read and write streams
=head1 SYNOPSIS
    my $input    = UE::Streamer::FileInput->new("file.txt");
    my $output   = UE::Streamer::StreamOutput->new($connection);
    my $streamer = UE::Streamer->new($input, $output);
    $streamer->start();
    $streamer->finish_callback(sub { ... });
     
    UE::Loop->default->run;
=head1 DESCRIPTION
Streamer redirects byte stream from input stream (aka producer) into output stream (aka consumer).
It automatically synchronizes speed between input and output.
To use Streamer you need to create a streamer input and streamer output object.
Those can be one of the built-in classes (see L<UniEvent::Streamer/"BUILT-IN PRODUCERS AND CONSUMERS">) or your own custom classes.
To create custom input and/or output you need to create a class that inherits from L<UniEvent::Streamer::Input> or L<UniEvent::Streamer::Output>.
See those classes' docs for more details.
=head1 METHODS
=head2 new($input, $output, [$max_buf = 10_000_000], [$loop = default])
Constructs new Streamer object, connecting C<$input> sink to C<$output>.
C<$max_buf> is the buffer size (maximum amount of data to read-ahead from input).
If output is not fast enough and this buffer gets full, then input is paused until some part of the buffer is processed by output.
NOTE: if you use inputs/outputs that works with handles (like C<StreamOutput/StreamInput>), make sure that those handles that you pass to their constructor
use loop C<$loop>. 
=head2 start()
Starts the streamer, i.e. start the process of reading from input and writing to output.
=head2 stop()
Interrupt streaming process. Callback will be called with UniEvent::SystemError::operation_canceled error.
=head2 finish_callback($sub)
=head2 finish_event()
Callback will be called upon completion of streaming process (successful or unsuccessful).
Callback signature:
    my $error = shift;
     
Where C<$error> (if any) is an object of class L<XS::ErrorCode>.
See L<UniEvent/"EVENT CALLBACKS">
=head1 BUILT-IN PRODUCERS AND CONSUMERS
L<UniEvent::Streamer::FileInput>
L<UniEvent::Streamer::FileOutput>
L<UniEvent::Streamer::StreamInput>
L<UniEvent::Streamer::StreamOutput>
=cut