merb-core 0.9.8 → 0.9.9

data/lib/merb-core/dispatch/worker.rb

@@ -3,10 +3,24 @@ module Merb
     
     attr_accessor :thread
     
+    # ==== Returns
+    # Merb::Worker:: instance of a worker.
+    # 
+    # @api private
+    def self.start
+      new
+    end
+    
+    # Creates a new worker thread that loops over the work queue.
+    # 
+    # @api private
     def initialize
       @thread = Thread.new { loop { process_queue } }
     end
     
+    # Processes tasks in the Merb::Dispatcher.work_queue.
+    # 
+    # @api private
     def process_queue
       begin
         while blk = Merb::Dispatcher.work_queue.pop
@@ -21,8 +35,8 @@ module Merb
       rescue Exception => e
         Merb.logger.warn! %Q!Worker Thread Crashed with Exception:\n#{Merb.exception(e)}\nRestarting Worker Thread!
         retry
-      end    
+      end
     end
     
   end
-end    
+end

data/lib/merb-core/gem_ext/erubis.rb

@@ -1,5 +1,9 @@
 require 'erubis'
 module Erubis
+  # This adds support for embedding the return value of a block call:
+  #   <%= foo do %>...<% end =%>
+  #
+  # @api private
   module Basic::Converter
     def convert_input(src, input)
       pat = @pattern

data/lib/merb-core/plugins.rb

@@ -2,10 +2,15 @@ module Merb
 
   module Plugins
 
+    # Returns the configuration settings hash for plugins. This is prepopulated from
+    # Merb.root / "config/plugins.yml" if it is present.
+    #
     # ==== Returns
     # Hash::
     #   The configuration loaded from Merb.root / "config/plugins.yml" or, if
     #   the load fails, an empty hash whose default value is another Hash.
+    #
+    # @api plugin
     def self.config
       @config ||= begin
         # this is so you can do Merb.plugins.config[:helpers][:awesome] = "bar"
@@ -25,12 +30,16 @@ module Merb
 
     # ==== Returns
     # Array(String):: All Rakefile load paths Merb uses for plugins.
+    #
+    # @api plugin
     def self.rakefiles
       Merb.rakefiles
     end
     
     # ==== Returns
     # Array(String):: All Generator load paths Merb uses for plugins.
+    #
+    # @api plugin
     def self.generators
       Merb.generators
     end
@@ -49,6 +58,8 @@ module Merb
     # if defined(Merb::Plugins)
     #   Merb::Plugins.add_rakefiles "merb_sequel" / "merbtasks"
     # end
+    #
+    # @api plugin
     def self.add_rakefiles(*rakefiles)
       Merb.add_rakefiles(*rakefiles)
     end
@@ -60,6 +71,8 @@ module Merb
     #
     # This is the recommended way to register your plugin's generators
     # in Merb.
+    #
+    # @api plugin
     def self.add_generators(*generators)
       Merb.add_generators(*generators)
     end

data/lib/merb-core/rack.rb

@@ -23,5 +23,6 @@ module Merb
     autoload :ConditionalGet,      'merb-core/rack/middleware/conditional_get'
     autoload :Csrf,                'merb-core/rack/middleware/csrf'
     autoload :StreamWrapper,       'merb-core/rack/stream_wrapper'
+    autoload :Helpers,             'merb-core/rack/helpers'
   end # Rack
 end # Merb

data/lib/merb-core/rack/adapter.rb

@@ -5,6 +5,7 @@ module Merb
     class Adapter
 
       class << self
+        # Get a rack adapter by id. 
         # ==== Parameters
         # id<String>:: The identifier of the Rack adapter class to retrieve.
         #

data/lib/merb-core/rack/adapter/abstract.rb

@@ -2,30 +2,83 @@ module Merb
   module Rack
     class AbstractAdapter
 
+      # This method is designed to be overridden in a rack adapter.  It 
+      # will be called to start a server created with the new_server method.
+      # This is called from the AbstractAdapter start method.
+      #
+      # @api plugin
+      # @overridable
+      def self.start_server
+        raise NotImplemented
+      end
+      
+      # This method is designed to be overridden in a rack adapter.  It will
+      # be called to create a new instance of the server for the adapter to 
+      # start.  The adapter should attempt to bind to a port at this point. 
+      # This is called from the AbstractAdapter start method.
+      #
+      # ==== Parameters
+      # port<Integer>:: The port the server should listen on
+      #
+      # @api plugin
+      # @overridable
+      def self.new_server(port)
+        raise NotImplemented
+      end
+      
+      # This method is designed to be overridden in a rack adapter.  It will
+      # be called to stop the adapter server.  
+      #
+      # ==== Parameters
+      # status<Integer>:: The exit status the adapter should exit with. 
+      #
+      # ==== Returns
+      # Boolean:: True if the server was properly stopped.  
+      #
+      # @api plugin
+      # @overridable
+      def self.stop(status)
+        raise NotImplemented
+      end
+
       # Spawn a new worker process at a port.
+      #
+      # ==== Parameters
+      # port<Integer>:: The port to start the worker process on. 
+      #
+      # @api private
       def self.spawn_worker(port)
-        child_pid = Kernel.fork
-        start_at_port(port, @opts) unless child_pid
+        worker_pid = Kernel.fork
+        start_at_port(port, @opts) unless worker_pid
 
-        # If we have a child_pid, we're in the parent. If we're
-        throw(:new_worker) unless child_pid
+        # If we have a worker_pid, we're in the parent.
+        throw(:new_worker) unless worker_pid
 
-        @pids[port] = child_pid
-        $CHILDREN = @pids.values
+        @pids[port] = worker_pid
+        $WORKERS = @pids.values
       end
 
       # The main start method for bootloaders that support forking.
+      # This method launches the adapters which inherit using the 
+      # new_server and start_server methods.  This method should not
+      # be overridden in adapters which want to fork.  
+      #
+      # ==== Parameters
+      # opts<Hash>:: A hash of options
+      #   socket: the socket to bind to
+      #   port: the port to bind to
+      #   cluster: the number 
+      #
+      # @api private
       def self.start(opts={})
         @opts = opts
-        $CHILDREN ||= []
+        $WORKERS ||= []
         parent = nil
 
         @pids = {}
         port = (opts[:socket] || opts[:port]).to_i
         max_port = Merb::Config[:cluster] ? Merb::Config[:cluster] - 1 : 0
 
-        Merb.logger.warn! "Cluster: #{max_port}"
-
         # If we only have a single merb, just start it up and dispense with
         # the spawner/worker setup.
         if max_port == 0
@@ -36,7 +89,7 @@ module Merb
         $0 = process_title(:spawner, port)
 
         # For each port, spawn a new worker. The parent will continue in
-        # the loop, while the child will throw :new_worker and be booted
+        # the loop, while the worker will throw :new_worker and be booted
         # out of the loop.
         catch(:new_worker) do
           0.upto(max_port) do |i|
@@ -64,7 +117,7 @@ module Merb
                 ensure
                   # If there was no worker with that PID, the status was non-0
                   # (we send back a status of 128 when ABRT is called on a 
-                  # child, and Merb.fatal! exits with a status of 1), or if
+                  # worker, and Merb.fatal! exits with a status of 1), or if
                   # Merb is in the process of exiting, *then* don't respawn.
                   # Note that processes killed with kill -9 will return no
                   # exitstatus, and we respawn them.
@@ -88,11 +141,21 @@ module Merb
 
       end
 
+      # Fork a server on the specified port and start the app.
+      #
+      # ==== Parameters
+      # port<Integer>:: The port to start the server on
+      # opts<Hash>:: The hash of options, defaults to the @opts 
+      #   instance variable.  
+      #
+      # @api private
       def self.start_at_port(port, opts = @opts)
         at_exit do
           Merb::Server.remove_pid(port)
         end
 
+        Merb::Worker.start
+
         # If Merb is daemonized, trap INT. If it's not daemonized,
         # we let the master process' ctrl-c control the cluster
         # of workers.
@@ -111,6 +174,7 @@ module Merb
         # In daemonized mode or not, support HUPing the process to
         # restart it.
         Merb.trap('HUP') do
+          Merb.exiting = true
           stop
           Merb.logger.warn! "Exiting port #{port} on #{Process.pid}\n"
           exit_process
@@ -118,6 +182,7 @@ module Merb
 
         # ABRTing the process will kill it, and it will not be respawned.
         Merb.trap('ABRT') do
+          Merb.exiting = true
           stopped = stop(128)
           Merb.logger.warn! "Exiting port #{port}\n" if stopped
           exit_process(128)
@@ -129,9 +194,9 @@ module Merb
         # Store the PID for this worker
         Merb::Server.store_pid(port)
 
-        Merb::Config[:log_delimiter] = "#{$0} ~ "
+        Merb::Config[:log_delimiter] = "#{process_title(:worker, port)} ~ "
 
-        Merb.logger = nil
+        Merb.reset_logger!
         Merb.logger.warn!("Starting #{self.name.split("::").last} at port #{port}")
 
         # If we can't connect to the port, keep trying until we can. Print
@@ -144,8 +209,8 @@ module Merb
             new_server(port)
           rescue Errno::EADDRINUSE
             unless printed_warning
-              Merb.logger.warn! "Couldn't bind to port #{port}."
-              Merb.logger.warn! "Waiting for it to become available"
+              Merb.logger.warn! "Port #{port} is in use, " \
+                "Waiting for it to become available."
               printed_warning = true
             end
 
@@ -163,11 +228,24 @@ module Merb
         start_server
       end
 
-      # This can be overridden in adapters, but shouldn't need to be.
+      # Exit the process with the specified status.  
+      #
+      # ==== Parameters
+      # status<Integer>:: The exit code of the process.
+      # 
+      # @api private
       def self.exit_process(status = 0)
         exit(status)
       end
 
+      # Set the process title.
+      #
+      # ==== Parameters
+      # whoami<Symbol>:: Either :spawner for the master process or :worker for any of the worker
+      #   processes. 
+      # port<Integer>:: The base port that the app is running on. 
+      #
+      # @api private
       def self.process_title(whoami, port)
         name = Merb::Config[:name]
         app  = "merb#{" : #{name}" if (name && name != "merb")}"
@@ -179,7 +257,7 @@ module Merb
           "socket#{'s' if max_port > 0 && whoami != :worker} #{numbers} "\
           "#{file ? file : "#{Merb.log_path}/#{name}.#{port}.sock"}"
         else
-          "port#{'s' if max_port > 0 && whoami != :worker}"
+          "port#{'s' if max_port > 0 && whoami != :worker} #{port}"
         end
         "#{app} : #{whoami} (#{listening_on})"
       end

data/lib/merb-core/rack/adapter/irb.rb

@@ -1,15 +1,60 @@
 module Merb
   module Rack
     class Console
-      # ==== Parameters
-      # name<~to_sym, Hash>:: The name of the route to generate.
-      # params<Hash>:: The params to use in the route generation.
+      # There are three possible ways to use this method.  First, if you have a named route, 
+      # you can specify the route as the first parameter as a symbol and any paramters in a 
+      # hash.  Second, you can generate the default route by just passing the params hash, 
+      # just passing the params hash.  Finally, you can use the anonymous parameters.  This 
+      # allows you to specify the parameters to a named route in the order they appear in the 
+      # router.  
+      #
+      # ==== Parameters(Named Route)
+      # name<Symbol>:: 
+      #   The name of the route. 
+      # args<Hash>:: 
+      #   Parameters for the route generation.
+      #
+      # ==== Parameters(Default Route)
+      # args<Hash>:: 
+      #   Parameters for the route generation.  This route will use the default route. 
+      #
+      # ==== Parameters(Anonymous Parameters)
+      # name<Symbol>::
+      #   The name of the route.  
+      # args<Array>:: 
+      #   An array of anonymous parameters to generate the route
+      #   with. These parameters are assigned to the route parameters
+      #   in the order that they are passed.
       #
       # ==== Returns
       # String:: The generated URL.
       #
-      # ==== Alternatives
-      # If name is a hash, it will be merged with params.
+      # ==== Examples
+      # Named Route
+      #
+      # Merb::Router.prepare do
+      #   match("/articles/:title").to(:controller => :articles, :action => :show).name("articles")
+      # end
+      #
+      # url(:articles, :title => "new_article")
+      #
+      # Default Route
+      #
+      # Merb::Router.prepare do
+      #   default_routes
+      # end
+      #
+      # url(:controller => "articles", :action => "new")
+      #
+      # Anonymous Paramters
+      #
+      # Merb::Router.prepare do
+      #   match("/articles/:year/:month/:title").to(:controller => :articles, :action => :show).name("articles")
+      # end
+      #
+      # url(:articles, 2008, 10, "test_article")
+      #
+      # @api public
       def url(name, *args)
         args << {}
         Merb::Router.url(name, *args)

data/lib/merb-core/rack/application.rb

@@ -2,24 +2,46 @@ module Merb
   module Rack
     class Application
       
+      # The main rack application call method.  This is the entry point from rack (and the webserver) 
+      # to your application.  
+      #
+      # ==== Parameters
+      # env<Hash>:: A rack request of parameters.  
+      #
+      # ==== Returns
+      # <Array>:: A rack response of [status<Integer>, headers<Hash>, body<String, Stream>]
+      #
+      # @api private
       def call(env) 
         begin
-          controller = ::Merb::Dispatcher.handle(Merb::Request.new(env))
+          rack_response = ::Merb::Dispatcher.handle(Merb::Request.new(env))
         rescue Object => e
-          return [500, {Merb::Const::CONTENT_TYPE => "text/html"}, e.message + "<br/>" + e.backtrace.join("<br/>")]
+          return [500, {Merb::Const::CONTENT_TYPE => Merb::Const::TEXT_SLASH_HTML}, e.message + Merb::Const::BREAK_TAG + e.backtrace.join(Merb::Const::BREAK_TAG)]
         end
-        Merb.logger.info "\n\n"
+        Merb.logger.info Merb::Const::DOUBLE_NEWLINE
         Merb.logger.flush
 
         # unless controller.headers[Merb::Const::DATE]
         #   require "time"
         #   controller.headers[Merb::Const::DATE] = Time.now.rfc2822.to_s
         # end
-        controller.rack_response
+        rack_response
       end
 
+      # Determines whether this request is a "deferred_action", usually a long request. 
+      # Rack uses this method to detemine whether to use an evented request or a deferred 
+      # request in evented rack handlers.  
+      #
+      # ==== Parameters
+      # env<Hash>:: The rack request
+      #
+      # ==== Returns
+      # Boolean::
+      #   True if the request should be deferred.  
+      #
+      # @api private
       def deferred?(env)
-        path = env[Merb::Const::PATH_INFO] ? env[Merb::Const::PATH_INFO].chomp('/') : ""
+        path = env[Merb::Const::PATH_INFO] ? env[Merb::Const::PATH_INFO].chomp(Merb::Const::SLASH) : Merb::Const::EMPTY_STRING
         if path =~ Merb.deferred_actions
           Merb.logger.info! "Deferring Request: #{path}"
           true

data/lib/merb-core/rack/handler/mongrel.rb

@@ -54,10 +54,10 @@ module Merb
         # response<HTTPResponse>:: The response object to write response to.
         def process(request, response)
           env = {}.replace(request.params)
-          env.delete "HTTP_CONTENT_TYPE"
-          env.delete "HTTP_CONTENT_LENGTH"
+          env.delete Merb::Const::HTTP_CONTENT_TYPE
+          env.delete Merb::Const::HTTP_CONTENT_LENGTH
   
-          env["SCRIPT_NAME"] = ""  if env["SCRIPT_NAME"] == "/"
+          env[Merb::Const::SCRIPT_NAME] = Merb::Const::EMPTY_STRING if env[Merb::Const::SCRIPT_NAME] == Merb::Const::SLASH
   
           env.update({"rack.version" => [0,1],
                        "rack.input" => request.body || StringIO.new(""),
@@ -69,8 +69,8 @@ module Merb
   
                        "rack.url_scheme" => "http"
                      })
-          env["QUERY_STRING"] ||= ""
-          env.delete "PATH_INFO"  if env["PATH_INFO"] == ""
+          env[Merb::Const::QUERY_STRING] ||= ""
+          env.delete Merb::Const::PATH_INFO  if env[Merb::Const::PATH_INFO] == Merb::Const::EMPTY_STRING
   
           status, headers, body = @app.call(env)
   
@@ -93,4 +93,4 @@ module Merb
       end
     end
   end
-end
+end