
			 Parallel User Agent
                        ---------------------

(c) 1997,1998 Marc Langheinrich

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

1. What is it?
--------------
ParallelUserAgent (or PUA for short) is an extension of the existing
libwww5.x distribution. It allows you to connect to download several
Web pages in _parallel_, without having to request each page one after
the other. 

Instead of retrieving each single page using LWP::UserAgent::request
or ::simple_request methods, you first "register" all pages that you
wish to download in parallel and then call PUA's "wait" method, which
will then make all the necessary connections and download the
pages. 

You can define callback routines which will be called whenever a
connection is established, is cut off, new data comes in or a request
finishes. The subroutines can be global for all requests you
registered, or different for every single request. 

Callbacks for example allow you to print status updates as the
responses come in, or even immediately post follow-up requests based
on the responses, all within the same single "wait" cycle.

2. How to install it?
---------------------

PUA finally comes with an out-of-the-box installation setup. All you
have to do is the usual

perl Makefile.PL
make
make test
make install

Previous versions of PUA asked you to replace a few standard modules
that came with libwww5.x. As of version 2.30, PUA will install all of
its modules into the LWP::Parallel subtree, so that your previous
libwww installation remains unchanged!

However, it also requires at least version 5.20 of the libwww
distribution, since it relies on features that were not available in
earlier versions. If you are using a different version then the ones
listed below, either upgrade to the newest libwww distribution, or try
running the testscript ("make test") and see if it tests ok anyways
:-) 

*** Warning: The newest version of libwww (5.41 and up) breaks a lot
*** of compatibilities! This version of ParallelUserAgent will not 
*** work with these new versions! Please use libwww-5.36 or wait until
*** an update of this package is available!


Checked versions so far:

*******	libwww-5.41                     not ok! ********
	libwww-5.20 - 5.36		ok
	libwww-5.19			untested
	libwww-5.18 and below		not ok!

Note: For optimal performance you shoul use the _latest_ version of 
      libwww-perl that is listed above (i.e. 5.36).

***** Look into the t/ subdirectory in this distribution for *****
***** some examples on how to use this library!              *****


Remarks for users upgrading from ParallelUA 2.20:
------------------------------------------------- 

You should start out by installing a clean copy of the latest
libwww5.x package, which should overwrite any existing PUA modules
which used to replace some of the LWP modules. 

The new PUA distribution will still offer the LWP::ParallelUA and
LWP::RobotPUA modules for backward compatibility, but you are
encouraged to start any new projects using the "local" modules now
residing under the LWP::Parallel subtree, namely
LWP::Parallel::UserAgent and LWP::Parallel::RobotUA.

The old "TestScript.pl" that used to come with versions 2.20 and below
can be found in t/TestScript.pl and can be used to check backward
compatibility (or can also be used to get a somewhat bigger example on
how to use this module).
 

3. Questions, comments, etc.
----------------------------

Question about how to use the underlying LWP library should be
directed to the comp.lang.perl.modules USENET Newsgroup.  

Bug reports and suggestions for improvements can be sent to the
<libwww-perl@ics.uci.edu> mailing list.  This mailing list is also the
place for general discussions and development of the libwww-perl
package. 

You can join the mailing list by sending a message to
<libwww-perl-request@ics.uci.edu> with "Subscribe" as subject.
            ^^^^^^^^


COPYRIGHT

  © 1997-1998 Marc Langheinrich. All rights reserved.

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


Have fun!

--
$Revision: 1.8 $





