Linux Manual Pages

Free Software * Books

Source Code

Free Media

Linux

Net::Server::Multiplex

NAME
SYNOPSIS
DESCRIPTION
PROCESS FLOW
CLIENT PROCESSING
HOOKS
TIMEOUTS
CALLBACK INTERFACE
BUGS
AUTHOR
MAINTAINER
LICENSE
SEE ALSO

NAME

Net::Server::Multiplex − Multiplex several connections within one process

SYNOPSIS

  package MyPlexer;
  use base 'Net::Server::Multiplex';
  sub mux_input {
     #...code...
  }
  __PACKAGE__−>run();

DESCRIPTION

This personality is designed to handle multiple connections all within one process. It should only be used with protocols that are guaranteed to be able to respond quickly on a packet by packet basis. If determining a response could take a while or an unknown period of time, all other connections established will block until the response completes. If this condition might ever occur, this personality should probably not be used.

This takes some nice features of Net::Server (like the server listen socket setup, configuration file processing, safe signal handling, convenient inet style STDIN/STDOUT handling, logging features, deamonization and pid tracking, and restartability −SIGHUP) and some nice features of IO::Multiplex (automatic buffered IO and per-file-handle objects) and combines them for an easy-to-use interace.

See examples/samplechat.pl distributed with Net::Server for a simple chat server that uses several of these features.

PROCESS FLOW

The process flow is written in an open, easy to override, easy to hook, fashion. The basic flow is shown below.

  $self−>configure_hook;
  $self−>configure(@_);
  $self−>post_configure;
  $self−>post_configure_hook;
  $self−>pre_bind;
  $self−>bind;
  if( Restarting server ){
     $self−>restart_open_hook();
  }
  $self−>post_bind_hook;
  $self−>post_bind;
  $self−>pre_loop_hook;
  $self−>loop; # This basically just runs IO::Multiplex::loop
  # For routines inside a $self−>loop
  # See CLIENT PROCESSING below
  $self−>pre_server_close_hook;
  $self−>post_child_cleanup_hook;
  $self−>server_close;
  if( Restarting server ){
     $self−>restart_close_hook();
     $self−>hup_server;
     # Redo process again starting with configure_hook
  }

The server then exits.

CLIENT PROCESSING

The following represents the client processing program flow:

  $self−>{server}−>{client} = Net::Server::Proto::TCP−>accept();  # NOTE: Multiplexed with mux_input() below
  if (check_for_dequeue seconds have passed) {
    $self−>run_dequeue();
  }
  $self−>get_client_info;
  $self−>post_accept_hook; # Net::Server style
  if( $self−>allow_deny
      && $self−>allow_deny_hook ){
    # (Net::Server style $self−>process_request() is never called.)
    # A unique client specific object is created
    # for all mux_* methods from this point on.
    $self = __PACKAGE__−>new($self, client);
    $self−>mux_connection; # IO::Multiplex style
    for (every packet received) {
      $self−>mux_input;  # NOTE: Multiplexed with accept() above
    }
  }else{
    $self−>request_denied_hook;
    # Notice that if either allow_deny or allow_deny_hook fails, then
    # new(), mux_connection(), and mux_input() will never be called.
    # mux_eof() and mux_close() will still be called, but using a
    # common listen socket callback object instead of a unique client
    # specific object.
  }
  $self−>mux_eof;
  $self−>post_process_request_hook;
  $self−>mux_close;

This process then loops multiplexing between the accept() for the next connection and mux_input() when input arrives to avoid blocking either one.

HOOKS

The *_hook methods mentioned above are meant to be overridden with your own subroutines if you desire to provide additional functionality.

The loop() method of Net::Server has been overridden to run the loop routine of IO::Multiplex instead. The Net::Server methods may access the IO::Multiplex object at "$self−>{mux}" if desired. The IO::Multiplex methods may access the Net::Server object at "$self−>{net_server}" if desired.

The process_request() method is never used with this personality.

The other Net::Server hooks and methods should work the same.
"$self−>run_dequeue()"

This hook only gets called in conjuction with the check_for_dequeue setting. It will run every check_for_dequeue seconds. Since no forking is done, this hook should run fast in order to prevent blocking the rest of the processing.

TIMEOUTS

set_timeout
To utilize the optional timeout feature of IO::Multiplex, you need to specify a timeout by using the set_timeout method.

$self−>{net_server}−>{mux}−>set_timeout($fh, $seconds_from_now);

$fh may be either a client socket or a listen socket file descriptor within the mux. $seconds_from_now may be fractional to achieve more precise timeouts. This is used in conjuction with mux_timeout, which you should define yourself.

mux_timeout
The main loop() routine will call $obj−>mux_timeout($mux, $fh) when the timeout specified in set_timeout is reached where $fh is the same as the one specified in set_timeout() and $obj is its corresponding object (either the unique client specific object or the main listen callback object) and $mux is the main IO::Multiplex object itself.

CALLBACK INTERFACE

Callback objects should support the following interface. You do not have to provide all of these methods, just provide the ones you are interested in. These are just like the IO::Multiplex hooks except that STDOUT is tied to the corresponding client socket handle for your convenience and to more closely emulate the Net::Server model. However, unlike some other Net::Server personalities, you should never read directly from STDIN yourself. You should define one or more of the following methods:

mux_connection ($mux,$fh)
( OPTIONAL ) Run once when the client first connects if the allow_deny passes. Note that the "$self−>{net_server}−>{server}" property hash may be modified by future connections through Net::Server. Any values within it that this object may need to use later should be copied within its own object at this point.

Example: $self−>{peerport} = $self−>{net_server}−>{server}−>{peerport};

mux_input ($mux,$fh,\$data)
( REQUIRED ) Run each time a packet is read. It should consume $data starting at the left and leave unconsumed data in the scalar for future calls to mux_input.

mux_eof ($mux,$fh,\$data)
( OPTIONAL ) Run once when the client is done writing. It should consume the rest of $data since mux_input() will never be run again.

mux_close ($mux,$fh)
( OPTIONAL ) Run after the entire client socket has been closed. No more attempts should be made to read or write to the client or to STDOUT .

mux_timeout ($mux,$fh)
( OPTIONAL ) Run once when the set_timeout setting expires as explained above.

BUGS

This is only known to work with TCP servers.

If you need to use the IO::Multiplex style set_timeout / mux_timeout interface, you cannot use the Net::Server style check_for_dequeue / run_dequeue interface. It will not work if the check_for_dequeue option is specified. The run_dequeue method is just a compatibility interface to comply with the Net::Server::Fork style run_dequeue but is implemented in terms of the IO::Multiplex style set_timeout and mux_timeout methods.

AUTHOR

Rob Brown <bbb@cpan.org>

MAINTAINER

Paul Seamons <paul@seamons.com>

LICENSE

Opportunity

Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.

Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.

Free Software

Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.

Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.

Free Books

The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.

Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.

Education

Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.

Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.