.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Feersum::Connection::Handle 3pm"
.TH Feersum::Connection::Handle 3pm "2018-03-22" "perl v5.26.1" "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"
Feersum::Connection::Handle \- PSGI\-style reader/writer objects.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
For read handles:
.PP
.Vb 5
\&    my $buf;
\&    my $r = delete $env{\*(Aqpsgi.input\*(Aq};
\&    $r\->read($buf, 1, 1); # read the second byte of input without moving offset
\&    $r\->read($buf, $env{CONTENT_LENGTH}); # append the whole input
\&    $r\->close(); # discards any un\-read() data
\&
\&    # assuming the handle is "open":
\&    $r\->seek(2,SEEK_CUR); # returns 1, discards skipped bytes
\&    $r\->seek(\-1,SEEK_CUR); # returns 0, can\*(Aqt seek back
\&    
\&    # not yet supported, throws exception:
\&    # $r\->poll_cb(sub { .... });
.Ve
.PP
For write handles:
.PP
.Vb 9
\&    $w\->write("scalar");
\&    $w\->write(\e"scalar ref");
\&    $w\->write_array(\e@some_stuff);
\&    $w\->poll_cb(sub {
\&        # use $_[0] instead of $w to avoid a closure
\&        $_[0]\->write(\e"some data");
\&        # can close() or unregister the poll_cb in here
\&        $_[0]\->close();
\&    });
.Ve
.PP
For both:
.PP
.Vb 1
\&    $h\->response_guard(guard { response_is_complete() });
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
See the \s-1PSGI\s0 spec for more information on how read/write handles are used
(The Delayed Response and Streaming Body section has details on the writer).
.SH "METHODS"
.IX Header "METHODS"
.SS "Reader methods"
.IX Subsection "Reader methods"
The reader is obtained via \f(CW\*(C`$env\->{\*(Aqpsgi.input\*(Aq}\*(C'\fR.
.ie n .IP """$r\->read($buf, $len)""" 4
.el .IP "\f(CW$r\->read($buf, $len)\fR" 4
.IX Item "$r->read($buf, $len)"
Read the first \f(CW$len\fR bytes of the request body into the buffer specified by
\&\f(CW$buf\fR (similar to how sysread works).
.Sp
The calls to \f(CW\*(C`$r\->read()\*(C'\fR 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 \fB\s-1MAY\s0\fR change. Regardless, Feersum
will be doing some buffering so \f(CW\*(C`psgix.input.buffered\*(C'\fR is set in the \s-1PSGI\s0 env
hash.
.ie n .IP """$r\->seek(...)""" 4
.el .IP "\f(CW$r\->seek(...)\fR" 4
.IX Item "$r->seek(...)"
Seeking is partially supported.  Feersum discards skipped-over bytes to
conserve memory.
.Sp
.Vb 6
\&    $r\->seek(0,SEEK_CUR);  # returns 1
\&    $r\->seek(\-1,SEEK_CUR); # returns 0
\&    $r\->seek(\-1,SEEK_SET); # returns 0
\&    $r\->seek(2,SEEK_CUR); # returns 1, discards skipped bytes
\&    $r\->seek(42,SEEK_SET); # returns 1 if room, discards skipped bytes
\&    $r\->seek(\-8,SEEK_END); # returns 1 if room, discards skipped bytes
.Ve
.ie n .IP """$r\->close()""" 4
.el .IP "\f(CW$r\->close()\fR" 4
.IX Item "$r->close()"
Discards the remainder of the input buffer.
.ie n .IP """$r\->poll_cb(sub { .... })""" 4
.el .IP "\f(CW$r\->poll_cb(sub { .... })\fR" 4
.IX Item "$r->poll_cb(sub { .... })"
\&\fB\s-1NOT YET SUPPORTED\s0\fR.  \s-1PSGI\s0 only defined poll_cb for the Writer object.
.SS "Writer methods."
.IX Subsection "Writer methods."
The writer is obtained under \s-1PSGI\s0 by sending a code/headers pair to the
\&\*(L"starter\*(R" callback.  Under Feersum, calls to \f(CW\*(C`$req\->start_streaming\*(C'\fR
return one.
.ie n .IP """$w\->write(""scalar"")""" 4
.el .IP "\f(CW$w\->write(``scalar'')\fR" 4
.IX Item "$w->write(""scalar"")"
Send the scalar as a \*(L"T\-E: chunked\*(R" chunk.
.Sp
The calls to \f(CW\*(C`$w\->write()\*(C'\fR will never block and data is buffered until
transmitted.  This behaviour is indicated by \f(CW\*(C`psgix.output.buffered\*(C'\fR in the
\&\s-1PSGI\s0 env hash (Twiggy supports this too, for example).
.ie n .IP """$w\->write(\e""scalar ref"")""" 4
.el .IP "\f(CW$w\->write(\e``scalar ref'')\fR" 4
.IX Item "$w->write(""scalar ref"")"
Works just like \f(CW\*(C`write("scalar")\*(C'\fR above.  This extension is indicated by
\&\f(CW\*(C`psgix.body.scalar_refs\*(C'\fR in the \s-1PSGI\s0 env hash.
.ie n .IP """$w\->write_array(\e@array)""" 4
.el .IP "\f(CW$w\->write_array(\e@array)\fR" 4
.IX Item "$w->write_array(@array)"
Pass in an array-ref and it works much like the two \f(CW\*(C`write()\*(C'\fR calls above,
except it's way more efficient than calling \f(CW\*(C`write()\*(C'\fR over and over.
Undefined elements of the array are ignored.
.ie n .IP """$w\->close()""" 4
.el .IP "\f(CW$w\->close()\fR" 4
.IX Item "$w->close()"
Close the \s-1HTTP\s0 response (which triggers the \*(L"T\-E: chunked\*(R" terminating chunk
to be sent).  This method is implicitly called when the last reference to the
writer is dropped.
.ie n .IP """$w\->poll_cb(sub { .... })""" 4
.el .IP "\f(CW$w\->poll_cb(sub { .... })\fR" 4
.IX Item "$w->poll_cb(sub { .... })"
Register a callback to be called when the write buffer is empty.  Pass in
\&\f(CW\*(C`undef\*(C'\fR to unset.  The sub can call \f(CW\*(C`close()\*(C'\fR.
.Sp
A reference to the writer is passed in as the first and only argument to the
sub.  It's recommended that you use \f(CW$_[0]\fR rather than closing-over on \f(CW$w\fR
to prevent a circular reference.
.SS "Common methods."
.IX Subsection "Common methods."
Methods in common to both types of handles.
.ie n .IP """$h\->response_guard($guard)""" 4
.el .IP "\f(CW$h\->response_guard($guard)\fR" 4
.IX Item "$h->response_guard($guard)"
Register a guard to be triggered when the response is completely sent and the
socket is closed.  A \*(L"guard\*(R" in this context is some object that will do
something interesting in its \s-1DESTROY/DEMOLISH\s0 method. For example, Guard.
.Sp
The guard is *not* attached to this handle object; the guard is attached to
the response.
.Sp
\&\f(CW\*(C`psgix.output.guard\*(C'\fR is the PSGI-env extension that indicates this method.
.ie n .IP """$h\->fileno""" 4
.el .IP "\f(CW$h\->fileno\fR" 4
.IX Item "$h->fileno"
Returns the file descriptor number for this connection.
.SH "AUTHOR"
.IX Header "AUTHOR"
Jeremy Stashewsky, \f(CW\*(C`stash@cpan.org\*(C'\fR
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2010 by Jeremy Stashewsky & Socialtext Inc.
.PP
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.