Permalink
Browse files

Documentation revamp.

Signed-off-by: Aman Gupta <aman@tmm1.net>
  • Loading branch information...
1 parent d326bb3 commit 38705c4418b6af33455cdfd8b6184d9cccded0fc @michaelklishin michaelklishin committed with tmm1 Apr 24, 2011
Showing with 2,548 additions and 1,298 deletions.
  1. +5 −0 .gitignore
  2. +5 −1 .yardopts
  3. 0 {docs → }/GNU
  4. +1 −0 Gemfile
  5. 0 docs/COPYING → LICENSE
  6. +0 −81 README
  7. +109 −0 README.md
  8. +8 −0 Rakefile
  9. +27 −0 docs/DocumentationGuidesIndex.md
  10. +521 −0 docs/GettingStarted.md
  11. 0 docs/{ → old}/ChangeLog
  12. 0 docs/{ → old}/DEFERRABLES
  13. 0 docs/{ → old}/EPOLL
  14. 0 docs/{ → old}/INSTALL
  15. 0 docs/{ → old}/KEYBOARD
  16. 0 docs/{ → old}/LEGAL
  17. 0 docs/{ → old}/LIGHTWEIGHT_CONCURRENCY
  18. 0 docs/{ → old}/PURE_RUBY
  19. 0 docs/{ → old}/RELEASE_NOTES
  20. 0 docs/{ → old}/SMTP
  21. 0 docs/{ → old}/SPAWNED_PROCESSES
  22. 0 docs/{ → old}/TODO
  23. +4 −2 eventmachine.gemspec
  24. +18 −0 examples/guides/getting_started/01_eventmachine_echo_server.rb
  25. +22 −0 examples/guides/getting_started/02_eventmachine_echo_server_that_recognizes_exit_command.rb
  26. +149 −0 examples/guides/getting_started/03_simple_chat_server.rb
  27. +27 −0 examples/guides/getting_started/04_simple_chat_server_step_one.rb
  28. +43 −0 examples/guides/getting_started/05_simple_chat_server_step_two.rb
  29. +98 −0 examples/guides/getting_started/06_simple_chat_server_step_three.rb
  30. +121 −0 examples/guides/getting_started/07_simple_chat_server_step_four.rb
  31. +141 −0 examples/guides/getting_started/08_simple_chat_server_step_five.rb
  32. +3 −3 examples/{ → old}/ex_channel.rb
  33. 0 examples/{ → old}/ex_queue.rb
  34. 0 examples/{ → old}/ex_tick_loop_array.rb
  35. 0 examples/{ → old}/ex_tick_loop_counter.rb
  36. 0 examples/{ → old}/helper.rb
  37. +35 −63 lib/em/buftok.rb
  38. +43 −11 lib/em/callback.rb
  39. +21 −14 lib/em/channel.rb
  40. +321 −205 lib/em/connection.rb
  41. +37 −18 lib/em/file_watch.rb
  42. +16 −11 lib/em/protocols/httpclient.rb
  43. +13 −7 lib/em/protocols/smtpclient.rb
  44. +197 −206 lib/em/pure_ruby.rb
  45. +16 −14 lib/em/queue.rb
  46. +31 −43 lib/em/streamer.rb
  47. +1 −0 lib/em/timers.rb
  48. +493 −587 lib/eventmachine.rb
  49. +10 −0 lib/jeventmachine.rb
  50. +0 −30 tasks/doc.rake
  51. +12 −2 tasks/package.rake
View
@@ -14,3 +14,8 @@ Makefile
*.dSYM
java/src/.project
*.rbc
+Gemfile.lock
+
+.yardoc/*
+doc/*
+
View
@@ -1,3 +1,7 @@
+--no-private
+--protected
+--markup="markdown" lib/**/*.rb
+--main README.md
--exclude jeventmachine --exclude pure_ruby
-
-docs/DEFERRABLES docs/EPOLL docs/KEYBOARD
+docs/*.md
View
File renamed without changes.
View
@@ -1,2 +1,3 @@
source :rubygems
gemspec
+
View
File renamed without changes.
View
81 README
@@ -1,81 +0,0 @@
-= RUBY/EventMachine
-
-Homepage:: http://rubyeventmachine.com
-Rubyforge Page:: http://rubyforge.org/projects/eventmachine
-Google Group:: http://groups.google.com/group/eventmachine
-RDoc:: http://eventmachine.rubyforge.org
-IRC:: #eventmachine on irc.freenode.net
-Copyright:: (C) 2006-07 by Francis Cianfrocca. All Rights Reserved.
-Email:: gmail address: garbagecat10
-
-EventMachine is copyrighted free software made available under the terms
-of either the GPL or Ruby's License. See the file COPYING for full licensing
-information.
-See EventMachine and EventMachine::Connection for documentation and
-usage examples.
-
-EventMachine implements a fast, single-threaded engine for arbitrary network
-communications. It's extremely easy to use in Ruby. EventMachine wraps all
-interactions with IP sockets, allowing programs to concentrate on the
-implementation of network protocols. It can be used to create both network
-servers and clients. To create a server or client, a Ruby program only needs
-to specify the IP address and port, and provide a Module that implements the
-communications protocol. Implementations of several standard network protocols
-are provided with the package, primarily to serve as examples. The real goal
-of EventMachine is to enable programs to easily interface with other programs
-using TCP/IP, especially if custom protocols are required.
-
-A Ruby program uses EventMachine by registering the addresses and ports of
-network servers and clients, and then entering an event-handling loop.
-EventMachine contains glue code in Ruby which will execute callbacks to
-user-supplied code for all significant events occurring in the clients
-and servers. These events include connection acceptance, startup, data-receipt,
-shutdown, and timer events. Arbitrary processing can be performed by user code
-during event callbacks, including sending data to one or more remote network
-peers, startup and shutdown of network connections, and installation of new
-event handlers.
-
-The EventMachine implements a very familiar model for network programming.
-It emphasizes: 1) the maximum possible isolation of user code from network
-objects like sockets; 2) maximum performance and scalability; and 3) extreme
-ease-of-use for user code. It attempts to provide a higher-level interface
-than similar projects which expose a variety of low-level event-handling
-and networking objects to Ruby programs.
-
-The design and implementation of EventMachine grows out of nearly ten years
-of experience writing high-performance, high-scaling network server applications.
-We have taken particular account of the challenges and lessons described as
-the "C10K problem" by Dan Kegel and others.
-
-EventMachine consists of an extension library written in C++ (which can be
-accessed from languages other than Ruby), and a Ruby module which can be dropped
-into user programs. On most platforms, EventMachine uses the
-<tt>select(2)</tt> system call,
-so it will run on a large range of Unix-like systems and on Microsoft
-Windows with good performance and scalability. On Linux 2.6 kernels, EventMachine
-automatically configures itself to use <tt>epoll(4)</tt> instead of
-<tt>select(2),</tt> so scalability on that platform can be significantly
-improved.
-
-Here's a fully-functional echo server written with EventMachine:
-
- require 'eventmachine'
-
- module EchoServer
- def post_init
- puts "-- someone connected to the echo server!"
- end
-
- def receive_data data
- send_data ">>>you sent: #{data}"
- close_connection if data =~ /quit/i
- end
-
- def unbind
- puts "-- someone disconnected from the echo server!"
- end
- end
-
- EventMachine::run {
- EventMachine::start_server "127.0.0.1", 8081, EchoServer
- }
View
109 README.md
@@ -0,0 +1,109 @@
+# About EventMachine #
+
+
+## What is EventMachine ##
+
+EventMachine is an event-driven I/O and lightweight concurrency library for Ruby.
+It provides event-driven I/O using the [Reactor pattern](http://en.wikipedia.org/wiki/Reactor_pattern),
+much like [JBoss Netty](http://www.jboss.org/netty), [Apache MINA](http://mina.apache.org/),
+Python's [Twisted](http://twistedmatrix.com), [Node.js](http://nodejs.org), libevent and libev.
+
+EventMachine is designed to simultaneously meet two key needs:
+
+ * Extremely high scalability, performance and stability for the most demanding production environments.
+ * An API that eliminates the complexities of high-performance threaded network programming,
+ allowing engineers to concentrate on their application logic.
+
+This unique combination makes EventMachine a premier choice for designers of critical networked
+applications, including Web servers and proxies, email and IM production systems, authentication/authorization
+processors, and many more.
+
+EventMachine has been around since yearly 2000s and is a mature and battle tested library.
+
+
+## What EventMachine is good for? ##
+
+ * Scalable event-driven servers. Examples: [Thin](http://code.macournoyer.com/thin/) or [Goliath](https://github.com/postrank-labs/goliath/).
+ * Scalable asynchronous clients for various protocols, RESTful APIs and so on. Examples: [em-http-request](https://github.com/igrigorik/em-http-request) or [amqp gem](https://github.com/ruby-amqp/amqp).
+ * Efficient network proxies with custom logic. Examples: [Proxymachine](https://github.com/mojombo/proxymachine/).
+ * File and network monitoring tools. Examples: [eventmachine-tail](https://github.com/jordansissel/eventmachine-tail) and [logstash](https://github.com/logstash/logstash).
+
+
+
+## What platforms are supported by EventMachine? ##
+
+EventMachine supports Ruby 1.8.7, 1.9.2, REE, JRuby and **works well on Windows** as well
+as many operating systems from the Unix family (Linux, Mac OS X, BSD flavors).
+
+
+
+## Install the gem ##
+
+Install it with [RubyGems](https://rubygems.org/)
+
+ gem install eventmachine
+
+or add this to your Gemfile if you use [Bundler](http://gembundler.com/):
+
+ gem "eventmachine"
+
+
+
+## Getting started ##
+
+For an introduction to EventMachine, check out:
+
+ * [blog post about EventMachine by Ilya Grigorik](http://www.igvita.com/2008/05/27/ruby-eventmachine-the-speed-demon/).
+ * [EventMachine Introductions by Dan Sinclair](http://everburning.com/news/eventmachine-introductions/).
+
+
+### Server example: Echo server ###
+
+Here's a fully-functional echo server written with EventMachine:
+
+ require 'eventmachine'
+
+ module EchoServer
+ def post_init
+ puts "-- someone connected to the echo server!"
+ end
+
+ def receive_data data
+ send_data ">>>you sent: #{data}"
+ close_connection if data =~ /quit/i
+ end
+
+ def unbind
+ puts "-- someone disconnected from the echo server!"
+ end
+ end
+
+ # Note that this will block current thread.
+ EventMachine.run {
+ EventMachine.start_server "127.0.0.1", 8081, EchoServer
+ }
+
+
+## EventMachine documentation ##
+
+Currently we only have [reference documentation](http://eventmachine.rubyforge.org) and a [wiki](https://github.com/eventmachine/eventmachine/wiki).
+
+
+## Community and where to get help ##
+
+ * Join the [mailing list](http://groups.google.com/group/eventmachine) (Google Group)
+ * Join IRC channel #eventmachine on irc.freenode.net
+
+
+## License and copyright ##
+
+EventMachine is copyrighted free software made available under the terms
+of either the GPL or Ruby's License.
+
+Copyright: (C) 2006-07 by Francis Cianfrocca. All Rights Reserved.
+
+
+## Alternatives ##
+
+If you are unhappy with EventMachine and want to use Ruby, check out [Cool.io](http://coolio.github.com/).
+One caveat: by May 2011, it did not support JRuby and Windows.
View
@@ -4,8 +4,16 @@ import *Dir['tasks/*.rake']
GEMSPEC = eval(File.read(File.expand_path('../eventmachine.gemspec', __FILE__)))
+require 'yard'
require 'rake/clean'
task :clobber => :clean
desc "Build eventmachine, then run tests."
task :default => [:compile, :test]
+
+desc 'Generate documentation'
+YARD::Rake::YardocTask.new do |t|
+ t.files = ['lib/**/*.rb', '-', 'docs/*.md']
+ t.options = ['--main', 'README.md', '--no-private']
+ t.options = ['--exclude', 'lib/jeventmachine', '--exclude', 'lib/pr_eventmachine']
+end
@@ -0,0 +1,27 @@
+# EventMachine documentation guides #
+
+Welcome to the documentation guides for [EventMachine](http://github.com/eventmachine/eventmachine),
+a fast and simple event-processing library for Ruby programs (à la JBoss Netty, Twisted, Node.js
+and so on).
+
+## Guide list ##
+
+ * {file:docs/GettingStarted.md Getting started with EventMachine}
+ * {file:docs/EventDrivenServers.md Writing event-driven servers}
+ * {file:docs/EventDrivenClients.md Writing event-driven clients}
+ * {file:docs/ConnectionFailureAndRecovery.md Connection Failure and Recovery}
+ * {file:docs/TLS.md TLS (aka SSL)}
+ * {file:docs/Ecosystem.md EventMachine ecosystem}: Thin, Goliath, em-http-request, em-websockets, Proxymachine and beyond
+ * {file:docs/BlockingEventLoop.md On blocking the event loop: why it is harmful for performance and how to avoid it}
+ * {file:docs/LightweightConcurrency.md Lightweight concurrency with EventMachine}
+ * {file:docs/Deferrables.md Deferrables}
+ * {file:docs/ModernKernelInputOutputAPIs.md Brief introduction to epoll, kqueue, select}
+ * {file:docs/WorkingWithOtherIOSources.md Working with other IO sources such as the keyboard}
+
+
+## Tell us what you think! ##
+
+Please take a moment and tell us what you think about this guide on the [EventMachine mailing list](http://bit.ly/jW3cR3)
+or in the #eventmachine channel on irc.freenode.net: what was unclear? What wasn't covered?
+Maybe you don't like the guide style or the grammar and spelling are incorrect? Reader feedback is
+key to making documentation better.
Oops, something went wrong.

0 comments on commit 38705c4

Please sign in to comment.