view release on metacpan or  search on metacpan

lib/HTTP/Server/Multiplex.pod  view on Meta::CPAN

=head2 Virtual host administration

$obj-E<gt>B<addVirtualHost>(VHOST|PACKAGE|HASH-of-OPTIONS|OPTIONS)

=over 4

Adds a new virtual host to the knowledge of the daemon.  Can be used
at run-time.  See L<HTTP::Server::VirtualHost::new()|HTTP::Server::VirtualHost/"Constructors"> for OPTIONS.
The added virtual host object is returned.

=back

$obj-E<gt>B<removeVirtualHost>(VHOST|NAME|ALIAS)

=over 4

Remove all name and alias registrations for the indicated virtual host.
Silently ignores non-existing vhosts.  The removed virtual host object
is returned.

=back

$obj-E<gt>B<virtualHost>(NAME)

=over 4

=back

=head1 DETAILS

=head2 HTTP::Daemon/mod_perl differ from this approach

The LWP network library is very solid and provides a full HTTP/1.1
daemon named HTTP::Daemon.  The logic of that daemon was used to
create the code for this module.  Both LWP and Apache's mod_perl start
many processes, for each requesting client one.  What we do here is to
have only one process to serve many clients at the same time.

HTTP::Daemon and mod_perl are based on processes and threads to handle
requests in parallel.  The advantage is that disturbances and delays in
handling one client's request are not brothering the other processes, the
other clients.  As disadvantage, it quite hard to share user session
information and do caching.  Solutions are found in databases and the
mem-cache daemon to share data, and use locking to synchronize.

This L<HTTP::Server::Multiplex|HTTP::Server::Multiplex> module uses only one process to handle
all requests, by serving many client connections together.  The base
is laid in IO::Multiplex, which is a smart C<select(2)> call (you may
need to read-up on that Operating System feature).  The single process
spends all its time handling one request, until IO has to be done.
When waiting for that IO to happen, it will handle available request
from other connections.

Advantages of this approach: no heavy forking, no complex synchronizing
between processes and very simple caching.  Most importantly: the whole
code is a critical section which avoid the need for locking.  Very fast
and very simple -in concept.

Disadvantages are also plentifold: you have to be careful with any IO
to use the IO::Multiplex select loop, and busy-waits (for reading files,
acquiring locks, database output, hostname lookups, sleep) are blocking
all other clients.  Any bug in your software can break the daemon,
and therewith the whole service.

=head2 Features

The following common needs for http servers are implemented:

=over 4

=item HTTP/1.1 (and 1.0 and older)

Multiple requests can use one connection. Requests can arrive asynchronously
from the processing, queuing-up while processed in order.

=item Virtual Hosts

Configure multiple websites, handled by this single daemon.  See
L<HTTP::Server::VirtualHost|HTTP::Server::VirtualHost>.  Each website (virtual host) has its own
directories where the information is taken from, each with a set access
restrictions (allow/deny), rewrite rules, location, etc.  See
L<HTTP::Server::Directory|HTTP::Server::Directory>

=item Critical section

With forking servers, it is difficult to synchronize between threads and
processes: you have to lock or use databases to create critical sections.
In this implementation, the whole program runs in one big critical
section, unless you do IO. Of course, each processing should take little
time, to avoid long response delays for other connections.

=item Asynchronous processing

In case you task does difficult I/O or long computation, you can start
a seperate process with L<HTTP::Server::Connection::async()|HTTP::Server::Connection/"Constructors">.  Be aware
that this comes with a penalty.

=item Sessions

The same user can have multiple connections to the daemon, which use a
single session definition.  This way, the cache of the user's information
cannot get out-of-sync.  See L<HTTP::Server::Session|HTTP::Server::Session>.

=back

=head3 Missing features

=over 4

=item CGI

Asynchronous execution of external scripts, according to the CGI
protocol.  This is not too hard to implement, it just takes some
time.

=back

=head2 Microsoft Windows Limitations

Microsofts POSIX implementation does support the select() call, which