From 6411add3f1a5aae5f2e0dcd73cd842500d21e9fd Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Mon, 18 Apr 2011 15:53:08 -0700 Subject: documentation cleanup/reduction Don't clutter up our RDoc/website with things that users of Unicorn don't need to see. This should make user-relevant documentation easier to find, especially since Unicorn is NOT intended to be an API. --- lib/unicorn.rb | 26 +++++++++++++++++++------- lib/unicorn/app/exec_cgi.rb | 2 +- lib/unicorn/app/inetd.rb | 3 +-- lib/unicorn/app/old_rails.rb | 1 + lib/unicorn/app/old_rails/static.rb | 2 +- lib/unicorn/cgi_wrapper.rb | 1 + lib/unicorn/configurator.rb | 21 ++++++++++++++------- lib/unicorn/const.rb | 1 + lib/unicorn/http_response.rb | 1 + lib/unicorn/http_server.rb | 9 +++++++-- lib/unicorn/launcher.rb | 1 + lib/unicorn/preread_input.rb | 3 +++ lib/unicorn/socket_helper.rb | 2 +- lib/unicorn/stream_input.rb | 2 +- 14 files changed, 53 insertions(+), 22 deletions(-) diff --git a/lib/unicorn.rb b/lib/unicorn.rb index 7891d67..8a5fdcc 100644 --- a/lib/unicorn.rb +++ b/lib/unicorn.rb @@ -5,10 +5,27 @@ require 'stringio' require 'rack' require 'kgio' +# :stopdoc: # Unicorn module containing all of the classes (include C extensions) for # running a Unicorn web server. It contains a minimalist HTTP server with just # enough functionality to service web application requests fast as possible. +# :startdoc: + +# \Unicorn exposes very little of an user-visible API and most of its +# internals are subject to change. \Unicorn is designed to host Rack +# applications, so applications should be written against the Rack SPEC +# and not \Unicorn internals. module Unicorn + + # Raised inside TeeInput when a client closes the socket inside the + # application dispatch. This is always raised with an empty backtrace + # since there is nothing in the application stack that is responsible + # for client shutdowns/disconnects. This exception is visible to Rack + # applications unless PrereadInput middleware is loaded. + class ClientShutdown < EOFError + end + + # :stopdoc: def self.run(app, options = {}) Unicorn::HttpServer.new(app, options).start.join end @@ -63,14 +80,9 @@ module Unicorn Unicorn::SocketHelper.sock_name(io) end end + # :startdoc: end - -# raised inside TeeInput when a client closes the socket inside the -# application dispatch. This is always raised with an empty backtrace -# since there is nothing in the application stack that is responsible -# for client shutdowns/disconnects. -class Unicorn::ClientShutdown < EOFError; end - +# :enddoc: require 'unicorn/const' require 'unicorn/socket_helper' require 'unicorn/stream_input' diff --git a/lib/unicorn/app/exec_cgi.rb b/lib/unicorn/app/exec_cgi.rb index ac16755..232b681 100644 --- a/lib/unicorn/app/exec_cgi.rb +++ b/lib/unicorn/app/exec_cgi.rb @@ -1,5 +1,5 @@ # -*- encoding: binary -*- - +# :enddoc: require 'unicorn' module Unicorn::App diff --git a/lib/unicorn/app/inetd.rb b/lib/unicorn/app/inetd.rb index 2cc280c..2a212a2 100644 --- a/lib/unicorn/app/inetd.rb +++ b/lib/unicorn/app/inetd.rb @@ -1,10 +1,9 @@ # -*- encoding: binary -*- - +# :enddoc: # Copyright (c) 2009 Eric Wong # You can redistribute it and/or modify it under the same terms as Ruby. # this class *must* be used with Rack::Chunked - module Unicorn::App class Inetd < Struct.new(:cmd) diff --git a/lib/unicorn/app/old_rails.rb b/lib/unicorn/app/old_rails.rb index e674d78..5f04ce7 100644 --- a/lib/unicorn/app/old_rails.rb +++ b/lib/unicorn/app/old_rails.rb @@ -1,5 +1,6 @@ # -*- encoding: binary -*- +# :enddoc: # This code is based on the original Rails handler in Mongrel # Copyright (c) 2005 Zed A. Shaw # Copyright (c) 2009 Eric Wong diff --git a/lib/unicorn/app/old_rails/static.rb b/lib/unicorn/app/old_rails/static.rb index 13a435e..1d53717 100644 --- a/lib/unicorn/app/old_rails/static.rb +++ b/lib/unicorn/app/old_rails/static.rb @@ -1,5 +1,5 @@ # -*- encoding: binary -*- - +# :enddoc: # This code is based on the original Rails handler in Mongrel # Copyright (c) 2005 Zed A. Shaw # Copyright (c) 2009 Eric Wong diff --git a/lib/unicorn/cgi_wrapper.rb b/lib/unicorn/cgi_wrapper.rb index b6eeb33..0dc3f33 100644 --- a/lib/unicorn/cgi_wrapper.rb +++ b/lib/unicorn/cgi_wrapper.rb @@ -1,5 +1,6 @@ # -*- encoding: binary -*- +# :enddoc: # This code is based on the original CGIWrapper from Mongrel # Copyright (c) 2005 Zed A. Shaw # Copyright (c) 2009 Eric Wong diff --git a/lib/unicorn/configurator.rb b/lib/unicorn/configurator.rb index 595d105..73869de 100644 --- a/lib/unicorn/configurator.rb +++ b/lib/unicorn/configurator.rb @@ -207,7 +207,14 @@ class Unicorn::Configurator set[:listeners] = addresses end - # adds an +address+ to the existing listener set. + # Adds an +address+ to the existing listener set. May be specified more + # than once. +address+ may be an Integer port number for a TCP port, an + # "IP_ADDRESS:PORT" for TCP listeners or a pathname for UNIX domain sockets. + # + # listen 3000 # listen to port 3000 on all TCP interfaces + # listen "127.0.0.1:3000" # listen to port 3000 on the loopback interface + # listen "/tmp/.unicorn.sock" # listen on the given Unix domain socket + # listen "[::1]:3000" # listen to port 3000 on the IPv6 loopback interface # # The following options may be specified (but are generally not needed): # @@ -333,24 +340,24 @@ class Unicorn::Configurator # There is no good reason to change from the default. # # Default: "httpready" - def listen(address, opt = {}) + def listen(address, options = {}) address = expand_addr(address) if String === address [ :umask, :backlog, :sndbuf, :rcvbuf, :tries ].each do |key| - value = opt[key] or next + value = options[key] or next Integer === value or raise ArgumentError, "not an integer: #{key}=#{value.inspect}" end [ :tcp_nodelay, :tcp_nopush ].each do |key| - (value = opt[key]).nil? and next + (value = options[key]).nil? and next TrueClass === value || FalseClass === value or raise ArgumentError, "not boolean: #{key}=#{value.inspect}" end - unless (value = opt[:delay]).nil? + unless (value = options[:delay]).nil? Numeric === value or raise ArgumentError, "not numeric: delay=#{value.inspect}" end - set[:listener_opts][address].merge!(opt) + set[:listener_opts][address].merge!(options) end set[:listeners] << address @@ -484,7 +491,7 @@ class Unicorn::Configurator # expands "unix:path/to/foo" to a socket relative to the current path # expands pathnames of sockets if relative to "~" or "~username" # expands "*:port and ":port" to "0.0.0.0:port" - def expand_addr(address) #:nodoc + def expand_addr(address) #:nodoc: return "0.0.0.0:#{address}" if Integer === address return address unless String === address diff --git a/lib/unicorn/const.rb b/lib/unicorn/const.rb index 8a65a54..c65c242 100644 --- a/lib/unicorn/const.rb +++ b/lib/unicorn/const.rb @@ -1,5 +1,6 @@ # -*- encoding: binary -*- +# :enddoc: # Frequently used constants when constructing requests or responses. # Many times the constant just refers to a string with the same # contents. Using these constants gave about a 3% to 10% performance diff --git a/lib/unicorn/http_response.rb b/lib/unicorn/http_response.rb index 03d3179..b781e20 100644 --- a/lib/unicorn/http_response.rb +++ b/lib/unicorn/http_response.rb @@ -1,4 +1,5 @@ # -*- encoding: binary -*- +# :enddoc: # Writes a Rack response to your client using the HTTP/1.1 specification. # You use it by simply doing: # diff --git a/lib/unicorn/http_server.rb b/lib/unicorn/http_server.rb index 69feb2f..7ed26ca 100644 --- a/lib/unicorn/http_server.rb +++ b/lib/unicorn/http_server.rb @@ -4,15 +4,19 @@ # processes which in turn handle the I/O and application process. # Listener sockets are started in the master process and shared with # forked worker children. +# +# Users do not need to know the internals of this class, but reading the +# {source}[http://bogomips.org/unicorn.git/tree/lib/unicorn/http_server.rb] +# is education for programmers wishing to learn how \Unicorn works. +# See Unicorn::Configurator for information on how to configure \Unicorn. class Unicorn::HttpServer + # :stopdoc: attr_accessor :app, :request, :timeout, :worker_processes, :before_fork, :after_fork, :before_exec, :listener_opts, :preload_app, :reexec_pid, :orig_app, :init_listeners, :master_pid, :config, :ready_pipe, :user attr_reader :pid, :logger - - # :stopdoc: include Unicorn::SocketHelper include Unicorn::HttpResponse @@ -84,6 +88,7 @@ class Unicorn::HttpServer rescue Dir.pwd end + # :stopdoc: # Creates a working server on host:port (strange things happen if # port isn't a Number). Use HttpServer::run to start the server and diff --git a/lib/unicorn/launcher.rb b/lib/unicorn/launcher.rb index 662b603..5eafe5b 100644 --- a/lib/unicorn/launcher.rb +++ b/lib/unicorn/launcher.rb @@ -1,5 +1,6 @@ # -*- encoding: binary -*- +# :enddoc: $stdout.sync = $stderr.sync = true $stdin.binmode $stdout.binmode diff --git a/lib/unicorn/preread_input.rb b/lib/unicorn/preread_input.rb index 7a315b7..12eb3e8 100644 --- a/lib/unicorn/preread_input.rb +++ b/lib/unicorn/preread_input.rb @@ -13,6 +13,8 @@ module Unicorn # end # run YourApp.new class PrereadInput + + # :stopdoc: def initialize(app) @app = app end @@ -26,5 +28,6 @@ class PrereadInput end @app.call(env) end + # :startdoc: end end diff --git a/lib/unicorn/socket_helper.rb b/lib/unicorn/socket_helper.rb index b0fd3ce..9f2d55c 100644 --- a/lib/unicorn/socket_helper.rb +++ b/lib/unicorn/socket_helper.rb @@ -17,7 +17,7 @@ module Unicorn # denial-of-service attacks :tcp_defer_accept => 1, - # FreeBSD, we need to override this to 'dataready' when we + # FreeBSD, we need to override this to 'dataready' if we # eventually get HTTPS support :accept_filter => 'httpready', diff --git a/lib/unicorn/stream_input.rb b/lib/unicorn/stream_input.rb index 90e1d6e..4ca5a04 100644 --- a/lib/unicorn/stream_input.rb +++ b/lib/unicorn/stream_input.rb @@ -1,7 +1,7 @@ # -*- encoding: binary -*- # When processing uploads, Unicorn may expose a StreamInput object under -# "rack.input" of the Rack (2.x) environment. +# "rack.input" of the (future) Rack (2.x) environment. class Unicorn::StreamInput # The I/O chunk size (in +bytes+) for I/O operations where # the size cannot be user-specified when a method is called. -- cgit v1.2.3-24-ge0c7