about summary refs log tree commit homepage
diff options
context:
space:
mode:
authorEric Wong <normalperson@yhbt.net>2011-04-26 14:04:26 -0700
committerEric Wong <normalperson@yhbt.net>2011-04-26 14:04:26 -0700
commit6ea50dd6866a7b4eda5134cb2c8980710285e127 (patch)
tree1022141ba80b29f269c925bfd9dce702c3edfc6c
parent5bd08f7bb06367823412bd3410bcb41babd6d57b (diff)
downloadrainbows-6ea50dd6866a7b4eda5134cb2c8980710285e127.tar.gz
Too much NIH and too fragile.
-rw-r--r--lib/rainbows/coolio_fiber_spawn.rb18
-rw-r--r--lib/rainbows/fiber.rb5
-rw-r--r--lib/rainbows/fiber/io.rb13
-rw-r--r--lib/rainbows/fiber/io/pipe.rb7
-rw-r--r--lib/rainbows/fiber/io/socket.rb7
-rw-r--r--lib/rainbows/fiber_pool.rb19
-rw-r--r--lib/rainbows/fiber_spawn.rb17
7 files changed, 60 insertions, 26 deletions
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