Feersum::Connection::Handle - PSGI-style reader/writer objects.
For read handles:
my $buf; my $r = delete $env{'psgi.input'}; $r->read($buf, $env{CONTENT_LENGTH}); $r->close(); # discards any un-read() data # emits a warning and returns 0: $r->seek(....); # not yet supported, throws exception: # $r->poll_cb(sub { .... });
For write handles:
$w->write("scalar"); $w->write(\"scalar ref"); $w->poll_cb(sub { # use $_[0] instead of $w to avoid a closure $_[0]->write(\"some data"); # can close() or unregister the poll_cb in here $_[0]->close(); });
See the PSGI spec for more information on how read/write handles are used (The Delayed Response and Streaming Body section has details on the writer).
The reader is obtained via $env->{'psgi.input'}.
$env->{'psgi.input'}
$r->read($buf, $len)
Read the first $len bytes of the request body into the buffer specified by $buf (similar to how sysread works).
$len
$buf
The calls to $r->read() will never block. Currently, the entire body is read into memory (or perhaps to a temp file) before the Feersum request handler is even called. This behaviour MAY change. Regardless, Feersum will be doing some buffering so psgix.input.buffered is set in the PSGI env hash.
$r->read()
psgix.input.buffered
$r->seek(...)
Seeking is not supported. Feersum discards input data to conserve memory, but only after it has been read.
$r->close()
Discards the remainder of the input buffer.
$r->poll_cb(sub { .... })
NOT YET SUPPORTED. PSGI only defined poll_cb for the Writer object.
The writer is obtained under PSGI by sending a code/headers pair to the "starter" callback. Under Feersum, calls to $req->start_streaming return one.
$req->start_streaming
$w->write("scalar")
Send the scalar as a "T-E: chunked" chunk.
The calls to $w->write() will never block and data is buffered until transmitted. This behaviour is indicated by psgix.output.buffered in the PSGI env hash (Twiggy supports this too, for example).
$w->write()
psgix.output.buffered
$w->write(\"scalar ref")
Works just like write("scalar") above. This extension is indicated by psgix.body.scalar_refs in the PSGI env hash.
write("scalar")
psgix.body.scalar_refs
$w->close()
Close the HTTP response (which triggers the "T-E: chunked" terminating chunk to be sent).
$w->poll_cb(sub { .... })
Register a callback to be called when the write buffer is empty. Pass in undef to unset. The sub can call close().
undef
close()
A reference to the writer is passed in as the first and only argument to the sub. It's recommended that you use $_[0] rather than closing-over on $w to prevent a circular reference.
$_[0]
$w
Jeremy Stashewsky, stash@cpan.org
stash@cpan.org
Copyright (C) 2010 by Jeremy Stashewsky & Socialtext Inc.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.7 or, at your option, any later version of Perl 5 you may have available.
To install Feersum, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Feersum
CPAN shell
perl -MCPAN -e shell install Feersum
For more information on module installation, please visit the detailed CPAN module installation guide.