MAN page from Mandrake Other perl-LWPng-alpha-0.23-1.i386.rpm

lib::LWP::Conn

Section: User Contributed Perl Documentation (3)
Updated: perl 5.004, patch 04
Index

NAME

LWP::Conn - event driven protocol module interface

SYNOPSIS

  use LWP::Conn::XXX;  $conn = LWP::Conn::XXX->new(ManagedBy => $mgr,                              Host      => $host,                              Port      => $port,                              #...                             );

DESCRIPTION

The LWP::Conn objects represent a connection to some server where oneor more request/response exchanges can take place. There aredifferent subclasses for various types of the underlying (network)protocols. (Talking about `subclasses' is kind of a lie, since thebase-class does not really manifest itself as any real code.)

LWP::Conn objects conform to the following interfaces when interactingwith their manager object (passed in as parameter during creation).For the normal setup, then manager will be a LWP::Server object.

An LWP::Conn object is contructed with the new() method. It takeshash-style arguments and the `ManagedBy' parameter is the only whichis mandatory for any LWP::Conn subclass. It should be an reference tothe manager object that will get method callbacks when various eventshappen. Other parameters might be mandatory depending on the specificsubclass.

  $conn = LWP::Conn::XXX->new(MangagedBy => $mgr,                              Host => $host,                              Port => $port,                              ...);

The constructor will return a reference to the LWP::Conn object orundef. If a connection object is returned, then the manager shouldwait for callbacks methods to be invoked on itself. A return ofundef will either indicate than we can't connect to the specifiedserver or that all requests has already been processed. A manager canknow the difference based on whether get_request() has been invoked onit or not.

The following methods are invoked by the created LWP::Conn object ontheir manager. The first two manage the request queue. The lastthree let the manager be made aware of the state of the connection.

  $mgr->get_request($conn);  $mgr->pushback_request($conn, @requests);

  $mgr->connection_active($conn);  $mgr->connection_idle($conn);  $mgr->connection_closed($conn);

The get_request() method should return a single LWP::Request objector undef if there are no more requests to process. It is passed areference to the connection object as argument. If the connectionobjects discover that it has been too greedy (calling get_request()too many times), then it might want to return unprocessed request backto the mangager. It does so by calling the pushback_request() methodwith a reference to itself and one or more request objects asarguments. The first request obtained by get_request() should neverbe pushed back.

The following two methods can be invoked (usually by the manager) on aliving $conn object. The activate() method can be invoked on a(usually `idle') connection to make it start calling get_request()again. The stop() kills the connection (whatever state it is in).

  $conn->activate;  $conn->stop;

When a connection has received a response, then it will invoke thefollowing two methods on the request object (obtained usingget_request()).

  $req->response_data($data, $res);  $req->response_done($res);

The response_data() method is invoked repeatedly as the body contentof the response is received from the network. Invocation of thismethod is optional and depends on the kind of connection object thisis. The response_done() method is always invoked once for eachrequest obtained. It is called when the complete response has beenreceived.

COPYRIGHT

This library is free software; you can redistribute it and/ormodify it under the same terms as Perl itself.

This document was created byman2html,using the manual pages.