.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "IO::Async::Sequencer 3pm"
.TH IO::Async::Sequencer 3pm "2012-10-24" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
"IO::Async::Sequencer" \- handle a serial pipeline of requests / responses (EXPERIMENTAL)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
When used as a client:
.PP
.Vb 2
\& use IO::Async::Loop;
\& my $loop = IO::Async::Loop\->new;
\&
\& my $sock = ...
\&
\& my $sequencer = IO::Async::Sequencer\->new(
\&    handle => $sock,
\&
\&    on_read => sub {
\&       my ( $self, $buffref, $eof ) = @_;
\&
\&       return 0 unless $$buffref =~ s/^(.*)\en//;
\&       my $line = $1;
\&
\&       $line =~ m/^RESPONSE (.*)$/ and
\&          $self\->incoming_response( $1 ), return 1;
\&
\&       print STDERR "An error \- didn\*(Aqt recognise the line $line\en";
\&    },
\&
\&    marshall_request => sub {
\&       my ( $self, $request ) = @_;
\&       return "REQUEST $request\en";
\&    },
\& );
\&
\& $loop\->add( $sequencer );
\&
\& $sequencer\->request(
\&    request     => "hello",
\&    on_response => sub {
\&       my ( $response ) = @_;
\&       print "The response is: $response\en";
\&    },
\& );
.Ve
.PP
When used as a server:
.PP
.Vb 2
\& my $sequencer = IO::Async::Sequencer\->new(
\&    handle => $sock,
\&
\&    on_read => sub {
\&       my ( $self, $buffref, $eof ) = @_;
\&
\&       return 0 unless $$buffref =~ s/^(.*)\en//;
\&       my $line = $1;
\&
\&       $line =~ m/^REQUEST (.*)$/ and
\&          $self\->incoming_request( $1 ), return 1;
\&
\&       print STDERR "An error \- didn\*(Aqt recognise the line $line\en";
\&    },
\&
\&    on_request => sub {
\&       my ( $self, $token, $request ) = @_;
\&
\&       # Now to invoke the application logic, whatever it may be
\&       solve_request(
\&          request      => $request,
\&          on_completed => sub {
\&             my ( $response ) = @_;
\&             $self\->respond( $token, $response );
\&          }
\&       );
\&    },
\&
\&    marshall_response => sub {
\&       my ( $self, $response ) = @_;
\&       return "RESPONSE $response\en";
\&    },
\& );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides an \s-1EXPERIMENTAL\s0 subclass of \f(CW\*(C`IO::Async::Stream\*(C'\fR which
may be helpful in implementing serial pipeline-based network protocols of
requests and responses. It deals with low-level details such as pairing up
responses to requests in ordered protocols, and allows a convenient location
to store the line stream marshalling and demarshalling code.
.PP
The intention is that individual network protocols may be implemented as a
subclass of this class, providing the marshalling and demarshalling code
itself, providing a clean implementation to be used by the using code. An
example protocol that would be easy to implement in this way would be \s-1HTTP\s0.
.PP
Objects in this class can operate in any of three ways:
.IP "\(bu" 4
A pure client
.Sp
The object is asked to send requests by the containing code and invokes
response handling code when responses arrive.
.IP "\(bu" 4
A pure server
.Sp
The object receives requests from the filehandle, processes them, and sends
responses back, but does not initiate any traffic of its own.
.IP "\(bu" 4
Mixed
.Sp
The object behaves as a mixture of the two; initiating requests, as well as
responding to those of its peer connection.
.PP
The exact mode of operation of any object is not declared explicitly, but
instead is an artefact of the set of callbacks provided to the constructor or
methods defined by the subclass. Certain callbacks or methods only make sense
for one mode or the other.
.PP
The various operations required can each be provided as callback functions
given in keys to the constructor, or as object methods on a subclass of this
class. Keys passed to the constructor will take precidence over defined
methods.
.PP
As it is still \s-1EXPERIMENTAL\s0, any details of this class are liable to change in
future versions. It shouldn't yet be relied upon as a stable interface.
.SH "PARAMETERS"
.IX Header "PARAMETERS"
The following named parameters may be passed to \f(CW\*(C`new\*(C'\fR or \f(CW\*(C`configure\*(C'\fR:
.IP "on_read => \s-1CODE\s0" 8
.IX Item "on_read => CODE"
As for IO::Async::Stream. The code here should invoke the
\&\f(CW\*(C`incoming_request\*(C'\fR or \f(CW\*(C`incoming_response\*(C'\fR methods when appropriate,
after having parsed the incoming stream. See the \s-1SYNOPSIS\s0 or \s-1EXAMPLES\s0 sections
for more detail.
.Sp
Each request can optionally provide its own handler for reading its response,
using the \f(CW\*(C`on_read\*(C'\fR key to the \f(CW\*(C`request\*(C'\fR method. The handler provided to
the constructor is only used if this is not provided.
.IP "on_request => \s-1CODE\s0" 8
.IX Item "on_request => CODE"
A callback that is invoked when the \f(CW\*(C`incoming_request\*(C'\fR method is called
(i.e. when operating in server mode). It is passed the request, and a token to
identify it when sending a response.
.Sp
.Vb 1
\& $on_request\->( $self, $token, $request );
.Ve
.Sp
The token should be considered as an opaque value \- passed into the
\&\f(CW\*(C`respond\*(C'\fR method when a response is ready, but not otherwise used or
modified.
.IP "marshall_request => \s-1CODE\s0" 8
.IX Item "marshall_request => CODE"
.PD 0
.IP "marshall_response => \s-1CODE\s0" 8
.IX Item "marshall_response => CODE"
.PD
Callbacks that the \f(CW\*(C`request\*(C'\fR or \f(CW\*(C`respond\*(C'\fR methods will use,
respectively, to stream a request or response object into a string of bytes to
write to the underlying file handle.
.Sp
.Vb 1
\& $string = $marshall_request\->( $self, $request );
\&
\& $string = $marshall_response\->( $self, $response );
.Ve
.Sp
These are used respectively by the client and server modes.
.IP "pipeline => \s-1BOOL\s0" 8
.IX Item "pipeline => BOOL"
Optional. Controls whether requests will be pipelined; that is, all requests
will be sent by the client before responses are received. If this option is
disabled, only the first request will be sent. Other requests will be queued
internally, and each will be sent when the response to the previous has been
received. Defaults enabled; supply a defined but false value to disable.
.SH "SUBCLASS METHODS"
.IX Header "SUBCLASS METHODS"
This class is intended as a base class for building specific protocol handling
code on top of. These methods are intended to be called by the specific
subclass, rather than the containing application code.
.ie n .SS "$sequencer\->incoming_request( $request )"
.el .SS "\f(CW$sequencer\fP\->incoming_request( \f(CW$request\fP )"
.IX Subsection "$sequencer->incoming_request( $request )"
To be called from \f(CW\*(C`on_read\*(C'\fR.
.PP
This method informs the sequencer that a new request has arrived. It will
invoke \f(CW\*(C`on_request\*(C'\fR, passing in a token to identify the request for stream
ordering purposes, and the request itself.
.ie n .SS "$sequencer\->incoming_response( $response )"
.el .SS "\f(CW$sequencer\fP\->incoming_response( \f(CW$response\fP )"
.IX Subsection "$sequencer->incoming_response( $response )"
To be called from \f(CW\*(C`on_read\*(C'\fR.
.PP
This method informs the sequencer that a response has arrived. It will invoke
\&\f(CW\*(C`on_response\*(C'\fR that had been passed to the \f(CW\*(C`request\*(C'\fR method that sent the
original request.
.SH "PUBLIC METHODS"
.IX Header "PUBLIC METHODS"
These methods are intended to be called by the application code using a
subclass of this class.
.ie n .SS "$sequencer\->request( %params )"
.el .SS "\f(CW$sequencer\fP\->request( \f(CW%params\fP )"
.IX Subsection "$sequencer->request( %params )"
Called in client mode, this method sends a request upstream, and awaits a
response to it. Can be called in one of two ways; either giving a specific
\&\f(CW\*(C`on_read\*(C'\fR handler to be used when the response to this request is expected,
or by providing an \f(CW\*(C`on_response\*(C'\fR handler for when the default handler invokes
\&\f(CW\*(C`incoming_response\*(C'\fR.
.PP
The \f(CW%params\fR hash takes the following arguments:
.IP "request => \s-1SCALAR\s0" 8
.IX Item "request => SCALAR"
The request value to pass to \f(CW\*(C`marshall_request\*(C'\fR.
.IP "on_response => \s-1CODE\s0" 8
.IX Item "on_response => CODE"
A continuation to invoke when a response to this request arrives from the
upstream server. It will be invoked as
.Sp
.Vb 1
\& $on_response\->( $response );
.Ve
.IP "on_read => \s-1CODE\s0" 8
.IX Item "on_read => CODE"
A callback to use to parse the incoming stream while the response to this
particular request is expected. It will be invoked the same as for
\&\f(CW\*(C`IO::Async::Stream\*(C'\fR; i.e.
.Sp
.Vb 1
\& $on_read\->( $self, $buffref, $eof )
.Ve
.Sp
This handler should return \f(CW\*(C`undef\*(C'\fR when it has finished handling the
response, so that the next one queued can be invoked (or the default if none
exists). It \s-1MUST\s0 \s-1NOT\s0 call \f(CW\*(C`incoming_response\*(C'\fR. Instead, the code should
directly implement the behaviour for receipt of a response.
.PP
If the \f(CW\*(C`on_read\*(C'\fR key is used, it is intended that a specific subclass that
implements a specific protocol would construct the callback code in a method
it provides, intended for the using code to call.
.ie n .SS "$sequencer\->respond( $token, $response )"
.el .SS "\f(CW$sequencer\fP\->respond( \f(CW$token\fP, \f(CW$response\fP )"
.IX Subsection "$sequencer->respond( $token, $response )"
Called in server mode, usually at the end of \f(CW\*(C`on_request\*(C'\fR, or some
continuation created within it, this method sends a response back downstream
to a client that had earlier requested it.
.ie n .IP "$token" 8
.el .IP "\f(CW$token\fR" 8
.IX Item "$token"
The token that was passed into the \f(CW\*(C`on_request\*(C'\fR. Used to ensure responses are
sent in the right order.
.ie n .IP "$response" 8
.el .IP "\f(CW$response\fR" 8
.IX Item "$response"
The response value to pass to \f(CW\*(C`marshall_response\*(C'\fR.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "A simple line-based server"
.IX Subsection "A simple line-based server"
The following sequencer implements a simple server which takes and responds
with CRLF-delimited lines.
.PP
.Vb 1
\& package LineSequencer;
\&
\& use base qw( IO::Async::Sequencer );
\&
\& my $CRLF = "\ex0d\ex0a"; # More portable than \er\en
\&
\& sub on_read {
\&    my ( $self, $buffref, $eof ) = @_;
\&
\&    while( $buffref =~ s/^(.*)$CRLF// ) {
\&       $self\->incoming_request( $1 );
\&    }
\&
\&    return 0;
\& }
\&
\& sub marshall_response {
\&    my ( $self, $response ) = @_;
\&    return $response . $CRLF;
\& }
\&
\& 1;
.Ve
.PP
The server could then be used, for example, as a simple echo server that
replies whatever the client said, in uppercase. This would be done using an
\&\f(CW\*(C`on_request\*(C'\fR like the following.
.PP
.Vb 2
\& my $linesequencer = LineSequencer\->new(
\&    handle => ...
\&
\&    on_request => sub {
\&       my ( $self, $token, $request ) = @_;
\&       $self\->respond( $token, uc $request );
\&    }
\& );
.Ve
.PP
It is likely, however, that any real use of the server in a non-trivial way
would perform much more work than this, and only call \f(CW\*(C`$self\->respond\*(C'\fR
in an eventual continuation at the end of performing its work. The \f(CW$token\fR
is used to identify the request that the response responds to, so that it can
be sent in the correct order.
.ie n .SS "Per-request ""on_read"" handler"
.el .SS "Per-request \f(CWon_read\fP handler"
.IX Subsection "Per-request on_read handler"
If an \f(CW\*(C`on_read\*(C'\fR handler is provided to the \f(CW\*(C`request\*(C'\fR method in client
mode, then that handler will be used when the response to that request is
expected to arrive. This will be used instead of the \f(CW\*(C`incoming_response\*(C'\fR
method and the \f(CW\*(C`on_response\*(C'\fR handler. If every request provides its own
handler, then the one in the constructor would only be used for unrequested
input from the server \- perhaps to generate an error condition of some kind.
.PP
.Vb 2
\& my $sequencer = IO::Async::Sequencer\->new(
\&    ...
\&
\&    on_read => sub {
\&       my ( $self, $buffref, $eof ) = @_;
\&
\&       print STDERR "Spurious input: $$buffref\en";
\&       $self\->close;
\&       return 0;
\&    },
\&
\&    marshall_request => sub {
\&       my ( $self, $request ) = @_;
\&       return "GET $request" . $CRLF;
\&    },
\& );
\&
\& $sequencer\->request(
\&    request => "some key",
\&    on_read => sub {
\&       my ( $self, $buffref, $eof ) = @_;
\&
\&       return 0 unless $$buffref =~ s/^(.*)$CRLF//;
\&       my $line = $1;
\&
\&       print STDERR "Got response: $1\en" if $line =~ m/^HAVE (.*)$/;
\&
\&       return undef; # To indicate that this response is finished
\&    }
\& );
.Ve
.SH "TODO"
.IX Header "TODO"
.IP "\(bu" 4
Some consideration of streaming errors. How does the \f(CW\*(C`on_read\*(C'\fR signal to the
containing object that a stream error has occured? Is it fatal?  Can
resynchronisation be attempted later?
.IP "\(bu" 4
Support, either here or in a different class, for out-of-order protocols, such
as \s-1IMAP\s0, where responses can arrive in a different order than the requests
were sent.
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>