/ 
Feersum-1.506_24
/ Feersum::Connection::Handle

NAME

Feersum::Connection::Handle - PSGI-style reader/writer objects.

SYNOPSIS

For read handles:

my $buf;
my $r = delete $env->{'psgi.input'};
$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't seek back

$r->poll_cb(sub { .... });

For write handles:

$w->write("scalar");
$w->write(\"scalar ref");
$w->write_array(\@some_stuff);
$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();
});

For both:

$h->response_guard(guard { response_is_complete() });

DESCRIPTION

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).

METHODS

Reader methods

The reader is obtained via $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).

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->seek(...)

Seeking is partially supported. Feersum discards skipped-over bytes to conserve memory. Note: SEEK_SET is treated the same as SEEK_CUR (always relative to the current position), since the underlying buffer is consumed as it is read and absolute positioning is not supported.

$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 2 bytes
$r->seek(42,SEEK_SET); # same as SEEK_CUR: discards 42 bytes
$r->seek(-8,SEEK_END); # returns 1 if room, discards skipped bytes
$r->close()

Discards the remainder of the input buffer.

$r->poll_cb(sub { .... })

Register a callback to be called when more request body data is available. The callback receives the Reader object as its argument. Useful for streaming request body reads with Expect: 100-continue.

Writer methods.

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.

$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(\"scalar ref")

Works just like write("scalar") above. This extension is indicated by psgix.body.scalar_refs in the PSGI env hash.

$w->write_array(\@array)

Pass in an array-ref and it works much like the two write() calls above, except it's way more efficient than calling write() over and over. Undefined elements of the array are ignored.

$w->close()

Close the HTTP response (which triggers the "T-E: chunked" terminating chunk to be sent). This method is implicitly called when the last reference to the writer is dropped.

$w->poll_cb(sub { .... })

Register a callback to be called when the write buffer drains to (or below) the server's wbuf_low_water threshold (default: 0, i.e. empty). Pass in undef to unset. The sub can call 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.

$w->return_from_psgix_io($io)

Returns control of the socket back to Feersum after psgix.io was used. This is the PSGI-handle equivalent of $req->return_from_io($io) on the connection object. See "return_from_io" in Feersum::Connection for details.

$w->sendfile($fh [, $offset, $length])

Send file contents using zero-copy sendfile(2) system call. Linux only. The file handle should be a regular file opened for reading. The response should have a Content-Length header set appropriately. After calling sendfile(), call close() on the writer.

Optional $offset (bytes to skip from start, default 0) and $length (bytes to send, default remainder of file) allow sending a portion of the file.

Note: Not supported for HTTP/2 responses. Use write() instead.

my $w = $req->start_streaming(200, [
    'Content-Type' => 'application/octet-stream',
    'Content-Length' => -s $filename,
]);
open my $fh, '<', $filename or die $!;
$w->sendfile($fh);
close $fh;
$w->close();

Common methods.

Methods in common to both types of handles.

$h->response_guard($guard)

Register a guard to be triggered when the response is completely sent and the socket is closed. A "guard" in this context is some object that will do something interesting in its DESTROY/DEMOLISH method. For example, Guard.

The guard is *not* attached to this handle object; the guard is attached to the response.

psgix.output.guard is the PSGI-env extension that indicates this method.

$h->fileno

Returns the file descriptor number for this connection.

AUTHOR

Jeremy Stashewsky, stash@cpan.org

COPYRIGHT AND LICENSE

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.