The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
tux_perl-0.01
River stage zero No dependents
++
/ Tux

NAME

Tux - Perl extension for Tux webserver

SYNOPSIS

  package Tux::Sample::Template;

  use strict;

  use Tux;
  use Tux::Constants qw/:event/;

  my $html_content;

  BEGIN{
    $html_content = << 'EOT';
  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
  <html>
  <head>
    <title>tux_perl Template</title>
    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
    <meta name="GENERATOR" content="Quanta Plus">
  </head>
  <body>
  <h1>tux_perl Template</h1>
  <hr>
  Congratulation! Your tux_perl is working now!
  </body>
  </html>
  EOT
  }

  sub handler{
    my($r)=@_;

   SWITCH:
    {
      ($r->event==0) && do{
        $r->event(1);
        $r->http_status(200);
        return $r->tux_print_header('Content-Type' => 'text/html');
      };

      ($r->event==1) && do{
        $r->event(2);
        return $r->tux_print($html_content);
      };

      ($r->event==2) && do{
        $r->event(TUX_EVENT_FINISH_REQ);
        return $r->tux_print_http_chunk_eof;
      };

    }
    return 0;
  }

  1;

ABSTRACT

Tux is a VERY FAST http server embedded in Linux kernel. tux_perl is an user space Perl interpreter for Tux. tux_perl is event driven. It can generate dynamic web content quite fast.

DESCRIPTION

tux_perl run in user space as a module of Tux. It inherits the event driven structure of normal Tux module. Minimizing the overhead of process scheduling, it's speed is quite fast.

Because of th event driven structure, there are some differences between developing tux_perl driven modules and traditional CGIs or web scripts.

CONFIG FILE

tux_perl reads the config file for the options and handlers. Usually the config file will be PREFIX/etc/tux_perl.conf.

  imp_lib /usr/lib/perl5/site_perl/5.8.0/i386-linux-thread-multi/auto/Tux/tux_perl_imp.so
  init_log_file /var/log/tux_perl_init.log
  runtime_log_file /var/log/tux_perl_runtime.log
  perl_lib_path /usr/lib/perl5/site_perl/5.8.0/i386-linux-thread-multi
  <perl_module>
          name Static
          lib Tux::Sample::Static
          handler Tux::Sample::Static::handler
  </perl_module>
  <perl_module>
          name Template
          lib Tux::Sample::Template
          handler Tux::Sample::Template::handler
  </perl_module>
imp_lib

    There are tow dynamic libraries for tux_perl. tux_perl.so is loaded bu Tux directly, tux_perl_imp.so is loaded by tux_perl.so. The config file of Tux should be set to load tux_perl.so, and the location of tux_perl_imp.so should be specified in tux_perl.conf with imp_lib option.

    Usually this option is already set by Makefile.

init_log_file

    Because Tux module run in different privileges during the initial time and runtime, two log files are supported. init_log_file will log the information during initial time. Comment out this options with '#' will disable initial time log. This log will be written with root privileges.

runtime_log_file

    runtime_log_file will log the information during runtime. Comment out this options with '#' will disable runtime log. This log will be written with privileges specified in the config file of Tux.

    Notice, because Tux chroot to the DOCROOT before enter user space module. This path is related to the DOCROOT.

perl_lib_path

    Append new Perl library path. Multi paths can be specified with one perl_lib_path option for every path.

perl_module

    The handlers are specified in the <perl_module<gt> sections, one section per handler.

    name

      The name of the handler, which is used in the URL. The URL reads

        http://host/path/tux_perl.tux?name

    lib

      The package name of the handler module. tux_perl will look in the Perl lib path for the module. Please append the path with perl_lib_path if it's not included by default.

    handler

      The method name of the handler.

EVENT DRIVEN AND REQUEST SCHEDULING

To avoid the overhead of process scheduling, non-blocking event driven structure is deployed in Tux. The request are processed when it's READY, and rescheduled when it returned from the handle or called the tux() system call to send result or read other resources.

The code of tux_perl driven module has to be split into several pieces by the tux() system call, because when the tux() system call returned, the original request may be rescheduled and another one may be returned. The module should not continue operating on this request, but exit and kernel will schedule the requests correctly.

All the methods of Tux perl lib which uses tux() system call are prefixed by tux_. Modules should exit after calling these methods:

  return $r->tux_print($html_content);

TUX OBJECT

The tux() system call and the parameter user_req_t are wrapped as a Tux object of Perl. A parameter of class Tux is passed to the handler when it is called.

$r->tux($action)

    The tux method call the tux() system call. The request will be passed as the second argument. Refer to the tux(2) man page and Tux::Constants for the description of $action. Be sure to use Tux::Constants package when calling this method.

      use Tux::Constants qw/:action/;
$r->version_major

    Get the major version of Tux.

$r->version_minor

    Get the minor version of Tux.

$r->version_patch

    Get the patch version of Tux.

$r->http_version

    Get the http version of the request, 0 for HTTP/1.0, 1 for HTTP/1.1 .

$r->http_method

    Get the method of the request, one of METHOD_NONE, METHOD_GET, METHOD_HEAD, METHOD_POST, or METHOD_PUT.

$r->sock

    Socket file descriptor; writing to this will send data to the connected client associated with this request. Do not read from this socket file descriptor; you could potentially confuse the HTTP engine.

$r->event([$event])

    Private, per-request state for use in tux modules. The system will preserve this value as long as a request is active. Passing an argument will set the event.

$r->thread_nr

    Thread index; see discussion of TUX_ACTION_STARTTHREAD in tux(2).

$r->http_status([$status])

    Set the error status as an integer for error reporting. Must be set before tux_print_header() or http_header().

$r->module_index

    Used by the tux daemon to determine which loadable module to associate with a req.

$r->client_host

    The IP address of the host to which sock is connected.

$r->object_addr([$addr],[$length])

    Set to an address for a buffer of at least $r->objectlen size into which to read an object from the URL cache with the TUX_ACTION_READ_OBJECT action. TUX_ACTION_READ_OBJECT must not be called unless $r->objectlen >= 0, and TUX implicitly relies on $r->object_addr being at least $r->objectlen in size.

    Without argument, object_addr returns the object as a string. If only parameter $addr is set, the object_addr will be set to $addr and objectlen will be set to length of $addr. If parameter $length is also set, objectlen will be set to $length.

$r->objectlen([$length])

    The size of a file that satisfies the current request and which is currently living in the URL cache. This is set if a request returns after TUX_ACTION_GET_OBJECT. A module should make sure that the buffer at $r->object_addr is at least $r->objectlen in size before calling TUX_ACTION_READ_OBJECT.

    Passing an argument will set the objectlen.

$r->objectname([$name])

    Specifies the name of a URL to get with the TUX_ACTION_GET_OBJECT action. If the URL is not immediately available (that is, is not in the URL cache), the request is queued and the tux subsystem may go on to other ready requests while waiting.

    Passing an argument will set the objectname.

$r->query([$query])

    The full query string sent from the client. Passing an argument will set the query.

$r->cookies([$cookies])

    If cookies are in the request header, cookies is the string in which the cookies are passed to the module. Passing an argument will set the cookies.

$r->content_type([$content_type])

    The Content-Type header value for the request. Passing an argument will set the content-type.

$r->user_agent([$user_agent])

    The User-Agent header value for the request. Passing an argument will set the User-Agent.

$r->accept([$accept])

    The Accept header value for the request. Passing an argument will set the Accept.

$r->accept_charset([$charset])

    The Accept-Charset header value for the request. Passing an argument will set the Accept-Charset.

$r->accept_encoding([$encoding])

    The Accept-Encoding header value for the request. Passing an argument will set the Accept-Encoding.

$r->accept_language([$language])

    The Accept-Language header value for the request. Passing an argument will set the Accept-Language.

$r->cache_control([$cache_control])

    The Cache-Control header value for the request. Passing an argument will set the Cache-Control.

$r->if_modified_since([$if_modified_since])

    The If-Modified-Since header value for the request. Passing an argument will set the If-Modified-Since.

$r->negotiate([$negotiate])

    The Negotiate header value for the request. Passing an argument will set the Negotiate.

$r->pragma([$pragma])

    The Pragma header value for the request. Passing an argument will set the Pragma.

$r->referer([$referer])

    The Referer header value for the request. Passing an argument will set the Referer.

$r->post_data

    For POST requests, the incoming data is placed in post_data.

$r->new_date

    Returns the current date/time.

$r->keep_alive([$keep_alive])

    The KeepAlive header value for the request. Passing an argument will set the KeepAlive.

$r->http_header([$header_name => $value, ...])

    Generate HTTP response header with inputed header names and values. Transfer-Encoding header will be set to chunked by default. HTTP version will be detected automatic.

$r->http_chunk($string1, $string2, ...)

    Generate a chunk of content. tux_perl support HTTP/1.1 keep alive function with Transfer-Encoding of chunked.

$r->http_chunk_eof

    Generate an EOF symbol for chunk. It's necessary at the end of a HTTP/1.1 response.

$r->tux_print($string1, $string2, ...)

    Print the strings as the body of HTTP response. Strings will be wrapped into a chunk first. Don't send HTTP header with it.

$r->tux_print_header([$header_name => $value, ...])

    Generate the HTTP response header and print it. Refer to the http_header function.

$r->tux_print_http_chunk_eof

    Print the EOF symbol for chunk.

DOCROOT

Tux chroot to the DOCROOT specified at it's config file before calling the user space module. So, the environments of initial time and run time will be different. To resolve the problem, folders can be link to the DOCROOT folder with mount --bind.

  mount --bind /usr /var/www/html/usr

If your module loaded other perl libraries dynamically, /usr/lib is required to link.

EXPORT

None by default.

SEE ALSO

tux(2), Tux::Constants(3)

More information about tux_perl can be found at

  http://tux-perl.sourceforge.net
  http://sourceforge.net/projects/tux-perl

AUTHOR

Yale Huang, <yale@sdf-eu.org>

COPYRIGHT AND LICENSE

Copyright 2002 by Yale Huang

This library is released under the GPL; you can redistribute it and/or modify it under the term of GPL.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 278:

You can't have =items (as at line 283) unless the first thing after the =over is an =item