* [PATCH 1/2] doc: trim down documentation slightly
2016-02-14 11:28 [PUSHED] doc: switch to perlpod (from pandoc-flavored Markdown) Eric Wong
@ 2016-02-14 11:29 ` Eric Wong
2016-02-14 11:33 ` [PATCH 2/2] doc: document ssl_ctx for "listen" directive Eric Wong
2016-02-14 21:33 ` [PATCH 3/2] doc: various doc and linkification improvements Eric Wong
2 siblings, 0 replies; 4+ messages in thread
From: Eric Wong @ 2016-02-14 11:29 UTC (permalink / raw)
To: yahns-public
The "threads:" option for the "listen" directive is worthless.
Having a dedicated thread per-process is already more than enough
(and ideal) for a multi-process setup. Multiple acceptor threads
is still wrong for a single-process setup (even if we did not
have a GVL) as it still incurs contention with the worker
pool within the kernel.
So remove the documentation regarding "listen ... threads: ",
for now; at least until somebody can prove it's useful and not
taking up space.
Additionally, "atfork_parent" may be useful for restarting
background threads/connections if somebody wants to run
background jobs in the master process, so stop saying
it's completely useless.
---
Documentation/yahns_config.pod | 17 -----------------
examples/yahns_rack_basic.conf.rb | 2 +-
test/test_server.rb | 8 ++++----
3 files changed, 5 insertions(+), 22 deletions(-)
diff --git a/Documentation/yahns_config.pod b/Documentation/yahns_config.pod
index ff04cb3..12ec75e 100644
--- a/Documentation/yahns_config.pod
+++ b/Documentation/yahns_config.pod
@@ -422,22 +422,6 @@ ref: https://lwn.net/Articles/542629/
Default: false (unset)
-=item threads: INTEGER
-
-Used to control the number of threads blocking on the L<accept(2)>
-or L<accept4(2)> system call (per listen socket).
-
-Usually, only one thread here is necessary, especially when
-multiple worker_processes are configured (as there'll be one
-thread per-process). Having extra threads may increase
-contention with epoll and FD allocation within one process.
-
-Note: do not confuse this option with worker_threads for queues,
-each queue has their own thread pool and it makes sense to
-have multiple threads there.
-
-Default: 1
-
=item umask: MODE
Sets the file mode creation mask for UNIX sockets. If specified,
@@ -584,7 +568,6 @@ Default: none
=item atfork_parent &BLOCK
This &BLOCK is executed in the parent after the L<fork(2)> operation.
-This may not be useful, but exists in case somebody finds a use for it.
Default: none
diff --git a/examples/yahns_rack_basic.conf.rb b/examples/yahns_rack_basic.conf.rb
index 12bbc99..33ba619 100644
--- a/examples/yahns_rack_basic.conf.rb
+++ b/examples/yahns_rack_basic.conf.rb
@@ -16,7 +16,7 @@
puts "#$$ yahns parent about to spawn"
end
atfork_parent do
- puts "#$$ this is probably not useful"
+ puts "#$$ yahns parent done spawning"
end
end
diff --git a/test/test_server.rb b/test/test_server.rb
index 65a6ea1..87193e3 100644
--- a/test/test_server.rb
+++ b/test/test_server.rb
@@ -428,7 +428,7 @@ def test_mp_hooks
worker_processes(1) do
atfork_child { puts "af #$$ worker is running" }
atfork_prepare { puts "af #$$ parent about to spawn" }
- atfork_parent { puts "af #$$ this is probably not useful" }
+ atfork_parent { puts "af #$$ parent done spawning" }
end
}
stderr_path err.path
@@ -457,7 +457,7 @@ def test_mp_hooks
assert_equal("af #{pid} parent about to spawn", lines.shift)
# child/parent ordering is not guaranteed
- assert_equal 1, lines.grep(/\Aaf #{pid} this is probably not useful\z/).size
+ assert_equal 1, lines.grep(/\Aaf #{pid} parent done spawning\z/).size
assert_equal 1, lines.grep(/\Aaf #{worker_pid} worker is running\z/).size
ensure
quit_wait(master_pid)
@@ -479,7 +479,7 @@ def test_mp_hooks_worker_nr
worker_processes(1) do
atfork_child { |nr| puts "af.#{nr} #$$ worker is running" }
atfork_prepare { |nr| puts "af.#{nr} #$$ parent about to spawn" }
- atfork_parent { |nr| puts "af.#{nr} #$$ this is probably not useful" }
+ atfork_parent { |nr| puts "af.#{nr} #$$ parent done spawning" }
end
}
stderr_path err.path
@@ -503,7 +503,7 @@ def test_mp_hooks_worker_nr
# child/parent ordering is not guaranteed
assert_equal 1,
- lines.grep(/\Aaf\.0 #{pid} this is probably not useful\z/).size
+ lines.grep(/\Aaf\.0 #{pid} parent done spawning\z/).size
assert_equal 1,
lines.grep(/\Aaf\.0 #{worker_pid} worker is running\z/).size
ensure
--
EW
^ permalink raw reply related [flat|nested] 4+ messages in thread* [PATCH 3/2] doc: various doc and linkification improvements
2016-02-14 11:28 [PUSHED] doc: switch to perlpod (from pandoc-flavored Markdown) Eric Wong
2016-02-14 11:29 ` [PATCH 1/2] doc: trim down documentation slightly Eric Wong
2016-02-14 11:33 ` [PATCH 2/2] doc: document ssl_ctx for "listen" directive Eric Wong
@ 2016-02-14 21:33 ` Eric Wong
2 siblings, 0 replies; 4+ messages in thread
From: Eric Wong @ 2016-02-14 21:33 UTC (permalink / raw)
To: yahns-public
Correctly link to subsections within the same page, and include
a link to mailing list archives.
Also, use "ssl_ctx" consistently as a local variable as
we internally use "ctx" for other purposes.
---
Documentation/yahns-rackup.pod | 18 ++++++++++--------
Documentation/yahns.pod | 3 +--
Documentation/yahns_config.pod | 31 +++++++++++++++++--------------
examples/yahns_rack_basic.conf.rb | 7 ++++++-
4 files changed, 34 insertions(+), 25 deletions(-)
diff --git a/Documentation/yahns-rackup.pod b/Documentation/yahns-rackup.pod
index fc724e6..efdfb6d 100644
--- a/Documentation/yahns-rackup.pod
+++ b/Documentation/yahns-rackup.pod
@@ -1,5 +1,3 @@
-% yahns-rackup(1) yahns user manual
-
=head1 NAME
yahns-rackup - a rackup-like command to launch yahns
@@ -17,7 +15,9 @@ It is expected to start in your application root (APP_ROOT).
This defaults to "config.ru" in APP_ROOT. It should be the same
file used by L<rackup(1)> and other Rack launchers, it uses the
-*Rack::Builder* DSL.
+*Rack::Builder* DSL documented at:
+
+L<http://www.rubydoc.info/github/rack/rack/Rack/Builder>
=head1 YAHNS OPTIONS
@@ -90,7 +90,7 @@ also be redirected to "/dev/null".
=item -E, --env RACK_ENV
-Run under the given RACK_ENV. See the RACK ENVIRONMENT section
+Run under the given RACK_ENV. See the L</RACK ENVIRONMENT> section
for more details.
=item -o, --host HOST
@@ -107,7 +107,7 @@ use of "-l"/"--listen" switch is recommended instead.
Listen on the specified TCP PORT, default is 9292.
If specified multiple times on the command-line, only the last-specified
value takes effect.
-This option only exists for compatibility with the Lrackup(1)> command,
+This option only exists for compatibility with the L<rackup(1)> command,
use of "-l"/"--listen" switch is recommended instead.
=back
@@ -161,8 +161,9 @@ See rackup documentation for more details.
=head1 CONTACT
-All feedback welcome via plain-text mail to L<yahns-public@yhbt.net>
+All feedback welcome via plain-text mail to L<mailto:yahns-public@yhbt.net>
No subscription is necessary to post to the mailing list.
+List archives are available at L<http://yhbt.net/yahns-public/>
=head1 COPYRIGHT
@@ -171,6 +172,7 @@ License: GPL-3.0+ L<http://www.gnu.org/licenses/gpl-3.0.txt>
=head1 SEE ALSO
-L<yahns(1)>, L<yahns_config(5)>, *Rack::Builder* ri/RDoc,
+L<yahns(1)>, L<yahns_config(5)>,
+L<Rack::Builder RDoc|http://www.rubydoc.info/github/rack/rack/Rack/Builder>,
L<Rack RDoc|http://www.rubydoc.info/github/rack/rack/>,
-L<Rackup HowTo|https://wiki.github.com/rack/rack/tutorial-rackup-howto>
+L<Rackup HowTo|https://github.com/rack/rack/wiki/tutorial-rackup-howto>
diff --git a/Documentation/yahns.pod b/Documentation/yahns.pod
index bad468e..dc21638 100644
--- a/Documentation/yahns.pod
+++ b/Documentation/yahns.pod
@@ -1,5 +1,3 @@
-% yahns(1) yahns user manual
-
=head1 NAME
yahns - multi-threaded, non-blocking application server for Ruby
@@ -86,6 +84,7 @@ See L<yahns_config(5)> for documentation on the configuration file format.
All feedback welcome via plain-text mail to L<mailto:yahns-public@yhbt.net>
No subscription is necessary to post to the mailing list.
+Mail archives are available at L<http://yhbt.net/yahns-public/>
=head1 COPYRIGHT
diff --git a/Documentation/yahns_config.pod b/Documentation/yahns_config.pod
index 858aaf1..cc1ea71 100644
--- a/Documentation/yahns_config.pod
+++ b/Documentation/yahns_config.pod
@@ -1,5 +1,3 @@
-% yahns_config(5) yahns user manual
-
=head1 NAME
yahns_config - configuration file description for L<yahns(1)>
@@ -28,7 +26,7 @@ An app with the same :TYPE and APP_ARGUMENTS may be defined multiple
times with different &BLOCK contents (with different listeners and
buffering settings).
-See the APP-LEVEL DIRECTIVES section for details on what goes into
+See the L</APP-LEVEL DIRECTIVES> section for details on what goes into
the &BLOCK.
This directive may be specified multiple times for different or
@@ -37,7 +35,7 @@ identical applications.
If the "working_directory" directive is used, all app directives may
only be specified after setting "working_directory".
-For Rack HTTP applications, see RACK APP ARGUMENTS for more
+For Rack HTTP applications, see L</RACK APP ARGUMENTS> for more
information.
=item before_exec &BLOCK
@@ -104,7 +102,7 @@ Default: none
As a top-level directive, this configures or defines a queue.
If no NAME is specified, a default queue (named :default) is
-assumed. See the QUEUE-LEVEL DIRECTIVES section for details.
+assumed. See the L</QUEUE-LEVEL DIRECTIVES> section for details.
A &BLOCK must be given if used as a top-level directive. This
behaves slightly differently inside an app &BLOCK. This may also
@@ -418,7 +416,7 @@ one of the yahns instances is stopped while using this.
This is supported on *BSD systems and Linux 3.9 or later.
-ref: https://lwn.net/Articles/542629/
+ref: L<https://lwn.net/Articles/542629/>
Default: false (unset)
@@ -435,22 +433,21 @@ Default: none
An example which seems to work is:
require 'openssl'
- ctx = OpenSSL::SSL::SSLContext.new
- ctx.cert =
- OpenSSL::X509::Certificate.new(
- IO.read('/etc/ssl/certs/example.crt')
- )
- ctx.extra_chain_cert = [
+ ssl_ctx = OpenSSL::SSL::SSLContext.new
+ ssl_ctx.cert = OpenSSL::X509::Certificate.new(
+ IO.read('/etc/ssl/certs/example.crt')
+ )
+ ssl_ctx.extra_chain_cert = [
OpenSSL::X509::Certificate.new(
IO.read('/etc/ssl/certs/chain.crt')
)
]
- ctx.key = OpenSSL::PKey::RSA.new(
+ ssl_ctx.key = OpenSSL::PKey::RSA.new(
IO.read('/etc/ssl/private/example.key')
)
app(:rack, "/path/to/my/app/config.ru") do
- listen 443, ssl_ctx: ctx
+ listen 443, ssl_ctx: ssl_ctx
end
=item umask: MODE
@@ -645,6 +642,12 @@ See the examples/ directory in the git source tree.
git clone git://yhbt.net/yahns.git
+=head1 CONTACT
+
+All feedback welcome via plain-text mail to L<mailto:yahns-public@yhbt.net>
+No subscription is necessary to post to the mailing list.
+List archives are available at L<http://yhbt.net/yahns-public/>
+
=head1 COPYRIGHT
Copyright (C) 2013-2016 all contributors L<mailto:yahns-public@yhbt.net>
diff --git a/examples/yahns_rack_basic.conf.rb b/examples/yahns_rack_basic.conf.rb
index 33ba619..f3f8e6a 100644
--- a/examples/yahns_rack_basic.conf.rb
+++ b/examples/yahns_rack_basic.conf.rb
@@ -31,7 +31,12 @@
end
app(:rack, "config.ru", preload: false) do
- listen 8080
+ listen 80
+
+ # See yahns_config(5) and OpenSSL::SSL::SSLContext on configuring
+ # HTTPS support
+ # listen 443, ssl_ctx: ...
+
client_max_body_size 1024 * 1024
input_buffering true
output_buffering true # this lazy by default
--
EW
^ permalink raw reply related [flat|nested] 4+ messages in thread