$Id: README,v 1.10 1999/02/03 14:14:10 troc Exp $

APOLOGIES
=========

Version 0.06 breaks backward compatibility in several small but
fundamental ways.  As a result, programs written in earlier versions
will not work correctly.

These changes were not made lightly.  They are the product much
discussion, testing and benchmarking.  I regret needing to make them,
but I believe they have improved version 0.06 and helped shape POE's
future for the better.

Please accept my deepest apologies for breaking your code.


ABOUT POE
=========

POE is an acronym for Perl Object Environment.

POE is a programming framework for event-driven state machines.

POE is a high-level, functional interface to select, alarm and IPC.

POE is a cooperative multi-threading model, written only in Perl.

POE is a component architecture.

POE does many things.  The sample programs in the tests directory only
begin to scratch the surface.

Despite all this, POE is actually pretty simple.  It starts with a
basic premise and builds upon it.  Most of the things POE are, are
just different ways of looking at it.


COMPATIBILITY
=============

POE has been tested with Perl 5.004_04, 5.005_02, 5.005_53 and
5.005_54 on Linux, FreeBSD, HP-UX, Solaris7, and OS/2.  For more
detailed compatibility information, please see
<http://www.connect.net/gbarr/cpan-test/by-dist/POE.html>.

POE currently does not work on Windows platforms, due to differences
between Windows' and the rest of the world's ioctl and select calls.

POE is suspected to work on MacOS.  If someone could confirm or deny
this, it would be greatly appreciated.

Non-requirements:

POE is compatible with fork(), but it doesn't require it.

If Time::HiRes is available, POE will use it to support
high-resolution event timing.  Nothing untoward happens if it's not.

Requirements:

POE uses POSIX for portability.

Some of POE's tests require a recent IO bundle, but you get that for
free with recent versions of Perl.

If you plan on using Filter::Reference, you'll also need either
Storable or FreezeThaw so it can freeze and thaw data between systems.
Storable tends to be faster.

If you plan on using Filter::HTTPD, you'll need a small world of
modules to go with it: HTTP::Status; HTTP::Request; HTTP::Date; and
URI::URL.

tests/httpd.perl uses Filter::HTTPD, which uses all that other stuff.

tests/preforkedserver.perl uses fork(), which may not be available on
your planet.


AVAILABILITY
============

The latest stable release of POE is available three ways:

  perl -MCPAN -e 'install POE'

  In the /authors/id/R/RC/RCAPUTO/ on your favorite CPAN mirror.

  Or at <http://www.cpan.org/authors/id/R/RC/RCAPUTO/>, if you don't
  have a favorite CPAN mirror.

Beta versions of the next release are available from the author.  They
tend to be mostly stable.


CREDITS
=======

Thanks to Artur Bergman <artur@vogon-solutions.com> (sky) for many
useful suggestions and contributions.  He has had a hand in the design
and/or implementation of most of POE's improvements.

Thanks to Dave Paris <dparis@w3works.com> (a-mused) for benchmark
results, testing, feedback and suggestions.  Version 0.06 runs much
better under high loads thanks to his efforts.

Thanks to Robert Seifer (Crimson) for extreme debugging beyond the
call of duty.  And sanity.


GETTING STARTED
===============

If you've been using POE since before 0.06, please, PLEASE read the
Changes file before installing.  Many things have been broken between
versions 0.05 and 0.06.

To build and test this distribution, type:

  perl Makefile.PL
  make
  make test

Actually, 'make test' doesn't do anything important.  The real tests
exist within the tests directory, and just happen to be examples of
how to use different parts of POE.

Once everything looks good, POE can be installed by typing:

  make install

-- Rocco Caputo / troc@netrus.net / Thank you for reading.
