From 6ea50dd6866a7b4eda5134cb2c8980710285e127 Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Tue, 26 Apr 2011 14:04:26 -0700 Subject: doc: stop recommending Fiber* stuff Too much NIH and too fragile. --- lib/rainbows/coolio_fiber_spawn.rb | 18 +++++++++++------- lib/rainbows/fiber.rb | 5 +++++ lib/rainbows/fiber/io.rb | 13 +++++++++---- lib/rainbows/fiber/io/pipe.rb | 7 ++++++- lib/rainbows/fiber/io/socket.rb | 7 ++++++- lib/rainbows/fiber_pool.rb | 19 ++++++++++++------- lib/rainbows/fiber_spawn.rb | 17 +++++++++++------ 7 files changed, 60 insertions(+), 26 deletions(-) (limited to 'lib') diff --git a/lib/rainbows/coolio_fiber_spawn.rb b/lib/rainbows/coolio_fiber_spawn.rb index 52b3e63..7b00d58 100644 --- a/lib/rainbows/coolio_fiber_spawn.rb +++ b/lib/rainbows/coolio_fiber_spawn.rb @@ -1,13 +1,17 @@ # -*- encoding: binary -*- require 'rainbows/fiber/coolio' -# 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 streaming "rack.input" is exposed. -# 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. +# A combination of the Coolio and FiberSpawn models. +# +# This concurrency model is difficult to use with existing applications, +# lacks third-party support, and is thus NOT recommended. +# +# 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 streaming +# "rack.input" is exposed. 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::CoolioFiberSpawn include Rainbows::Base diff --git a/lib/rainbows/fiber.rb b/lib/rainbows/fiber.rb index 3dc97c3..34b7c39 100644 --- a/lib/rainbows/fiber.rb +++ b/lib/rainbows/fiber.rb @@ -8,6 +8,11 @@ end # :startdoc: # core namespace for all things that use Fibers in \Rainbows! +# +# It's generally not recommended to use any of this in your applications +# unless you're willing to accept breakage. Most of this is very +# difficult-to-use, fragile and we don't have much time to devote to +# supporting these in the future. module Rainbows::Fiber # :stopdoc: diff --git a/lib/rainbows/fiber/io.rb b/lib/rainbows/fiber/io.rb index da377d0..3005d96 100644 --- a/lib/rainbows/fiber/io.rb +++ b/lib/rainbows/fiber/io.rb @@ -1,13 +1,18 @@ # -*- encoding: binary -*- -# A Fiber-aware IO class, gives users the illusion of a synchronous -# interface that yields away from the current Fiber whenever +# A \Fiber-aware IO class, gives users the illusion of a synchronous +# interface that yields away from the current \Fiber whenever # the underlying descriptor is blocked on reads or write # +# It's not recommended to use any of this in your applications +# unless you're willing to accept breakage. Most of this is very +# difficult-to-use, fragile and we don't have much time to devote to +# supporting these in the future. +# # This is a stable, legacy interface and should be preserved for all # future versions of Rainbows! However, new apps should use -# Rainbows::Fiber::IO::Socket or Rainbows::Fiber::IO::Pipe instead. - +# Rainbows::Fiber::IO::Socket or Rainbows::Fiber::IO::Pipe instead +# (or better yet, avoid any of the Rainbows::Fiber* stuff). class Rainbows::Fiber::IO attr_accessor :to_io diff --git a/lib/rainbows/fiber/io/pipe.rb b/lib/rainbows/fiber/io/pipe.rb index c7ae508..59114d7 100644 --- a/lib/rainbows/fiber/io/pipe.rb +++ b/lib/rainbows/fiber/io/pipe.rb @@ -1,7 +1,12 @@ # -*- encoding: binary -*- # A Fiber-aware Pipe class, gives users the illusion of a synchronous # interface that yields away from the current Fiber whenever -# the underlying descriptor is blocked on reads or write +# the underlying descriptor is blocked on reads or write. +# +# It's not recommended to use any of this in your applications +# unless you're willing to accept breakage. Most of this is very +# difficult-to-use, fragile and we don't have much time to devote to +# supporting these in the future. class Rainbows::Fiber::IO::Pipe < Kgio::Pipe include Rainbows::Fiber::IO::Methods end diff --git a/lib/rainbows/fiber/io/socket.rb b/lib/rainbows/fiber/io/socket.rb index 61c451d..2b4df12 100644 --- a/lib/rainbows/fiber/io/socket.rb +++ b/lib/rainbows/fiber/io/socket.rb @@ -1,7 +1,12 @@ # -*- encoding: binary -*- # A Fiber-aware Socket class, gives users the illusion of a synchronous # interface that yields away from the current Fiber whenever -# the underlying descriptor is blocked on reads or write +# the underlying descriptor is blocked on reads or write. +# +# It's not recommended to use any of this in your applications +# unless you're willing to accept breakage. Most of this is very +# difficult-to-use, fragile and we don't have much time to devote to +# supporting these in the future. class Rainbows::Fiber::IO::Socket < Kgio::Socket include Rainbows::Fiber::IO::Methods end diff --git a/lib/rainbows/fiber_pool.rb b/lib/rainbows/fiber_pool.rb index 7e50723..64a638c 100644 --- a/lib/rainbows/fiber_pool.rb +++ b/lib/rainbows/fiber_pool.rb @@ -3,13 +3,18 @@ require 'rainbows/fiber' # A Fiber-based concurrency model for Ruby 1.9. This uses a pool of # Fibers to handle client IO to run the application and the root Fiber -# for scheduling and connection acceptance. The pool size is equal to -# the number of +worker_connections+. Compared to the ThreadPool -# model, Fibers are very cheap in terms of memory usage so you can -# have more active connections. This model supports a streaming -# "rack.input" with lightweight concurrency. Applications are -# strongly advised to wrap all slow IO objects (sockets, pipes) using -# the Rainbows::Fiber::IO class whenever possible. +# for scheduling and connection acceptance. +# +# This concurrency model is difficult to use with existing applications, +# lacks third-party support, and is thus NOT recommended. +# +# The pool size is equal to the number of +worker_connections+. +# Compared to the ThreadPool model, Fibers are very cheap in terms of +# memory usage so you can have more active connections. This model +# supports a streaming "rack.input" with lightweight concurrency. +# Applications are strongly advised to wrap all slow IO objects +# (sockets, pipes) using the Rainbows::Fiber::IO class whenever +# possible. module Rainbows::FiberPool include Rainbows::Fiber::Base diff --git a/lib/rainbows/fiber_spawn.rb b/lib/rainbows/fiber_spawn.rb index b8552d7..2c6d13d 100644 --- a/lib/rainbows/fiber_spawn.rb +++ b/lib/rainbows/fiber_spawn.rb @@ -1,12 +1,17 @@ # -*- encoding: binary -*- require 'rainbows/fiber' -# Simple Fiber-based concurrency model for 1.9. This spawns a new -# Fiber for every incoming client connection and the root Fiber for -# scheduling and connection acceptance. This exports a streaming -# "rack.input" with lightweight concurrency. Applications are -# strongly advised to wrap all slow IO objects (sockets, pipes) using -# the Rainbows::Fiber::IO class whenever possible. +# Simple Fiber-based concurrency model for 1.9. This spawns a new Fiber +# for every incoming client connection and the root Fiber for scheduling +# and connection acceptance. +# +# This concurrency model is difficult to use with existing applications, +# lacks third-party support, and is thus NOT recommended. +# +# This exports a streaming "rack.input" with lightweight concurrency. +# Applications are strongly advised to wrap all slow IO objects +# (sockets, pipes) using the Rainbows::Fiber::IO class whenever +# possible. module Rainbows::FiberSpawn include Rainbows::Fiber::Base -- cgit v1.2.3-24-ge0c7