engine.rb

 This file contains the MUES::Engine class -- the main server class for the
 Multi-User Environment Server (MUES). The server encapsulates and provides a
 simple framework to accomplish the following tasks:

 * Load, configure, and maintain one or more MUES::Environment objects.

 * Handle multiplexed IO through one or more stream abstractions
   (MUES::IOEventStream objects) attached to an IO::Reactor.

 * Provide object persistance for user objects and environments
   (MUES::ObjectStore).

 * Handle incoming connections using one or more configured protocols
   represented by listener objects (MUES::Listener), login and authentication
   (via a MUES::Questionnaire object), and user objects (MUES::User).

 * Coordinate, queue (MUES::EventQueue), and dispatch events (MUES::Event)
   between the Environment objects, User objects, and other subsystems.

 * Execute an event loop which serves as the fundamental unit of time for
   each environment

 == Synopsis

   #!/usr/bin/ruby

   require "mues"

   $ConfigFile = "/opt/mues/server/config.yml"

   # Instantiate the configuration and the server objects
   config = MUES::Config::load( $ConfigFile )
   engine = MUES::Engine::instance

   # Start up and run the server
   puts "Starting up...\n"
   engine.start( config )
   puts "Shut down...\n"

 === Subsystems
 ==== System Startup and Shutdown

 The Engine is started by means of its #start method, and is shut down either
 from inside the server with a MUES::EngineShutdownEvent or from outside by
 calling the #stop method.

 ==== Threads and Thread Routines

 There are currently two thread routines in the Engine: the routine for the
 main thread of execution and the routine which drives IO. The main thread
 loops in the #mainThreadRoutine method, marking each loop by dispatching a
 MUES::TickEvent, and then sleeping for a duration of time set in the main
 configuration file. The #ioThreadRoutine method polls any socket added to the
 engine's reactor object and calls the appropriate callback when an IO event
 occurs. This includes IO for both the MUES::Listener objects and (by default)
 MUES::OutputFilter objects in a MUES::IOEventStream.

 ==== User Authentication/Authorization

 When an incoming connection is detected on one of the Engine's MUES::Listener
 objects, the listener object creates a MUES::OutputFilter appropriate to the
 protocol it is listening for and dispatches a MUES::ListenerConnectEvent. The
 Engine then fetches other appropriate initial filters (e.g., loginsession,
 commandshell, etc.) from the listener. The MUES::LoginSession class can be
 used to present the user with a username/password prompt sequence, and
 dispatch a MUES::UserAuthEvent with the authentication data and two callbacks
 -- one for success and one for failure. The Engine looks up the MUES::User
 object of the user logging in, checks authentication and authorization, and
 calls the appropriate callback. On a successful login, the LoginSession
 creates a MUES::UserLoginEvent and dispatches it to the Engine, which creates
 a MUES::CommandShell for the user, and adds the user to its user table.

 :TODO: The above needs rewriting.

 ==== Event Dispatch and Handling

 The Engine contains the main dispatch mechanism for events in the server in
 the form of two MUES::EventQueue objects. An EventQueue is a prioritized
 scaling thread work crew object which accepts and executes events given to it
 by the server under a restricted permissions level. The Engine has a primary
 queue, which executes most events in the system, and a "privileged" queue,
 which executes events that require greater privileges (MUES::PrivilegedEvent
 objects). It fills these queues itself from the events that are given to its
 #dispatchEvents method, which is typically accessed via the like-named
 #function in MUES::ServerFunctions (in MUES::Mixins).

 Once an event has been given to one queue or the other, it will be picked up
 by a worker thread, which will then consult the registry of handlers to
 determine how to dispatch the event. Objects register themselves as being
 interested in receiving certain kinds of events either through that event
 class's #registerHandlers method, or by mixing in the MUES::Event::Handler
 mixin and then using the #registerHandlerForEvents method.

 See the documentation in lib/mues/EventQueue.rb (MUES::EventQueue),
 lib/mues/Events.rb (MUES::Event and MUES::Event::Handler), and
 lib/mues/Mixins.rb (MUES::ServerFunctions) for more information on the event
 system.

 ==== Environments

 The Engine can host one or more MUES::Environment objects, which are loaded
 either via the server's configuration, or by a user from the command shell via
 a MUES::LoadEnvironmentEvent.

 === Other Stuff

 You can find more about the MUES project at http://mues.FaerieMUD.org/

 == Subversion ID

 $Id: engine.rb 1235 2004-08-21 22:54:36Z ged $

 == Authors

 * Michael Granger <ged@FaerieMUD.org>
 * Jeremiah Chase <phaedrus@FaerieMUD.org>
 * Alexis Lee <red@FaerieMUD.org>

:include: COPYRIGHT

Required files