GSP
Quick Navigator

Search Site

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

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


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

.ds Aq ’

NAME

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

CONTENTS

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, cant seek back
   
    # not yet supported, throws exception:
    # $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 <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.

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.

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.