IO::Async::Sequencer(3User Contributed Perl DocumentatiIO::Async::Sequencer(3)NAME
"IO::Async::Sequencer" - handle a serial pipeline of requests /
responses (EXPERIMENTAL)
SYNOPSIS
When used as a client:
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, $closed ) = @_;
return 0 unless $$buffref =~ s/^(.*)\n//;
my $line = $1;
$line =~ m/^RESPONSE (.*)$/ and
$self->incoming_response( $1 ), return 1;
print STDERR "An error - didn't recognise the line $line\n";
},
marshall_request => sub {
my ( $self, $request ) = @_;
return "REQUEST $request\n";
},
);
$loop->add( $sequencer );
$sequencer->request(
request => "hello",
on_response => sub {
my ( $response ) = @_;
print "The response is: $response\n";
},
);
When used as a server:
my $sequencer = IO::Async::Sequencer->new(
handle => $sock,
on_read => sub {
my ( $self, $buffref, $closed ) = @_;
return 0 unless $$buffref =~ s/^(.*)\n//;
my $line = $1;
$line =~ m/^REQUEST (.*)$/ and
$self->incoming_request( $1 ), return 1;
print STDERR "An error - didn't recognise the line $line\n";
},
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\n";
},
);
DESCRIPTION
This module provides an EXPERIMENTAL subclass of "IO::Async::Stream"
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.
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 HTTP.
Objects in this class can operate in any of three ways:
· A pure client
The object is asked to send requests by the containing code and
invokes response handling code when responses arrive.
· A pure server
The object receives requests from the filehandle, processes them,
and sends responses back, but does not initiate any traffic of its
own.
· Mixed
The object behaves as a mixture of the two; initiating requests, as
well as responding to those of its peer connection.
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.
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.
As it is still EXPERIMENTAL, any details of this class are liable to
change in future versions. It shouldn't yet be relied upon as a stable
interface.
PARAMETERS
The following named parameters may be passed to "new" or "configure":
on_read => CODE
As for IO::Async::Stream. The code here should invoke the
"incoming_request()" or "incoming_response()" methods when
appropriate, after having parsed the incoming stream. See the
SYNOPSIS or EXAMPLES sections for more detail.
Each request can optionally provide its own handler for reading
its response, using the "on_read" key to the "request()"
method. The handler provided to the constructor is only used if
this is not provided.
on_request => CODE
A callback that is invoked when the "incoming_request()" 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.
$on_request->( $self, $token, $request );
The token should be considered as an opaque value - passed into
the "respond()" method when a response is ready, but not
otherwise used or modified.
marshall_request => CODE
marshall_response => CODE
Callbacks that the "request()" or "respond()" methods will use,
respectively, to stream a request or response object into a
string of bytes to write to the underlying file handle.
$string = $marshall_request->( $self, $request );
$string = $marshall_response->( $self, $response );
These are used respectively by the client and server modes.
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.
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.
$sequencer->incoming_request( $request )
To be called from "on_read".
This method informs the sequencer that a new request has arrived. It
will invoke "on_request", passing in a token to identify the request
for stream ordering purposes, and the request itself.
$sequencer->incoming_response( $response )
To be called from "on_read".
This method informs the sequencer that a response has arrived. It will
invoke "on_response" that had been passed to the "request" method that
sent the original request.
PUBLIC METHODS
These methods are intended to be called by the application code using a
subclass of this class.
$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 "on_read" handler to be used when the response to this request
is expected, or by providing an "on_response" handler for when the
default handler invokes "incoming_response()".
The %params hash takes the following arguments:
request => SCALAR
The request value to pass to "marshall_request".
on_response => CODE
A continuation to invoke when a response to this request
arrives from the upstream server. It will be invoked as
$on_response->( $response );
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 "IO::Async::Stream"; i.e.
$on_read->( $self, $buffref, $closed )
This handler should return "undef" when it has finished
handling the response, so that the next one queued can be
invoked (or the default if none exists). It MUST NOT call
"incoming_response()". Instead, the code should directly
implement the behaviour for receipt of a response.
If the "on_read" 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.
$sequencer->respond( $token, $response )
Called in server mode, usually at the end of "on_request", or some
continuation created within it, this method sends a response back
downstream to a client that had earlier requested it.
$token The token that was passed into the "on_request". Used to ensure
responses are sent in the right order.
$response
The response value to pass to "marshall_response".
EXAMPLES
A simple line-based server
The following sequencer implements a simple server which takes and
responds with CRLF-delimited lines.
package LineSequencer;
use base qw( IO::Async::Sequencer );
my $CRLF = "\x0d\x0a"; # More portable than \r\n
sub on_read {
my ( $self, $buffref, $closed ) = @_;
$buffref =~ s/^(.*)$CRLF// and
$self->incoming_request( $1 ), return 1;
return 0;
}
sub marshall_response {
my ( $self, $response ) = @_;
return $response . $CRLF;
}
1;
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 "on_request" like the following.
my $linesequencer = LineSequencer->new(
handle => ...
on_request => sub {
my ( $self, $token, $request ) = @_;
$self->respond( $token, uc $request );
}
);
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
"$self->respond()" in an eventual continuation at the end of performing
its work. The $token is used to identify the request that the response
responds to, so that it can be sent in the correct order.
Per-request "on_read" handler
If an "on_read" handler is provided to the "request()" 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
"incoming_response()" method and the "on_response" 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.
my $sequencer = IO::Async::Sequencer->new(
...
on_read => sub {
my ( $self, $buffref, $closed ) = @_;
print STDERR "Spurious input: $$buffref\n";
$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, $closed ) = @_;
return 0 unless $$buffref =~ s/^(.*)$CRLF//;
my $line = $1;
print STDERR "Got response: $1\n" if $line =~ m/^HAVE (.*)$/;
return undef; # To indicate that this response is finished
}
);
TODO
· Some consideration of streaming errors. How does the "on_read"
signal to the containing object that a stream error has occured? Is
it fatal? Can resynchronisation be attempted later?
· Support, either here or in a different class, for out-of-order
protocols, such as IMAP, where responses can arrive in a different
order than the requests were sent.
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>
perl v5.14.2 2010-06-09 IO::Async::Sequencer(3)
