From 2b85ea421197af84a13f6062b21ddcf61490ebcf Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Mon, 27 Dec 2010 08:57:31 +0000 Subject: doc: misc cleanups and additions for RDoc This is also our website, so we need to document the new Cool.io-based concurrency options for users and point existing Rev* users to it. --- lib/rainbows/coolio.rb | 23 ++++++++++++++++++++++- lib/rainbows/coolio_fiber_spawn.rb | 13 ++++++++++++- lib/rainbows/coolio_thread_pool.rb | 20 +++++++++++++++++++- lib/rainbows/coolio_thread_spawn.rb | 20 +++++++++++++++++++- lib/rainbows/fiber.rb | 7 +++++-- lib/rainbows/fiber/io.rb | 2 +- lib/rainbows/rev.rb | 2 ++ lib/rainbows/rev_fiber_spawn.rb | 2 ++ lib/rainbows/rev_thread_pool.rb | 2 ++ lib/rainbows/rev_thread_spawn.rb | 2 ++ lib/rainbows/worker_yield.rb | 1 + lib/rainbows/writer_thread_pool/client.rb | 4 ++-- lib/rainbows/writer_thread_spawn/client.rb | 1 + 13 files changed, 90 insertions(+), 9 deletions(-) (limited to 'lib') diff --git a/lib/rainbows/coolio.rb b/lib/rainbows/coolio.rb index fb0a305..2fdc741 100644 --- a/lib/rainbows/coolio.rb +++ b/lib/rainbows/coolio.rb @@ -1,2 +1,23 @@ -# :enddoc: +# -*- encoding: binary -*- +# :stopdoc: Rainbows.const_set(:Coolio, Rainbows::Rev) +# :startdoc: + +# Implements a basic single-threaded event model with +# {Cool.io}[http://coolio.github.com/]. It is capable of handling +# thousands of simultaneous client connections, but with only a +# single-threaded app dispatch. It is suited for slow clients and +# fast applications (applications that do not have slow network +# dependencies) or applications that use DevFdResponse for deferrable +# response bodies. It does not require your Rack application to be +# thread-safe, reentrancy is only required for the DevFdResponse body +# generator. +# +# Compatibility: Whatever Cool.io itself supports, currently Ruby +# 1.8/1.9. +# +# This model does not implement as streaming "rack.input" which +# allows the Rack application to process data as it arrives. This +# means "rack.input" will be fully buffered in memory or to a +# temporary file before the application is entered. +module Rainbows::Coolio; end diff --git a/lib/rainbows/coolio_fiber_spawn.rb b/lib/rainbows/coolio_fiber_spawn.rb index 272d111..6e573b4 100644 --- a/lib/rainbows/coolio_fiber_spawn.rb +++ b/lib/rainbows/coolio_fiber_spawn.rb @@ -1,2 +1,13 @@ -# :enddoc: +# -*- encoding: binary -*- +# :stopdoc: Rainbows.const_set(:CoolioFiberSpawn, Rainbows::RevFiberSpawn) +# :startdoc: + +# A combination of the Coolio and FiberSpawn models. This allows Ruby +# 1.9 Fiber-based concurrency for application processing while +# exposing a synchronous execution model and using scalable network +# concurrency provided by Cool.io. A "rack.input" is exposed as well +# being Sunshowers-compatible. Applications are strongly advised to +# wrap all slow IO objects (sockets, pipes) using the +# Rainbows::Fiber::IO or a Cool.io-compatible class whenever possible. +module Rainbows::CoolFiberSpawn; end diff --git a/lib/rainbows/coolio_thread_pool.rb b/lib/rainbows/coolio_thread_pool.rb index acb1bdb..f96795e 100644 --- a/lib/rainbows/coolio_thread_pool.rb +++ b/lib/rainbows/coolio_thread_pool.rb @@ -1,2 +1,20 @@ -# :enddoc: +# -*- encoding: binary -*- +# :stopdoc: Rainbows.const_set(:CoolioThreadPool, Rainbows::RevThreadSpawn) +# :startdoc: + +# A combination of the Coolio and ThreadPool models. This allows Ruby +# Thread-based concurrency for application processing. It DOES NOT +# expose a streamable "rack.input" for upload processing within the +# app. DevFdResponse should be used with this class to proxy +# asynchronous responses. All network I/O between the client and +# server are handled by the main thread and outside of the core +# application dispatch. +# +# Unlike ThreadPool, Cool.io makes this model highly suitable for +# slow clients and applications with medium-to-slow response times +# (I/O bound), but less suitable for sleepy applications. +# +# This concurrency model is designed for Ruby 1.9, and Ruby 1.8 +# users are NOT advised to use this due to high CPU usage. +module Rainbows::CoolThreadPool; end diff --git a/lib/rainbows/coolio_thread_spawn.rb b/lib/rainbows/coolio_thread_spawn.rb index 1ca5c6c..81591d9 100644 --- a/lib/rainbows/coolio_thread_spawn.rb +++ b/lib/rainbows/coolio_thread_spawn.rb @@ -1,2 +1,20 @@ -# :enddoc: +# -*- encoding: binary -*- +# :stopdoc: Rainbows.const_set(:CoolioThreadSpawn, Rainbows::RevThreadSpawn) +# :startdoc: + +# A combination of the Coolio and ThreadSpawn models. This allows Ruby +# Thread-based concurrency for application processing. It DOES NOT +# expose a streamable "rack.input" for upload processing within the +# app. DevFdResponse should be used with this class to proxy +# asynchronous responses. All network I/O between the client and +# server are handled by the main thread and outside of the core +# application dispatch. +# +# Unlike ThreadSpawn, Cool.io makes this model highly suitable for +# slow clients and applications with medium-to-slow response times +# (I/O bound), but less suitable for sleepy applications. +# +# This concurrency model is designed for Ruby 1.9, and Ruby 1.8 +# users are NOT advised to use this due to high CPU usage. +module Rainbows::CoolioThreadSpawn; end diff --git a/lib/rainbows/fiber.rb b/lib/rainbows/fiber.rb index ed01147..3dc97c3 100644 --- a/lib/rainbows/fiber.rb +++ b/lib/rainbows/fiber.rb @@ -1,14 +1,16 @@ # -*- encoding: binary -*- -# :enddoc: +# :stopdoc: begin require 'fiber' rescue LoadError defined?(NeverBlock) or raise end +# :startdoc: -# core module for all things that use Fibers in Rainbows! +# core namespace for all things that use Fibers in \Rainbows! module Rainbows::Fiber + # :stopdoc: # blocked readers (key: fileno, value: Rainbows::Fiber::IO object) RD = [] @@ -17,6 +19,7 @@ module Rainbows::Fiber # sleeping fibers go here (key: Fiber object, value: wakeup time) ZZ = {} + # :startdoc: # puts the current Fiber into uninterruptible sleep for at least # +seconds+. Unlike Kernel#sleep, this it is not possible to sleep diff --git a/lib/rainbows/fiber/io.rb b/lib/rainbows/fiber/io.rb index 6c3d91c..ac243a4 100644 --- a/lib/rainbows/fiber/io.rb +++ b/lib/rainbows/fiber/io.rb @@ -18,7 +18,7 @@ class Rainbows::Fiber::IO end # :startdoc: - # needed to write errors with + # no longer used internally within Rainbows!, only for compatibility def write_nonblock(buf) @to_io.write_nonblock(buf) end diff --git a/lib/rainbows/rev.rb b/lib/rainbows/rev.rb index cb4701b..1e425fe 100644 --- a/lib/rainbows/rev.rb +++ b/lib/rainbows/rev.rb @@ -8,6 +8,8 @@ rescue LoadError end require 'rev' if defined?(Coolio) +# Coolio is the new version of this, use that instead. +# # Implements a basic single-threaded event model with # {Rev}[http://rev.rubyforge.org/]. It is capable of handling # thousands of simultaneous client connections, but with only a diff --git a/lib/rainbows/rev_fiber_spawn.rb b/lib/rainbows/rev_fiber_spawn.rb index 39483b3..4338703 100644 --- a/lib/rainbows/rev_fiber_spawn.rb +++ b/lib/rainbows/rev_fiber_spawn.rb @@ -1,6 +1,8 @@ # -*- encoding: binary -*- require 'rainbows/fiber/rev' +# CoolioFiberSpawn is the new version of this, use that instead. +# # A combination of the Rev and FiberSpawn models. This allows Ruby # 1.9 Fiber-based concurrency for application processing while # exposing a synchronous execution model and using scalable network diff --git a/lib/rainbows/rev_thread_pool.rb b/lib/rainbows/rev_thread_pool.rb index b377062..4366086 100644 --- a/lib/rainbows/rev_thread_pool.rb +++ b/lib/rainbows/rev_thread_pool.rb @@ -1,5 +1,7 @@ # -*- encoding: binary -*- +# CoolioThreadPool is the new version of this, use that instead. +# # A combination of the Rev and ThreadPool models. This allows Ruby # Thread-based concurrency for application processing. It DOES NOT # expose a streamable "rack.input" for upload processing within the diff --git a/lib/rainbows/rev_thread_spawn.rb b/lib/rainbows/rev_thread_spawn.rb index 94e9503..f19b68f 100644 --- a/lib/rainbows/rev_thread_spawn.rb +++ b/lib/rainbows/rev_thread_spawn.rb @@ -1,5 +1,7 @@ # -*- encoding: binary -*- +# CoolioThreadPool is the new version of this, use that instead. +# # A combination of the Rev and ThreadSpawn models. This allows Ruby # Thread-based concurrency for application processing. It DOES NOT # expose a streamable "rack.input" for upload processing within the diff --git a/lib/rainbows/worker_yield.rb b/lib/rainbows/worker_yield.rb index ec2a289..e81d358 100644 --- a/lib/rainbows/worker_yield.rb +++ b/lib/rainbows/worker_yield.rb @@ -1,3 +1,4 @@ +# -*- encoding: binary -*- # :enddoc: module Rainbows::WorkerYield diff --git a/lib/rainbows/writer_thread_pool/client.rb b/lib/rainbows/writer_thread_pool/client.rb index 5889e84..3cc3335 100644 --- a/lib/rainbows/writer_thread_pool/client.rb +++ b/lib/rainbows/writer_thread_pool/client.rb @@ -1,8 +1,8 @@ # -*- encoding: binary -*- -# +# :enddoc: # used to wrap a BasicSocket to use with +q+ for all writes # this is compatible with IO.select -class Rainbows::WriterThreadPool::Client < Struct.new(:to_io, :q) # :nodoc: +class Rainbows::WriterThreadPool::Client < Struct.new(:to_io, :q) include Rainbows::SocketProxy def write(buf) diff --git a/lib/rainbows/writer_thread_spawn/client.rb b/lib/rainbows/writer_thread_spawn/client.rb index ed60f42..8f65c19 100644 --- a/lib/rainbows/writer_thread_spawn/client.rb +++ b/lib/rainbows/writer_thread_spawn/client.rb @@ -1,4 +1,5 @@ # -*- encoding: binary -*- +# :enddoc: # used to wrap a BasicSocket to use with +q+ for all writes # this is compatible with IO.select class Rainbows::WriterThreadSpawn::Client < Struct.new(:to_io, :q, :thr) -- cgit v1.2.3-24-ge0c7