Permalink
Browse files

update manual for 0.9 release

  • Loading branch information...
1 parent 4035b18 commit 0a6c366d327e0b5230c0bc1cb0a6a6377dcea50d @rtomayko committed Feb 24, 2011
Showing with 236 additions and 27 deletions.
  1. +79 −9 index.html
  2. +82 −10 shotgun.1
  3. +75 −8 shotgun.1.ronn
View
@@ -2,7 +2,7 @@
<html>
<head>
<meta http-equiv='content-type' value='text/html;charset=utf8'>
- <meta name='generator' value='Ronn/v0.6.42 (http://github.com/rtomayko/ronn/tree/0.6.6-36-gb67d494)'>
+ <meta name='generator' value='Ronn/v0.7.3 (http://github.com/rtomayko/ronn/tree/0.7.3)'>
<title>shotgun(1) - reloading rack development server</title>
<style type='text/css' media='all'>
/* style: man */
@@ -63,6 +63,7 @@
<a href="#SYNOPSIS">SYNOPSIS</a>
<a href="#DESCRIPTION">DESCRIPTION</a>
<a href="#OPTIONS">OPTIONS</a>
+ <a href="#PRELOADING">PRELOADING</a>
<a href="#INSTALLING">INSTALLING</a>
<a href="#CONTRIBUTING">CONTRIBUTING</a>
<a href="#VERSION-HISTORY">VERSION HISTORY</a>
@@ -129,14 +130,17 @@ <h2 id="OPTIONS">OPTIONS</h2>
<p>Ruby environment related options:</p>
<dl>
-<dt><code>-e</code>, <code>--eval</code> <var>command</var></dt><dd><p>Evaluate arbitrary <var>command</var> within the Ruby interpreter. <var>command</var> is
-evaluated as program arguments are parsed. Multiple <code>-e</code> arguments are
-allowed.</p></dd>
+<dt><code>-r</code>, <code>--require</code> <var>library</var></dt><dd><p>Require <var>library</var> before loading the application and starting the server.
+This can be used to load a portion of the application code in the master
+process so it doesn't need to be loaded in the child. See <a href="#PRELOADING" title="PRELOADING" data-bare-link="true">PRELOADING</a>][]
+for more information on this approach.</p></dd>
+<dt><code>-e</code>, <code>--eval</code> <var>command</var></dt><dd><p>Evaluate arbitrary <var>command</var> within the shotgun master Ruby interpreter.
+<var>command</var> is evaluated as program arguments are parsed. Multiple <code>-e</code>
+arguments are allowed.</p></dd>
<dt><code>-d</code>, <code>--debug</code></dt><dd><p>Turns on debug mode. <code>$DEBUG</code> will be set <code>true</code>.</p></dd>
<dt><code>-w</code>, <code>--warn</code></dt><dd><p>Enable verbose mode without printing version message at the beginning. It
sets the <code>$VERBOSE</code> variable to true.</p></dd>
<dt><code>-I</code>, <code>--include</code> <var>path</var></dt><dd><p>Add <var>path</var> to the Ruby load path (<code>$LOAD_PATH</code>). May be used more than once.</p></dd>
-<dt><code>-r</code>, <code>--require</code> <var>library</var></dt><dd><p>Require <var>library</var> before loading the application and starting the server.</p></dd>
</dl>
@@ -148,6 +152,51 @@ <h2 id="OPTIONS">OPTIONS</h2>
</dl>
+<h2 id="PRELOADING">PRELOADING</h2>
+
+<p>It's possible to load support libraries and portions of the application in the
+shotgun master process to reduce the amount of work that needs to be done for
+each request in worker processes. There's two ways of accomplishing this: either
+by specifying one or more <code>--require</code> (<code>-r</code>) arguments or through the use of a
+<code>shotgun.rb</code> file.</p>
+
+<p>During start up, shotgun looks for a <code>shotgun.rb</code> or <code>config/shotgun.rb</code> file.
+If either file is found, it's loaded into the shotgun master process. Code at
+the top-level of the <code>shotgun.rb</code> is run once on startup, so just require
+whatever you want to preload. It's also possible to register callbacks to run
+before each request in either the master or child worker process:</p>
+
+<dl>
+<dt><code>after_fork {</code> <var>stuff</var> <code>}</code></dt><dd><p>Run <var>stuff</var> in the shotgun child worker process immediately after forking.
+Any files or socket connections opened in the master process should be
+closed / re-established by an <code>after_fork</code> block.</p></dd>
+<dt><code>before_fork {</code> <var>stuff</var> <code>}</code></dt><dd><p>Run <var>stuff</var> in the shotgun master process on each request before forking
+the child worker process. This is typically less useful than <code>after_fork</code>,
+but provided for completeness.</p></dd>
+</dl>
+
+
+<p>Example <code>config/shotgun.rb</code> file from the main github.com rails project:</p>
+
+<pre><code># make sure the load path includes RAILS_ROOT
+ENV['RAILS_ROOT'] ||= File.expand_path('../..', __FILE__)
+$:.unshift ENV['RAILS_ROOT']
+
+# bring in the base rails environment and some libraries
+require 'config/environment'
+require 'google-charts'
+require 'aws-s3'
+
+# disable Rails's built in class reloading
+Rails.configuration.cache_classes = true
+
+# reset database and redis connections in workers
+after_fork do
+ ActiveRecord::Base.establish_connection
+ CHIMNEY.client = $redis
+end
+</code></pre>
+
<h2 id="INSTALLING">INSTALLING</h2>
<p>Shotgun is distributed as a gem package at rubygems.org:</p>
@@ -166,10 +215,31 @@ <h2 id="CONTRIBUTING">CONTRIBUTING</h2>
<h2 id="VERSION-HISTORY">VERSION HISTORY</h2>
-<h3 id="Version-0-7-unreleased-">Version 0.7 (unreleased)</h3>
+<h3 id="Version-0-9-2011-February-24-">Version 0.9 (2011 February 24)</h3>
+
+<ul>
+<li><p><a href="http://github.com/rtomayko/shotgun/compare/0.8...0.9" data-bare-link="true">http://github.com/rtomayko/shotgun/compare/0.8...0.9</a></p></li>
+<li><p>Various Ruby 1.9.2 fixes.</p></li>
+<li><p>Handle application class names consisting of multiple words.</p></li>
+</ul>
+
+
+<h3 id="Version-0-8-2010-June-24-">Version 0.8 (2010 June 24)</h3>
+
+<ul>
+<li><p><a href="http://github.com/rtomayko/shotgun/compare/0.7...0.8" data-bare-link="true">http://github.com/rtomayko/shotgun/compare/0.7...0.8</a></p></li>
+<li><p>Preloading support. The <code>shotgun.rb</code> or <code>config/shotgun.rb</code> file is
+loaded at startup and may require libraries and register callbacks
+for fork events. See the section on <a href="#PRELOADING" title="PRELOADING" data-bare-link="true">PRELOADING</a>.</p></li>
+<li><p>Fix starting with the Thin handler (<code>shotgun -s thin</code>)</p></li>
+<li><p>Actually include the <a href="shotgun.1.html" class="man-ref">shotgun<span class="s">(1)</span></a> roff manual.</p></li>
+</ul>
+
+
+<h3 id="Version-0-7-2010-June-22-">Version 0.7 (2010 June 22)</h3>
<ul>
-<li><p><a href="http://github.com/rtomayko/shotgun/compare/0.6...master" data-bare-link="true">http://github.com/rtomayko/shotgun/compare/0.6...master</a></p></li>
+<li><p><a href="http://github.com/rtomayko/shotgun/compare/0.6...0.7" data-bare-link="true">http://github.com/rtomayko/shotgun/compare/0.6...0.7</a></p></li>
<li><p>Static files now served from the shotgun master process, making
shotgun tolerable for apps with many/unbundled static assets.</p></li>
<li><p>Added <code>--public</code> (<code>-P</code>) for specifying a non-standard root / public
@@ -200,8 +270,8 @@ <h2 id="SEE-ALSO">SEE ALSO</h2>
<ol class='man-decor man-foot man foot'>
- <li class='tl'>Shotgun 0.7</li>
- <li class='tc'>June 2010</li>
+ <li class='tl'>Shotgun 0.9</li>
+ <li class='tc'>February 2011</li>
<li class='tr'>shotgun(1)</li>
</ol>
View
@@ -1,7 +1,7 @@
-.\" generated with Ronn/v0.6.42
-.\" http://github.com/rtomayko/ronn/tree/0.6.6-36-gb67d494
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
-.TH "SHOTGUN" "1" "June 2010" "Shotgun 0.7" ""
+.TH "SHOTGUN" "1" "February 2011" "Shotgun 0.9" ""
.
.SH "NAME"
\fBshotgun\fR \- reloading rack development server
@@ -49,8 +49,12 @@ Open browser at http://\fIhost\fR:\fIport\fR/ immediately after the server is st
Ruby environment related options:
.
.TP
+\fB\-r\fR, \fB\-\-require\fR \fIlibrary\fR
+Require \fIlibrary\fR before loading the application and starting the server\. This can be used to load a portion of the application code in the master process so it doesn\'t need to be loaded in the child\. See \fIPRELOADING\fR][] for more information on this approach\.
+.
+.TP
\fB\-e\fR, \fB\-\-eval\fR \fIcommand\fR
-Evaluate arbitrary \fIcommand\fR within the Ruby interpreter\. \fIcommand\fR is evaluated as program arguments are parsed\. Multiple \fB\-e\fR arguments are allowed\.
+Evaluate arbitrary \fIcommand\fR within the shotgun master Ruby interpreter\. \fIcommand\fR is evaluated as program arguments are parsed\. Multiple \fB\-e\fR arguments are allowed\.
.
.TP
\fB\-d\fR, \fB\-\-debug\fR
@@ -64,10 +68,6 @@ Enable verbose mode without printing version message at the beginning\. It sets
\fB\-I\fR, \fB\-\-include\fR \fIpath\fR
Add \fIpath\fR to the Ruby load path (\fB$LOAD_PATH\fR)\. May be used more than once\.
.
-.TP
-\fB\-r\fR, \fB\-\-require\fR \fIlibrary\fR
-Require \fIlibrary\fR before loading the application and starting the server\.
-.
.P
Miscellaneous:
.
@@ -79,6 +79,49 @@ Show usage message and exit\.
\fB\-\-version\fR
Show the Rack version and exit\.
.
+.SH "PRELOADING"
+It\'s possible to load support libraries and portions of the application in the shotgun master process to reduce the amount of work that needs to be done for each request in worker processes\. There\'s two ways of accomplishing this: either by specifying one or more \fB\-\-require\fR (\fB\-r\fR) arguments or through the use of a \fBshotgun\.rb\fR file\.
+.
+.P
+During start up, shotgun looks for a \fBshotgun\.rb\fR or \fBconfig/shotgun\.rb\fR file\. If either file is found, it\'s loaded into the shotgun master process\. Code at the top\-level of the \fBshotgun\.rb\fR is run once on startup, so just require whatever you want to preload\. It\'s also possible to register callbacks to run before each request in either the master or child worker process:
+.
+.TP
+\fBafter_fork {\fR \fIstuff\fR \fB}\fR
+Run \fIstuff\fR in the shotgun child worker process immediately after forking\. Any files or socket connections opened in the master process should be closed / re\-established by an \fBafter_fork\fR block\.
+.
+.TP
+\fBbefore_fork {\fR \fIstuff\fR \fB}\fR
+Run \fIstuff\fR in the shotgun master process on each request before forking the child worker process\. This is typically less useful than \fBafter_fork\fR, but provided for completeness\.
+.
+.P
+Example \fBconfig/shotgun\.rb\fR file from the main github\.com rails project:
+.
+.IP "" 4
+.
+.nf
+
+# make sure the load path includes RAILS_ROOT
+ENV[\'RAILS_ROOT\'] ||= File\.expand_path(\'\.\./\.\.\', __FILE__)
+$:\.unshift ENV[\'RAILS_ROOT\']
+
+# bring in the base rails environment and some libraries
+require \'config/environment\'
+require \'google\-charts\'
+require \'aws\-s3\'
+
+# disable Rails\'s built in class reloading
+Rails\.configuration\.cache_classes = true
+
+# reset database and redis connections in workers
+after_fork do
+ ActiveRecord::Base\.establish_connection
+ CHIMNEY\.client = $redis
+end
+.
+.fi
+.
+.IP "" 0
+.
.SH "INSTALLING"
Shotgun is distributed as a gem package at rubygems\.org:
.
@@ -102,10 +145,39 @@ Fork and report issues at github\.com:
.
.SH "VERSION HISTORY"
.
-.SS "Version 0\.7 (unreleased)"
+.SS "Version 0\.9 (2011 February 24)"
+.
+.IP "\(bu" 4
+\fIhttp://github\.com/rtomayko/shotgun/compare/0\.8\.\.\.0\.9\fR
+.
+.IP "\(bu" 4
+Various Ruby 1\.9\.2 fixes\.
+.
+.IP "\(bu" 4
+Handle application class names consisting of multiple words\.
+.
+.IP "" 0
+.
+.SS "Version 0\.8 (2010 June 24)"
+.
+.IP "\(bu" 4
+\fIhttp://github\.com/rtomayko/shotgun/compare/0\.7\.\.\.0\.8\fR
+.
+.IP "\(bu" 4
+Preloading support\. The \fBshotgun\.rb\fR or \fBconfig/shotgun\.rb\fR file is loaded at startup and may require libraries and register callbacks for fork events\. See the section on \fIPRELOADING\fR\.
+.
+.IP "\(bu" 4
+Fix starting with the Thin handler (\fBshotgun \-s thin\fR)
+.
+.IP "\(bu" 4
+Actually include the shotgun(1) roff manual\.
+.
+.IP "" 0
+.
+.SS "Version 0\.7 (2010 June 22)"
.
.IP "\(bu" 4
-\fIhttp://github\.com/rtomayko/shotgun/compare/0\.6\.\.\.master\fR
+\fIhttp://github\.com/rtomayko/shotgun/compare/0\.6\.\.\.0\.7\fR
.
.IP "\(bu" 4
Static files now served from the shotgun master process, making shotgun tolerable for apps with many/unbundled static assets\.
View
@@ -57,10 +57,16 @@ control server behavior:
Ruby environment related options:
+ * `-r`, `--require` <library>:
+ Require <library> before loading the application and starting the server.
+ This can be used to load a portion of the application code in the master
+ process so it doesn't need to be loaded in the child. See [PRELOADING]][]
+ for more information on this approach.
+
* `-e`, `--eval` <command>:
- Evaluate arbitrary <command> within the Ruby interpreter. <command> is
- evaluated as program arguments are parsed. Multiple `-e` arguments are
- allowed.
+ Evaluate arbitrary <command> within the shotgun master Ruby interpreter.
+ <command> is evaluated as program arguments are parsed. Multiple `-e`
+ arguments are allowed.
* `-d`, `--debug`:
Turns on debug mode. `$DEBUG` will be set `true`.
@@ -72,9 +78,6 @@ Ruby environment related options:
* `-I`, `--include` <path>:
Add <path> to the Ruby load path (`$LOAD_PATH`). May be used more than once.
- * `-r`, `--require` <library>:
- Require <library> before loading the application and starting the server.
-
Miscellaneous:
* `-h`, `--help`:
@@ -83,6 +86,50 @@ Miscellaneous:
* `--version`:
Show the Rack version and exit.
+## PRELOADING
+
+It's possible to load support libraries and portions of the application in the
+shotgun master process to reduce the amount of work that needs to be done for
+each request in worker processes. There's two ways of accomplishing this: either
+by specifying one or more `--require` (`-r`) arguments or through the use of a
+`shotgun.rb` file.
+
+During start up, shotgun looks for a `shotgun.rb` or `config/shotgun.rb` file.
+If either file is found, it's loaded into the shotgun master process. Code at
+the top-level of the `shotgun.rb` is run once on startup, so just require
+whatever you want to preload. It's also possible to register callbacks to run
+before each request in either the master or child worker process:
+
+ * `after_fork {` <stuff> `}`:
+ Run <stuff> in the shotgun child worker process immediately after forking.
+ Any files or socket connections opened in the master process should be
+ closed / re-established by an `after_fork` block.
+
+ * `before_fork {` <stuff> `}`:
+ Run <stuff> in the shotgun master process on each request before forking
+ the child worker process. This is typically less useful than `after_fork`,
+ but provided for completeness.
+
+Example `config/shotgun.rb` file from the main github.com rails project:
+
+ # make sure the load path includes RAILS_ROOT
+ ENV['RAILS_ROOT'] ||= File.expand_path('../..', __FILE__)
+ $:.unshift ENV['RAILS_ROOT']
+
+ # bring in the base rails environment and some libraries
+ require 'config/environment'
+ require 'google-charts'
+ require 'aws-s3'
+
+ # disable Rails's built in class reloading
+ Rails.configuration.cache_classes = true
+
+ # reset database and redis connections in workers
+ after_fork do
+ ActiveRecord::Base.establish_connection
+ CHIMNEY.client = $redis
+ end
+
## INSTALLING
Shotgun is distributed as a gem package at rubygems.org:
@@ -101,9 +148,29 @@ Fork and report issues at github.com:
## VERSION HISTORY
-### Version 0.7 (unreleased)
+### Version 0.9 (2011 February 24)
+
+ * <http://github.com/rtomayko/shotgun/compare/0.8...0.9>
+
+ * Various Ruby 1.9.2 fixes.
+
+ * Handle application class names consisting of multiple words.
+
+### Version 0.8 (2010 June 24)
+
+ * <http://github.com/rtomayko/shotgun/compare/0.7...0.8>
+
+ * Preloading support. The `shotgun.rb` or `config/shotgun.rb` file is
+ loaded at startup and may require libraries and register callbacks
+ for fork events. See the section on [PRELOADING][].
+
+ * Fix starting with the Thin handler (`shotgun -s thin`)
+
+ * Actually include the shotgun(1) roff manual.
+
+### Version 0.7 (2010 June 22)
- * <http://github.com/rtomayko/shotgun/compare/0.6...master>
+ * <http://github.com/rtomayko/shotgun/compare/0.6...0.7>
* Static files now served from the shotgun master process, making
shotgun tolerable for apps with many/unbundled static assets.

0 comments on commit 0a6c366

Please sign in to comment.