README
1######################################################################
2 LWP::UserAgent::POE 0.05
3######################################################################
4
5NAME
6 LWP::UserAgent::POE - Drop-in LWP::UserAgent replacement in POE
7 environments
8
9SYNOPSIS
10 use LWP::UserAgent::POE;
11
12 my $ua = LWP::UserAgent::POE->new();
13
14 # The following command looks (and behaves) like it's blocking,
15 # but it actually keeps the POE kernel ticking and processing
16 # other tasks. post() and request() work as well.
17 my $resp = $ua->get( "http://www.yahoo.com" );
18
19 if($resp->is_success()) {
20 print $resp->content();
21 } else {
22 print "Error: ", $resp->message(), "\n";
23 }
24
25 POE::Kernel->run();
26
27DESCRIPTION
28 LWP::UserAgent::POE is a subclass of LWP::UserAgent and works well in a
29 POE environment. It is a drop-in replacement for LWP::UserAgent in
30 systems that are already using LWP::UserAgent synchronously and want to
31 play nicely with POE.
32
33 The problem: LWP::UserAgent by itself is synchronous and blocks on
34 requests until the response from the network trickles in. This is
35 unacceptable in POE, as the POE kernel needs to continue processing
36 other tasks until the HTTP response arrives.
37
38 LWP::UserAgent::POE to the rescue. Its request() method and all related
39 methods like get(), post() etc. work just like in the original. But if
40 you peek under the hood, they're sending a request to a running
41 POE::Component::Client::HTTP component and return a valid $response
42 object when a response from the network is available. Although the
43 program flow seems to be blocked, it's not. LWP::UserAgent::POE works
44 the magic behind the scenes to keep the POE kernel ticking and process
45 other tasks.
46
47 The net effect is that you can use LWP::UserAgent::POE just like
48 LWP::UserAgent in a seemingly synchronous way.
49
50 Note that this module is not a POE component. Instead, it is a subclass
51 of LWP::UserAgent. It is self-contained, it even spawns the
52 POE::Component::Client::HTTP component in its constructor unless there's
53 one already running that has been started by another instance.
54
55 Cookies and other features
56 Just like LWP::UserAgent, LWP::UserAgent::POE supports cookies if you
57 define a cookie jar:
58
59 my $ua = LWP::UserAgent::POE->new(
60 cookie_jar => HTTP::Cookies->new(),
61 );
62
63 Just make sure to pass these parameters to the constructor, see the
64 'Bugs' section below on what hasn't been implemented yet.
65
66 Bugs
67 Currently, you can't call LWP::UserAgent's parameter methods, like
68
69 $ua->timeout();
70
71 as this won't be propagated to the POE component running the HTTP
72 requests. It might be added later. Currently, you have to add it to the
73 constructor, like
74
75 my $ua = LWP::UserAgent->new( timeout => 10 );
76
77 to take effect. LWP::UserAgent::POE translates the LWP::UserAgent
78 parameter names to POE::Component::Client::HTTP's parameters, which are
79 slightly different.
80
81LEGALESE
82 Copyright 2008 by Mike Schilli and Rocco Caputo, all rights reserved.
83 This program is free software, you can redistribute it and/or modify it
84 under the same terms as Perl itself.
85
86AUTHOR
87 The code of this module is based on Rocco Caputo's "pua-defer" code,
88 which has been included with his permission.
89
90 2008, Mike Schilli <cpan@perlmeister.com>
91
92