eventmachine 0.12.10-x86-mswin32-60 → 1.0.0.beta.2-x86-mswin32-60

data/docs/DEFERRABLES

@@ -1,133 +1,246 @@
-EventMachine (EM) adds two different formalisms for lightweight concurrency to the Ruby programmer's toolbox: spawned processes and deferrables. This note will show you how to use deferrables. For more information, see the separate document LIGHTWEIGHT_CONCURRENCY.
-
-=== What are Deferrables?
-
-EventMachine's Deferrable borrows heavily from the "deferred" object in Python's "Twisted" event-handling framework. Here's a minimal example that illustrates Deferrable:
-
- require 'eventmachine'
- 
- class MyClass
-   include EM::Deferrable
- 
-   def print_value x
-     puts "MyClass instance received #{x}"
-   end
- end
- 
- EM.run {
-   df = MyClass.new
-   df.callback {|x|
-     df.print_value(x)
-     EM.stop
-   }
- 
-   EM::Timer.new(2) {
-     df.set_deferred_status :succeeded, 100
-   }
- }
- 
-
-This program will spin for two seconds, print out the string "MyClass instance received 100" and then exit. The Deferrable pattern relies on an unusual metaphor that may be unfamiliar to you, unless you've used Python's Twisted. You may need to read the following material through more than once before you get the idea.
-
-EventMachine::Deferrable is simply a Ruby Module that you can include in your own classes. (There also is a class named EventMachine::DefaultDeferrable for when you want to create one without including it in code of your own.)
-
-An object that includes EventMachine::Deferrable is like any other Ruby object: it can be created whenever you want, returned from your functions, or passed as an argument to other functions.
-
-The Deferrable pattern allows you to specify any number of Ruby code blocks (callbacks or errbacks) that will be executed at some future time when the status of the Deferrable object changes.
-
-How might that be useful? Well, imagine that you're implementing an HTTP server, but you need to make a call to some other server in order to fulfill a client request.
-
-When you receive a request from one of your clients, you can create and return a Deferrable object. Some other section of your program can add a callback to the Deferrable that will cause the client's request to be fulfilled. Simultaneously, you initiate an event-driven or threaded client request to some different server. And then your EM program will continue to process other events and service other client requests.
-
-When your client request to the other server completes some time later, you will call the #set_deferred_status method on the Deferrable object, passing either a success or failure status, and an arbitrary number of parameters (which might include the data you received from the other server).
-
-At that point, the status of the Deferrable object becomes known, and its callback or errback methods are immediately executed. Callbacks and errbacks are code blocks that are attached to Deferrable objects at any time through the methods #callback and #errback.
-
-The deep beauty of this pattern is that it decouples the disposition of one operation (such as a client request to an outboard server) from the subsequent operations that depend on that disposition (which may include responding to a different client or any other operation).
-
-The code which invokes the deferred operation (that will eventually result in a success or failure status together with associated data) is completely separate from the code which depends on that status and data. This achieves one of the primary goals for which threading is typically used in sophisticated applications, with none of the nondeterminacy or debugging difficulties of threads.
-
-As soon as the deferred status of a Deferrable becomes known by way of a call to #set_deferred_status, the Deferrable will IMMEDIATELY execute all of its callbacks or errbacks in the order in which they were added to the Deferrable.
-
-Callbacks and errbacks can be added to a Deferrable object at any time, not just when the object is created. They can even be added after the status of the object has been determined! (In this case, they will be executed immediately when they are added.)
-
-A call to Deferrable#set_deferred_status takes :succeeded or :failed as its first argument. (This determines whether the object will call its callbacks or its errbacks.) #set_deferred_status also takes zero or more additional parameters, that will in turn be passed as parameters to the callbacks or errbacks.
-
-In general, you can only call #set_deferred_status ONCE on a Deferrable object. A call to #set_deferred_status will not return until all of the associated callbacks or errbacks have been called. If you add callbacks or errbacks AFTER making a call to #set_deferred_status, those additional callbacks or errbacks will execute IMMEDIATELY. Any given callback or errback will be executed AT MOST once.
-
-It's possible to call #set_deferred_status AGAIN, during the execution a callback or errback. This makes it possible to change the parameters which will be sent to the callbacks or errbacks farther down the chain, enabling some extremely elegant use-cases. You can transform the data returned from a deferred operation in arbitrary ways as needed by subsequent users, without changing any of the code that generated the original data.
-
-A call to #set_deferred_status will not return until all of the associated callbacks or errbacks have been called. If you add callbacks or errbacks AFTER making a call to #set_deferred_status, those additional callbacks or errbacks will execute IMMEDIATELY.
-
-Let's look at some more sample code. It turns out that many of the internal protocol implementations in the EventMachine package rely on Deferrable. One of these is EM::Protocols::HttpClient.
-
-To make an evented HTTP request, use the module function EM::Protocols::HttpClient#request, which returns a Deferrable object. Here's how:
-
- require 'eventmachine'
- 
- EM.run {
-   df = EM::Protocols::HttpClient.request( :host=>"www.example.com", :request=>"/index.html" )
- 
-   df.callback {|response|
-     puts "Succeeded: #{response[:content]}"
-     EM.stop
-   }
- 
-   df.errback {|response|
-     puts "ERROR: #{response[:status]}"
-     EM.stop
-   }
- }
-
-(See the documentation of EventMachine::Protocols::HttpClient for information on the object returned by #request.)
-
-In this code, we make a call to HttpClient#request, which immediately returns a Deferrable object. In the background, an HTTP client request is being made to www.example.com, although your code will continue to run concurrently.
-
-At some future point, the HTTP client request will complete, and the code in EM::Protocols::HttpClient will process either a valid HTTP response (including returned content), or an error.
-
-At that point, EM::Protocols::HttpClient will call EM::Deferrable#set_deferred_status on the Deferrable object that was returned to your program, as the return value from EM::Protocols::HttpClient.request. You don't have to do anything to make this happen. All you have to do is tell the Deferrable what to do in case of either success, failure, or both.
-
-In our code sample, we set one callback and one errback. The former will be called if the HTTP call succeeds, and the latter if it fails. (For simplicity, we have both of them calling EM#stop to end the program, although real programs would be very unlikely to do this.)
-
-Setting callbacks and errbacks is optional. They are handlers to defined events in the lifecycle of the Deferrable event. It's not an error if you fail to set either a callback, an errback, or both. But of course your program will then fail to receive those notifications.
-
-If through some bug it turns out that #set_deferred_status is never called on a Deferrable object, then that object's callbacks or errbacks will NEVER be called. It's also possible to set a timeout on a Deferrable. If the timeout elapses before any other call to #set_deferred_status, the Deferrable object will behave as is you had called set_deferred_status(:failed) on it.
-
-
-Now let's modify the example to illustrate some additional points:
-
- require 'eventmachine'
- 
- EM.run {
-   df = EM::Protocols::HttpClient.request( :host=>"www.example.com", :request=>"/index.html" )
- 
-   df.callback {|response|
-     df.set_deferred_status :succeeded, response[:content]
-   }
- 
-   df.callback {|string|
-     puts "Succeeded: #{string}"
-     EM.stop
-   }
- 
-   df.errback {|response|
-     puts "ERROR: #{response[:status]}"
-     EM.stop
-   }
- }
-
-
-Just for the sake of illustration, we've now set two callbacks instead of one. If the deferrable operation (the HTTP client-request) succeeds, then both of the callbacks will be executed in order.
-
-But notice that we've also made our own call to #set_deferred_status in the first callback. This isn't required, because the HttpClient implementation already made a call to #set_deferred_status. (Otherwise, of course, the callback would not be executing.)
-
-But we used #set_deferred_status in the first callback in order to change the parameters that will be sent to subsequent callbacks in the chain. In this way, you can construct powerful sequences of layered functionality. If you want, you can even change the status of the Deferrable from :succeeded to :failed, which would abort the chain of callback calls, and invoke the chain of errbacks instead.
-
-Now of course it's somewhat trivial to define two callbacks in the same method, even with the parameter-changing effect we just described. It would be much more interesting to pass the Deferrable to some other function (for example, a function defined in another module or a different gem), that would in turn add callbacks and/or errbacks of its own. That would illustrate the true power of the Deferrable pattern: to isolate the HTTP client-request from other functions that use the data that it returns without caring where those data came from.
-
-Remember that you can add a callback or an errback to a Deferrable at any point in time, regardless of whether the status of the deferred operation is known (more precisely, regardless of when #set_deferred_status is called on the object). Even hours or days later.
-
-When you add a callback or errback to a Deferrable object on which #set_deferred_status has not yet been called, the callback/errback is queued up for future execution, inside the Deferrable object. When you add a callback or errback to a Deferrable on which #set_deferred_status has already been called, the callback/errback will be executed immediately. Your code doesn't have to worry about the ordering, and there are no timing issues, as there would be with a threaded approach.
-
-For more information on Deferrables and their typical usage patterns, look in the EM unit tests. There are also quite a few sugarings (including EM::Deferrable#future) that make typical Deferrable usages syntactically easier to work with.
-
+EventMachine (EM) adds two different formalisms for lightweight concurrency
+to the Ruby programmer's toolbox: spawned processes and deferrables. This
+note will show you how to use deferrables. For more information, see the
+separate document LIGHTWEIGHT_CONCURRENCY.
+
+=== What are Deferrables?
+
+EventMachine's Deferrable borrows heavily from the "deferred" object in
+Python's "Twisted" event-handling framework. Here's a minimal example that
+illustrates Deferrable:
+
+ require 'eventmachine'
+
+ class MyClass
+   include EM::Deferrable
+
+   def print_value x
+     puts "MyClass instance received #{x}"
+   end
+ end
+
+ EM.run {
+   df = MyClass.new
+   df.callback {|x|
+     df.print_value(x)
+     EM.stop
+   }
+
+   EM::Timer.new(2) {
+     df.set_deferred_status :succeeded, 100
+   }
+ }
+
+
+This program will spin for two seconds, print out the string "MyClass
+instance received 100" and then exit. The Deferrable pattern relies on
+an unusual metaphor that may be unfamiliar to you, unless you've used
+Python's Twisted. You may need to read the following material through
+more than once before you get the idea.
+
+EventMachine::Deferrable is simply a Ruby Module that you can include
+in your own classes. (There also is a class named
+EventMachine::DefaultDeferrable for when you want to create one without
+including it in code of your own.)
+
+An object that includes EventMachine::Deferrable is like any other Ruby
+object: it can be created whenever you want, returned from your functions,
+or passed as an argument to other functions.
+
+The Deferrable pattern allows you to specify any number of Ruby code
+blocks (callbacks or errbacks) that will be executed at some future time
+when the status of the Deferrable object changes.
+
+How might that be useful? Well, imagine that you're implementing an HTTP
+server, but you need to make a call to some other server in order to fulfill
+a client request.
+
+When you receive a request from one of your clients, you can create and
+return a Deferrable object. Some other section of your program can add a
+callback to the Deferrable that will cause the client's request to be
+fulfilled. Simultaneously, you initiate an event-driven or threaded client
+request to some different server. And then your EM program will continue to
+process other events and service other client requests.
+
+When your client request to the other server completes some time later, you
+will call the #set_deferred_status method on the Deferrable object, passing
+either a success or failure status, and an arbitrary number of parameters
+(which might include the data you received from the other server).
+
+At that point, the status of the Deferrable object becomes known, and its
+callback or errback methods are immediately executed. Callbacks and errbacks
+are code blocks that are attached to Deferrable objects at any time through
+the methods #callback and #errback.
+
+The deep beauty of this pattern is that it decouples the disposition of one
+operation (such as a client request to an outboard server) from the
+subsequent operations that depend on that disposition (which may include
+responding to a different client or any other operation).
+
+The code which invokes the deferred operation (that will eventually result
+in a success or failure status together with associated data) is completely
+separate from the code which depends on that status and data. This achieves
+one of the primary goals for which threading is typically used in
+sophisticated applications, with none of the nondeterminacy or debugging
+difficulties of threads.
+
+As soon as the deferred status of a Deferrable becomes known by way of a call
+to #set_deferred_status, the Deferrable will IMMEDIATELY execute all of its
+callbacks or errbacks in the order in which they were added to the Deferrable.
+
+Callbacks and errbacks can be added to a Deferrable object at any time, not
+just when the object is created. They can even be added after the status of
+the object has been determined! (In this case, they will be executed
+immediately when they are added.)
+
+A call to Deferrable#set_deferred_status takes :succeeded or :failed as its
+first argument. (This determines whether the object will call its callbacks
+or its errbacks.) #set_deferred_status also takes zero or more additional
+parameters, that will in turn be passed as parameters to the callbacks or
+errbacks.
+
+In general, you can only call #set_deferred_status ONCE on a Deferrable
+object. A call to #set_deferred_status will not return until all of the
+associated callbacks or errbacks have been called. If you add callbacks or
+errbacks AFTER making a call to #set_deferred_status, those additional
+callbacks or errbacks will execute IMMEDIATELY. Any given callback or
+errback will be executed AT MOST once.
+
+It's possible to call #set_deferred_status AGAIN, during the execution a
+callback or errback. This makes it possible to change the parameters which
+will be sent to the callbacks or errbacks farther down the chain, enabling
+some extremely elegant use-cases. You can transform the data returned from
+a deferred operation in arbitrary ways as needed by subsequent users, without
+changing any of the code that generated the original data.
+
+A call to #set_deferred_status will not return until all of the associated
+callbacks or errbacks have been called. If you add callbacks or errbacks
+AFTER making a call to #set_deferred_status, those additional callbacks or
+errbacks will execute IMMEDIATELY.
+
+Let's look at some more sample code. It turns out that many of the internal
+protocol implementations in the EventMachine package rely on Deferrable. One
+of these is EM::Protocols::HttpClient.
+
+To make an evented HTTP request, use the module function
+EM::Protocols::HttpClient#request, which returns a Deferrable object.
+Here's how:
+
+ require 'eventmachine'
+
+ EM.run {
+   df = EM::Protocols::HttpClient.request( :host=>"www.example.com",
+                                           :request=>"/index.html" )
+
+   df.callback {|response|
+     puts "Succeeded: #{response[:content]}"
+     EM.stop
+   }
+
+   df.errback {|response|
+     puts "ERROR: #{response[:status]}"
+     EM.stop
+   }
+ }
+
+(See the documentation of EventMachine::Protocols::HttpClient for information
+on the object returned by #request.)
+
+In this code, we make a call to HttpClient#request, which immediately returns
+a Deferrable object. In the background, an HTTP client request is being made
+to www.example.com, although your code will continue to run concurrently.
+
+At some future point, the HTTP client request will complete, and the code in
+EM::Protocols::HttpClient will process either a valid HTTP response (including
+returned content), or an error.
+
+At that point, EM::Protocols::HttpClient will call
+EM::Deferrable#set_deferred_status on the Deferrable object that was returned
+to your program, as the return value from EM::Protocols::HttpClient.request.
+You don't have to do anything to make this happen. All you have to do is tell
+the Deferrable what to do in case of either success, failure, or both.
+
+In our code sample, we set one callback and one errback. The former will be
+called if the HTTP call succeeds, and the latter if it fails. (For
+simplicity, we have both of them calling EM#stop to end the program, although
+real programs would be very unlikely to do this.)
+
+Setting callbacks and errbacks is optional. They are handlers to defined
+events in the lifecycle of the Deferrable event. It's not an error if you
+fail to set either a callback, an errback, or both. But of course your
+program will then fail to receive those notifications.
+
+If through some bug it turns out that #set_deferred_status is never called
+on a Deferrable object, then that object's callbacks or errbacks will NEVER
+be called. It's also possible to set a timeout on a Deferrable. If the
+timeout elapses before any other call to #set_deferred_status, the Deferrable
+object will behave as is you had called set_deferred_status(:failed) on it.
+
+
+Now let's modify the example to illustrate some additional points:
+
+ require 'eventmachine'
+
+ EM.run {
+   df = EM::Protocols::HttpClient.request( :host=>"www.example.com",
+                                           :request=>"/index.html" )
+
+   df.callback {|response|
+     df.set_deferred_status :succeeded, response[:content]
+   }
+
+   df.callback {|string|
+     puts "Succeeded: #{string}"
+     EM.stop
+   }
+
+   df.errback {|response|
+     puts "ERROR: #{response[:status]}"
+     EM.stop
+   }
+ }
+
+
+Just for the sake of illustration, we've now set two callbacks instead of
+one. If the deferrable operation (the HTTP client-request) succeeds, then
+both of the callbacks will be executed in order.
+
+But notice that we've also made our own call to #set_deferred_status in the
+first callback. This isn't required, because the HttpClient implementation
+already made a call to #set_deferred_status. (Otherwise, of course, the
+callback would not be executing.)
+
+But we used #set_deferred_status in the first callback in order to change the
+parameters that will be sent to subsequent callbacks in the chain. In this
+way, you can construct powerful sequences of layered functionality. If you
+want, you can even change the status of the Deferrable from :succeeded to
+:failed, which would abort the chain of callback calls, and invoke the chain
+of errbacks instead.
+
+Now of course it's somewhat trivial to define two callbacks in the same
+method, even with the parameter-changing effect we just described. It would
+be much more interesting to pass the Deferrable to some other function (for
+example, a function defined in another module or a different gem), that would
+in turn add callbacks and/or errbacks of its own. That would illustrate the
+true power of the Deferrable pattern: to isolate the HTTP client-request
+from other functions that use the data that it returns without caring where
+those data came from.
+
+Remember that you can add a callback or an errback to a Deferrable at any
+point in time, regardless of whether the status of the deferred operation is
+known (more precisely, regardless of when #set_deferred_status is called on
+the object). Even hours or days later.
+
+When you add a callback or errback to a Deferrable object on which
+#set_deferred_status has not yet been called, the callback/errback is queued
+up for future execution, inside the Deferrable object. When you add a
+callback or errback to a Deferrable on which #set_deferred_status has
+already been called, the callback/errback will be executed immediately.
+Your code doesn't have to worry about the ordering, and there are no timing
+issues, as there would be with a threaded approach.
+
+For more information on Deferrables and their typical usage patterns, look
+in the EM unit tests. There are also quite a few sugarings (including
+EM::Deferrable#future) that make typical Deferrable usages syntactically
+easier to work with.
+

data/docs/EPOLL

@@ -1,141 +1,141 @@
-EventMachine now supports epoll, bringing large increases in performance and scalability to Ruby programs.
-
-Epoll(7) is a alternative mechanism for multiplexed I/O that is available in Linux 2.6 kernels.
-It features significantly greater performance than the standard select(2) mechanism, when used in
-applications that require very large numbers of open I/O descriptors.
-
-EventMachine has always used select(2) because its behavior is well standardized and broadly supported.
-But select becomes unreasonably slow when a program has a
-very large number of file descriptors or sockets. Ruby's version of select hardcodes a limit
-of 1024 descriptors per process, but heavily loaded processes will start to show performance
-degradation even after only a few hundred descriptors are in use.
-
-Epoll is an extended version of the poll(2) call, and it solves the problems with select. Programs
-based on epoll can easily scale past Ruby's 1024-descriptor limit, potentially to tens of thousands
-of connectors, with no significant impact on performance.
-
-(Another alternative which is very similar to epoll in principle is kqueue, supplied on BSD and its
-variants.)
-
-
-
-This note shows you how to use epoll in your programs.
-
-=== Compiling EventMachine to use epoll.
-
-You don't have to do anything to get epoll support in EventMachine.
-When you compile EventMachine on a platform that supports epoll, EM will
-automatically generate a Makefile that includes epoll. (At this writing, this will only work
-on Linux 2.6 kernels.) If you compile EM on a platform without epoll, then epoll support will
-be omitted from the Makefile, and EM will work just as it always has.
-
-=== Using epoll in your programs.
-
-First, you need to tell EventMachine to use epoll instead of select (but see below, as this requirement
-will be removed in a future EventMachine version). Second, you need to prepare your program to use
-more than 1024 descriptors, an operation that generally requires superuser privileges. Third, you will probably
-want your process to drop the superuser privileges after you increase your process's descriptor limit.
-
-=== Using EventMachine#epoll
-
-Call the method EventMachine#epoll anytime before you call EventMachine#run, and your program will
-automatically use epoll, if available. It's safe to call EventMachine#epoll on any platform because
-it compiles to a no-op on platforms that don't support epoll.
-
-  require 'rubygems'
-  require 'eventmachine'
-
-  EM.epoll
-  EM.run {
-    ...
-  }
-
-
-EventMachine#epoll was included in this initial release only to avoid changing the behavior of existing
-programs. However, it's expected that a future release of EM will convert EventMachine#epoll to a no-op,
-and run epoll by default on platforms that support it.
-
-=== Using EventMachine#set_descriptor_table_size
-
-In Linux (as in every Unix-like platform), every process has a internal table that determines the maximum
-number of file and socket descriptors you may have open at any given time. The size of this table is
-generally fixed at 1024, although it may be increased within certain system-defined hard and soft limits.
-
-If you want your EventMachine program to support more than 1024 total descriptors, you must use 
-EventMachine#set_descriptor_table_size, as follows:
-
-  require 'rubygems'
-  require 'eventmachine'
-
-  new_size = EM.set_descriptor_table_size( 60000 )
-  $>.puts "New descriptor-table size is #{new_size}"
-
-  EM.run {
-    ...
-  }
-
-If successful, this example will increase the maximum number of descriptors that epoll can use to 60,000.
-Call EventMachine#set_descriptor_table_size without an argument at any time to find out the current
-size of the descriptor table.
-
-Using EventMachine#set_descriptor_table_size ONLY affects the number of descriptors that can be used
-by epoll. It has no useful effect on platforms that don't support epoll, and it does NOT increase the
-number of descriptors that Ruby's own I/O functions can use.
-
-#set_descriptor_table_size can fail if your process is not running as superuser, or if you try to set a
-table size that exceeds the hard limits imposed by your system. In the latter case, try a smaller number.
-
-
-=== Using EventMachine#set_effective_user
-
-In general, you must run your program with elevated or superuser privileges if you want to increase
-your descriptor-table size beyond 1024 descriptors. This is easy enough to verify. Try running the
-sample program given above, that increases the descriptor limit to 60,000. You will probably find that
-the table size will not be increased if you don't run your program as root or with elevated privileges.
-
-But of course network servers, especially long-running ones, should not run with elevated privileges.
-You will want to drop superuser privileges as soon as possible after initialization. To do this,
-use EventMachine#set_effective_user:
-
-  require 'rubygems'
-  require 'eventmachine'
-
-  # (Here, program is running as superuser)
-
-  EM.set_descriptor_table_size( 60000 )
-  EM.set_effective_user( "nobody" )
-  # (Here, program is running as nobody)
-
-  EM.run {
-    ...
-  }
-
-Of course, you will need to replace "nobody" in the example with the name of an unprivileged user
-that is valid on your system. What if you want to drop privileges after opening a server socket
-on a privileged (low-numbered) port? Easy, just call #set_effective_user after opening your sockets:
-
-  require 'rubygems'
-  require 'eventmachine'
-
-  # (Here, program is running as superuser)
-
-  EM.set_descriptor_table_size( 60000 )
-
-  EM.run {
-    EM.start_server( "0.0.0.0", 80, MyHttpServer )
-    EM.start_server( "0.0.0.0", 443, MyEncryptedHttpServer )
-
-    EM.set_effective_user( "nobody" )
-    # (Here, program is running as nobody)
-
-    ...
-  }
-
-
-Because EventMachine#set_effective_user is used to enforce security
-requirements, it has no nonfatal errors. If you try to set a nonexistent or invalid effective user,
-#set_effective_user will abort your program, rather than continue to run with elevated privileges.
-
-EventMachine#set_effective_user is a silent no-op on platforms that don't support it, such as Windows.
-
-
+EventMachine now supports epoll, bringing large increases in performance and scalability to Ruby programs.
+
+Epoll(7) is a alternative mechanism for multiplexed I/O that is available in Linux 2.6 kernels.
+It features significantly greater performance than the standard select(2) mechanism, when used in
+applications that require very large numbers of open I/O descriptors.
+
+EventMachine has always used select(2) because its behavior is well standardized and broadly supported.
+But select becomes unreasonably slow when a program has a
+very large number of file descriptors or sockets. Ruby's version of select hardcodes a limit
+of 1024 descriptors per process, but heavily loaded processes will start to show performance
+degradation even after only a few hundred descriptors are in use.
+
+Epoll is an extended version of the poll(2) call, and it solves the problems with select. Programs
+based on epoll can easily scale past Ruby's 1024-descriptor limit, potentially to tens of thousands
+of connectors, with no significant impact on performance.
+
+(Another alternative which is very similar to epoll in principle is kqueue, supplied on BSD and its
+variants.)
+
+
+
+This note shows you how to use epoll in your programs.
+
+=== Compiling EventMachine to use epoll.
+
+You don't have to do anything to get epoll support in EventMachine.
+When you compile EventMachine on a platform that supports epoll, EM will
+automatically generate a Makefile that includes epoll. (At this writing, this will only work
+on Linux 2.6 kernels.) If you compile EM on a platform without epoll, then epoll support will
+be omitted from the Makefile, and EM will work just as it always has.
+
+=== Using epoll in your programs.
+
+First, you need to tell EventMachine to use epoll instead of select (but see below, as this requirement
+will be removed in a future EventMachine version). Second, you need to prepare your program to use
+more than 1024 descriptors, an operation that generally requires superuser privileges. Third, you will probably
+want your process to drop the superuser privileges after you increase your process's descriptor limit.
+
+=== Using EventMachine#epoll
+
+Call the method EventMachine#epoll anytime before you call EventMachine#run, and your program will
+automatically use epoll, if available. It's safe to call EventMachine#epoll on any platform because
+it compiles to a no-op on platforms that don't support epoll.
+
+  require 'rubygems'
+  require 'eventmachine'
+
+  EM.epoll
+  EM.run {
+    ...
+  }
+
+
+EventMachine#epoll was included in this initial release only to avoid changing the behavior of existing
+programs. However, it's expected that a future release of EM will convert EventMachine#epoll to a no-op,
+and run epoll by default on platforms that support it.
+
+=== Using EventMachine#set_descriptor_table_size
+
+In Linux (as in every Unix-like platform), every process has a internal table that determines the maximum
+number of file and socket descriptors you may have open at any given time. The size of this table is
+generally fixed at 1024, although it may be increased within certain system-defined hard and soft limits.
+
+If you want your EventMachine program to support more than 1024 total descriptors, you must use 
+EventMachine#set_descriptor_table_size, as follows:
+
+  require 'rubygems'
+  require 'eventmachine'
+
+  new_size = EM.set_descriptor_table_size( 60000 )
+  $>.puts "New descriptor-table size is #{new_size}"
+
+  EM.run {
+    ...
+  }
+
+If successful, this example will increase the maximum number of descriptors that epoll can use to 60,000.
+Call EventMachine#set_descriptor_table_size without an argument at any time to find out the current
+size of the descriptor table.
+
+Using EventMachine#set_descriptor_table_size ONLY affects the number of descriptors that can be used
+by epoll. It has no useful effect on platforms that don't support epoll, and it does NOT increase the
+number of descriptors that Ruby's own I/O functions can use.
+
+#set_descriptor_table_size can fail if your process is not running as superuser, or if you try to set a
+table size that exceeds the hard limits imposed by your system. In the latter case, try a smaller number.
+
+
+=== Using EventMachine#set_effective_user
+
+In general, you must run your program with elevated or superuser privileges if you want to increase
+your descriptor-table size beyond 1024 descriptors. This is easy enough to verify. Try running the
+sample program given above, that increases the descriptor limit to 60,000. You will probably find that
+the table size will not be increased if you don't run your program as root or with elevated privileges.
+
+But of course network servers, especially long-running ones, should not run with elevated privileges.
+You will want to drop superuser privileges as soon as possible after initialization. To do this,
+use EventMachine#set_effective_user:
+
+  require 'rubygems'
+  require 'eventmachine'
+
+  # (Here, program is running as superuser)
+
+  EM.set_descriptor_table_size( 60000 )
+  EM.set_effective_user( "nobody" )
+  # (Here, program is running as nobody)
+
+  EM.run {
+    ...
+  }
+
+Of course, you will need to replace "nobody" in the example with the name of an unprivileged user
+that is valid on your system. What if you want to drop privileges after opening a server socket
+on a privileged (low-numbered) port? Easy, just call #set_effective_user after opening your sockets:
+
+  require 'rubygems'
+  require 'eventmachine'
+
+  # (Here, program is running as superuser)
+
+  EM.set_descriptor_table_size( 60000 )
+
+  EM.run {
+    EM.start_server( "0.0.0.0", 80, MyHttpServer )
+    EM.start_server( "0.0.0.0", 443, MyEncryptedHttpServer )
+
+    EM.set_effective_user( "nobody" )
+    # (Here, program is running as nobody)
+
+    ...
+  }
+
+
+Because EventMachine#set_effective_user is used to enforce security
+requirements, it has no nonfatal errors. If you try to set a nonexistent or invalid effective user,
+#set_effective_user will abort your program, rather than continue to run with elevated privileges.
+
+EventMachine#set_effective_user is a silent no-op on platforms that don't support it, such as Windows.
+
+