Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  FEERSUM::CONNECTION::HANDLE (3)

.ds Aq ’


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



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, cant seek back
    # not yet supported, throws exception:
    # $r->poll_cb(sub { .... });

For write handles:

    $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

For both:

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


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


    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 <B>MAYB> 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.

    $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

$r->close() Discards the remainder of the input buffer.
$r->poll_cb(sub { .... }) <B>NOT YET SUPPORTEDB>. PSGI only defined poll_cb for the Writer object.

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

    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.


Jeremy Stashewsky,


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.

Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 FEERSUM::CONNECTION::HANDLE (3) 2015-08-12

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.