eventmachine-eventmachine 0.12.3

Sign up to get free protection for your applications and to get access to all the features.
Files changed (121) hide show
  1. data/Rakefile +169 -0
  2. data/docs/COPYING +60 -0
  3. data/docs/ChangeLog +183 -0
  4. data/docs/DEFERRABLES +138 -0
  5. data/docs/EPOLL +141 -0
  6. data/docs/GNU +281 -0
  7. data/docs/INSTALL +15 -0
  8. data/docs/KEYBOARD +38 -0
  9. data/docs/LEGAL +25 -0
  10. data/docs/LIGHTWEIGHT_CONCURRENCY +72 -0
  11. data/docs/PURE_RUBY +77 -0
  12. data/docs/README +74 -0
  13. data/docs/RELEASE_NOTES +96 -0
  14. data/docs/SMTP +9 -0
  15. data/docs/SPAWNED_PROCESSES +93 -0
  16. data/docs/TODO +10 -0
  17. data/ext/binder.cpp +126 -0
  18. data/ext/binder.h +48 -0
  19. data/ext/cmain.cpp +530 -0
  20. data/ext/cplusplus.cpp +172 -0
  21. data/ext/ed.cpp +1473 -0
  22. data/ext/ed.h +361 -0
  23. data/ext/em.cpp +1895 -0
  24. data/ext/em.h +170 -0
  25. data/ext/emwin.cpp +300 -0
  26. data/ext/emwin.h +94 -0
  27. data/ext/epoll.cpp +26 -0
  28. data/ext/epoll.h +25 -0
  29. data/ext/eventmachine.h +90 -0
  30. data/ext/eventmachine_cpp.h +94 -0
  31. data/ext/extconf.rb +150 -0
  32. data/ext/files.cpp +94 -0
  33. data/ext/files.h +65 -0
  34. data/ext/kb.cpp +368 -0
  35. data/ext/page.cpp +107 -0
  36. data/ext/page.h +51 -0
  37. data/ext/pipe.cpp +327 -0
  38. data/ext/project.h +119 -0
  39. data/ext/rubymain.cpp +683 -0
  40. data/ext/sigs.cpp +89 -0
  41. data/ext/sigs.h +32 -0
  42. data/ext/ssl.cpp +408 -0
  43. data/ext/ssl.h +86 -0
  44. data/java/src/com/rubyeventmachine/Application.java +196 -0
  45. data/java/src/com/rubyeventmachine/Connection.java +74 -0
  46. data/java/src/com/rubyeventmachine/ConnectionFactory.java +37 -0
  47. data/java/src/com/rubyeventmachine/DefaultConnectionFactory.java +46 -0
  48. data/java/src/com/rubyeventmachine/EmReactor.java +408 -0
  49. data/java/src/com/rubyeventmachine/EmReactorException.java +40 -0
  50. data/java/src/com/rubyeventmachine/EventableChannel.java +57 -0
  51. data/java/src/com/rubyeventmachine/EventableDatagramChannel.java +171 -0
  52. data/java/src/com/rubyeventmachine/EventableSocketChannel.java +244 -0
  53. data/java/src/com/rubyeventmachine/PeriodicTimer.java +38 -0
  54. data/java/src/com/rubyeventmachine/Timer.java +54 -0
  55. data/java/src/com/rubyeventmachine/tests/ApplicationTest.java +108 -0
  56. data/java/src/com/rubyeventmachine/tests/ConnectTest.java +124 -0
  57. data/java/src/com/rubyeventmachine/tests/EMTest.java +80 -0
  58. data/java/src/com/rubyeventmachine/tests/TestDatagrams.java +53 -0
  59. data/java/src/com/rubyeventmachine/tests/TestServers.java +74 -0
  60. data/java/src/com/rubyeventmachine/tests/TestTimers.java +89 -0
  61. data/lib/em/deferrable.rb +208 -0
  62. data/lib/em/eventable.rb +39 -0
  63. data/lib/em/future.rb +62 -0
  64. data/lib/em/messages.rb +66 -0
  65. data/lib/em/processes.rb +68 -0
  66. data/lib/em/spawnable.rb +88 -0
  67. data/lib/em/streamer.rb +112 -0
  68. data/lib/eventmachine.rb +1763 -0
  69. data/lib/eventmachine_version.rb +31 -0
  70. data/lib/evma.rb +32 -0
  71. data/lib/evma/callback.rb +32 -0
  72. data/lib/evma/container.rb +75 -0
  73. data/lib/evma/factory.rb +77 -0
  74. data/lib/evma/protocol.rb +87 -0
  75. data/lib/evma/reactor.rb +48 -0
  76. data/lib/jeventmachine.rb +137 -0
  77. data/lib/pr_eventmachine.rb +1011 -0
  78. data/lib/protocols/buftok.rb +127 -0
  79. data/lib/protocols/header_and_content.rb +129 -0
  80. data/lib/protocols/httpcli2.rb +794 -0
  81. data/lib/protocols/httpclient.rb +270 -0
  82. data/lib/protocols/line_and_text.rb +122 -0
  83. data/lib/protocols/linetext2.rb +163 -0
  84. data/lib/protocols/postgres.rb +261 -0
  85. data/lib/protocols/saslauth.rb +179 -0
  86. data/lib/protocols/smtpclient.rb +308 -0
  87. data/lib/protocols/smtpserver.rb +556 -0
  88. data/lib/protocols/stomp.rb +130 -0
  89. data/lib/protocols/tcptest.rb +57 -0
  90. data/tasks/cpp.rake +77 -0
  91. data/tasks/project.rake +78 -0
  92. data/tasks/tests.rake +192 -0
  93. data/tests/test_attach.rb +66 -0
  94. data/tests/test_basic.rb +231 -0
  95. data/tests/test_defer.rb +47 -0
  96. data/tests/test_epoll.rb +161 -0
  97. data/tests/test_errors.rb +82 -0
  98. data/tests/test_eventables.rb +78 -0
  99. data/tests/test_exc.rb +58 -0
  100. data/tests/test_futures.rb +214 -0
  101. data/tests/test_hc.rb +218 -0
  102. data/tests/test_httpclient.rb +215 -0
  103. data/tests/test_httpclient2.rb +133 -0
  104. data/tests/test_kb.rb +61 -0
  105. data/tests/test_ltp.rb +192 -0
  106. data/tests/test_ltp2.rb +320 -0
  107. data/tests/test_next_tick.rb +102 -0
  108. data/tests/test_processes.rb +56 -0
  109. data/tests/test_pure.rb +129 -0
  110. data/tests/test_running.rb +47 -0
  111. data/tests/test_sasl.rb +74 -0
  112. data/tests/test_send_file.rb +245 -0
  113. data/tests/test_servers.rb +80 -0
  114. data/tests/test_smtpclient.rb +81 -0
  115. data/tests/test_smtpserver.rb +93 -0
  116. data/tests/test_spawn.rb +329 -0
  117. data/tests/test_ssl_args.rb +68 -0
  118. data/tests/test_timers.rb +146 -0
  119. data/tests/test_ud.rb +43 -0
  120. data/tests/testem.rb +31 -0
  121. metadata +197 -0
@@ -0,0 +1,66 @@
1
+ # $Id$
2
+ #
3
+ # Author:: Francis Cianfrocca (gmail: blackhedd)
4
+ # Homepage:: http://rubyeventmachine.com
5
+ # Date:: 16 Jul 2006
6
+ #
7
+ # See EventMachine and EventMachine::Connection for documentation and
8
+ # usage examples.
9
+ #
10
+ #----------------------------------------------------------------------------
11
+ #
12
+ # Copyright (C) 2006-07 by Francis Cianfrocca. All Rights Reserved.
13
+ # Gmail: blackhedd
14
+ #
15
+ # This program is free software; you can redistribute it and/or modify
16
+ # it under the terms of either: 1) the GNU General Public License
17
+ # as published by the Free Software Foundation; either version 2 of the
18
+ # License, or (at your option) any later version; or 2) Ruby's License.
19
+ #
20
+ # See the file COPYING for complete licensing information.
21
+ #
22
+ #---------------------------------------------------------------------------
23
+ #
24
+ #
25
+
26
+ =begin
27
+
28
+ Message Routing in EventMachine.
29
+
30
+ The goal here is to enable "routing points," objects that can send and receive
31
+ "messages," which are delimited streams of bytes. The boundaries of a message
32
+ are preserved as it passes through the reactor system.
33
+
34
+ There will be several module methods defined in EventMachine to create route-point
35
+ objects (which will probably have a base class of EventMachine::MessageRouter
36
+ until someone suggests a better name).
37
+
38
+ As with I/O objects, routing objects will receive events by having the router
39
+ core call methods on them. And of course user code can and will define handlers
40
+ to deal with events of interest.
41
+
42
+ The message router base class only really needs a receive_message method. There will
43
+ be an EM module-method to send messages, in addition to the module methods to create
44
+ the various kinds of message receivers.
45
+
46
+ The simplest kind of message receiver object can receive messages by being named
47
+ explicitly in a parameter to EM#send_message. More sophisticated receivers can define
48
+ pub-sub selectors and message-queue names. And they can also define channels for
49
+ route-points in other processes or even on other machines.
50
+
51
+ A message is NOT a marshallable entity. Rather, it's a chunk of flat content more like
52
+ an Erlang message. Initially, all content submitted for transmission as a message will
53
+ have the to_s method called on it. Eventually, we'll be able to transmit certain structured
54
+ data types (XML and YAML documents, Structs within limits) and have them reconstructed
55
+ on the other end.
56
+
57
+ A fundamental goal of the message-routing capability is to interoperate seamlessly with
58
+ external systems, including non-Ruby systems like ActiveMQ. We will define various protocol
59
+ handlers for things like Stomp and possibly AMQP, but these will be wrapped up and hidden
60
+ from the users of the basic routing capability.
61
+
62
+ As with Erlang, a critical goal is for programs that are built to use message-passing to work
63
+ WITHOUT CHANGE when the code is re-based on a multi-process system.
64
+
65
+ =end
66
+
@@ -0,0 +1,68 @@
1
+ # $Id$
2
+ #
3
+ # Author:: Francis Cianfrocca (gmail: blackhedd)
4
+ # Homepage:: http://rubyeventmachine.com
5
+ # Date:: 13 Dec 07
6
+ #
7
+ # See EventMachine and EventMachine::Connection for documentation and
8
+ # usage examples.
9
+ #
10
+ #----------------------------------------------------------------------------
11
+ #
12
+ # Copyright (C) 2006-08 by Francis Cianfrocca. All Rights Reserved.
13
+ # Gmail: blackhedd
14
+ #
15
+ # This program is free software; you can redistribute it and/or modify
16
+ # it under the terms of either: 1) the GNU General Public License
17
+ # as published by the Free Software Foundation; either version 2 of the
18
+ # License, or (at your option) any later version; or 2) Ruby's License.
19
+ #
20
+ # See the file COPYING for complete licensing information.
21
+ #
22
+ #---------------------------------------------------------------------------
23
+ #
24
+ #
25
+
26
+
27
+ module EventMachine
28
+
29
+ # EM::DeferrableChildProcess is a sugaring of a common use-case
30
+ # involving EM::popen.
31
+ # Call the #open method on EM::DeferrableChildProcess, passing
32
+ # a command-string. #open immediately returns an EM::Deferrable
33
+ # object. It also schedules the forking of a child process, which
34
+ # will execute the command passed to #open.
35
+ # When the forked child terminates, the Deferrable will be signalled
36
+ # and execute its callbacks, passing the data that the child process
37
+ # wrote to stdout.
38
+ #
39
+ class DeferrableChildProcess < EventMachine::Connection
40
+ include EventMachine::Deferrable
41
+
42
+ # Sugars a common use-case involving forked child processes.
43
+ # #open takes a String argument containing an shell command
44
+ # string (including arguments if desired). #open immediately
45
+ # returns an EventMachine::Deferrable object, without blocking.
46
+ #
47
+ # It also invokes EventMachine#popen to run the passed-in
48
+ # command in a forked child process.
49
+ #
50
+ # When the forked child terminates, the Deferrable that
51
+ # #open calls its callbacks, passing the data returned
52
+ # from the child process.
53
+ #
54
+ def self.open cmd
55
+ EventMachine.popen( cmd, DeferrableChildProcess )
56
+ end
57
+
58
+ def receive_data data
59
+ (@data ||= []) << data
60
+ end
61
+
62
+ def unbind
63
+ succeed( @data.join )
64
+ end
65
+ end
66
+ end
67
+
68
+
@@ -0,0 +1,88 @@
1
+ # $Id$
2
+ #
3
+ # Author:: Francis Cianfrocca (gmail: blackhedd)
4
+ # Homepage:: http://rubyeventmachine.com
5
+ # Date:: 25 Aug 2007
6
+ #
7
+ # See EventMachine and EventMachine::Connection for documentation and
8
+ # usage examples.
9
+ #
10
+ #----------------------------------------------------------------------------
11
+ #
12
+ # Copyright (C) 2006-07 by Francis Cianfrocca. All Rights Reserved.
13
+ # Gmail: blackhedd
14
+ #
15
+ # This program is free software; you can redistribute it and/or modify
16
+ # it under the terms of either: 1) the GNU General Public License
17
+ # as published by the Free Software Foundation; either version 2 of the
18
+ # License, or (at your option) any later version; or 2) Ruby's License.
19
+ #
20
+ # See the file COPYING for complete licensing information.
21
+ #
22
+ #---------------------------------------------------------------------------
23
+ #
24
+ #
25
+
26
+
27
+ # Support for Erlang-style processes.
28
+ #
29
+
30
+
31
+ module EventMachine
32
+ class SpawnedProcess
33
+ #attr_accessor :receiver
34
+ def notify *x
35
+ me = self
36
+ EM.next_tick {
37
+ # A notification executes in the context of this
38
+ # SpawnedProcess object. That makes self and notify
39
+ # work as one would expect.
40
+ #
41
+ y = me.call(*x)
42
+ if y and y.respond_to?(:pull_out_yield_block)
43
+ a,b = y.pull_out_yield_block
44
+ set_receiver a
45
+ self.notify if b
46
+ end
47
+ }
48
+ end
49
+ alias_method :resume, :notify
50
+ alias_method :run, :notify # for formulations like (EM.spawn {xxx}).run
51
+
52
+ # I know I'm missing something stupid, but the inside of class << s
53
+ # can't see locally-bound values. It can see globals, though.
54
+ def set_receiver blk
55
+ $em______tmpglobal = blk
56
+ class << self
57
+ define_method :call, $em______tmpglobal.dup
58
+ end
59
+ end
60
+
61
+ end
62
+
63
+ class YieldBlockFromSpawnedProcess
64
+ def initialize block, notify
65
+ @block = [block,notify]
66
+ end
67
+ def pull_out_yield_block
68
+ @block
69
+ end
70
+ end
71
+
72
+ def EventMachine.spawn &block
73
+ s = SpawnedProcess.new
74
+ s.set_receiver block
75
+ s
76
+ end
77
+
78
+ def EventMachine.yield &block
79
+ return YieldBlockFromSpawnedProcess.new( block, false )
80
+ end
81
+
82
+ def EventMachine.yield_and_notify &block
83
+ return YieldBlockFromSpawnedProcess.new( block, true )
84
+ end
85
+ end
86
+
87
+
88
+
@@ -0,0 +1,112 @@
1
+ # $Id$
2
+ #
3
+ # Author:: Francis Cianfrocca (gmail: blackhedd)
4
+ # Homepage:: http://rubyeventmachine.com
5
+ # Date:: 16 Jul 2006
6
+ #
7
+ # See EventMachine and EventMachine::Connection for documentation and
8
+ # usage examples.
9
+ #
10
+ #----------------------------------------------------------------------------
11
+ #
12
+ # Copyright (C) 2006-07 by Francis Cianfrocca. All Rights Reserved.
13
+ # Gmail: blackhedd
14
+ #
15
+ # This program is free software; you can redistribute it and/or modify
16
+ # it under the terms of either: 1) the GNU General Public License
17
+ # as published by the Free Software Foundation; either version 2 of the
18
+ # License, or (at your option) any later version; or 2) Ruby's License.
19
+ #
20
+ # See the file COPYING for complete licensing information.
21
+ #
22
+ #---------------------------------------------------------------------------
23
+ #
24
+ #
25
+
26
+
27
+ module EventMachine
28
+ class FileStreamer
29
+ MappingThreshold = 16384
30
+ BackpressureLevel = 50000
31
+ ChunkSize = 16384
32
+
33
+ include Deferrable
34
+ def initialize connection, filename, args
35
+ @connection = connection
36
+ @http_chunks = args[:http_chunks]
37
+
38
+ if File.exist?(filename)
39
+ @size = File.size?(filename)
40
+ if @size <= MappingThreshold
41
+ stream_without_mapping filename
42
+ else
43
+ stream_with_mapping filename
44
+ end
45
+ else
46
+ fail "file not found"
47
+ end
48
+ end
49
+
50
+ def stream_without_mapping filename
51
+ if @http_chunks
52
+ @connection.send_data "#{@size.to_s(16)}\r\n"
53
+ @connection.send_file_data filename
54
+ @connection.send_data "\r\n0\r\n\r\n"
55
+ else
56
+ @connection.send_file_data filename
57
+ end
58
+ succeed
59
+ end
60
+ private :stream_without_mapping
61
+
62
+ def stream_with_mapping filename
63
+ ensure_mapping_extension_is_present
64
+
65
+ @position = 0
66
+ @mapping = EventMachine::FastFileReader::Mapper.new filename
67
+ stream_one_chunk
68
+ end
69
+ private :stream_with_mapping
70
+
71
+ def stream_one_chunk
72
+ loop {
73
+ if @position < @size
74
+ if @connection.get_outbound_data_size > BackpressureLevel
75
+ EventMachine::next_tick {stream_one_chunk}
76
+ break
77
+ else
78
+ len = @size - @position
79
+ len = ChunkSize if (len > ChunkSize)
80
+
81
+ @connection.send_data( "#{len.to_s(16)}\r\n" ) if @http_chunks
82
+ @connection.send_data( @mapping.get_chunk( @position, len ))
83
+ @connection.send_data("\r\n") if @http_chunks
84
+
85
+ @position += len
86
+ end
87
+ else
88
+ @connection.send_data "0\r\n\r\n" if @http_chunks
89
+ @mapping.close
90
+ succeed
91
+ break
92
+ end
93
+ }
94
+ end
95
+
96
+ #--
97
+ # We use an outboard extension class to get memory-mapped files.
98
+ # It's outboard to avoid polluting the core distro, but that means
99
+ # there's a "hidden" dependency on it. The first time we get here in
100
+ # any run, try to load up the dependency extension. User code will see
101
+ # a LoadError if it's not available, but code that doesn't require
102
+ # mapped files will work fine without it. This is a somewhat difficult
103
+ # compromise between usability and proper modularization.
104
+ #
105
+ def ensure_mapping_extension_is_present
106
+ @@fastfilereader ||= (require 'fastfilereaderext')
107
+ end
108
+ private :ensure_mapping_extension_is_present
109
+
110
+ end
111
+ end
112
+
@@ -0,0 +1,1763 @@
1
+ # $Id$
2
+ #
3
+ # Author:: Francis Cianfrocca (gmail: blackhedd)
4
+ # Homepage:: http://rubyeventmachine.com
5
+ # Date:: 8 Apr 2006
6
+ #
7
+ # See EventMachine and EventMachine::Connection for documentation and
8
+ # usage examples.
9
+ #
10
+ #----------------------------------------------------------------------------
11
+ #
12
+ # Copyright (C) 2006-07 by Francis Cianfrocca. All Rights Reserved.
13
+ # Gmail: blackhedd
14
+ #
15
+ # This program is free software; you can redistribute it and/or modify
16
+ # it under the terms of either: 1) the GNU General Public License
17
+ # as published by the Free Software Foundation; either version 2 of the
18
+ # License, or (at your option) any later version; or 2) Ruby's License.
19
+ #
20
+ # See the file COPYING for complete licensing information.
21
+ #
22
+ #---------------------------------------------------------------------------
23
+ #
24
+ #
25
+
26
+
27
+ #-- Select in a library based on a global variable.
28
+ # PROVISIONALLY commented out this whole mechanism which selects
29
+ # a pure-Ruby EM implementation if the extension is not available.
30
+ # I expect this will cause a lot of people's code to break, as it
31
+ # exposes misconfigurations and path problems that were masked up
32
+ # till now. The reason I'm disabling it is because the pure-Ruby
33
+ # code will have problems of its own, and it's not nearly as fast
34
+ # anyway. Suggested by a problem report from Moshe Litvin. 05Jun07.
35
+ #
36
+ # 05Dec07: Re-enabled the pure-ruby mechanism, but without the automatic
37
+ # fallback feature that tripped up Moshe Litvin. We shouldn't fail over to
38
+ # the pure Ruby version because it's possible that the user intended to
39
+ # run the extension but failed to do so because of a compilation or
40
+ # similar error. So we require either a global variable or an environment
41
+ # string be set in order to select the pure-Ruby version.
42
+ #
43
+
44
+
45
+ unless defined?($eventmachine_library)
46
+ $eventmachine_library = ENV['EVENTMACHINE_LIBRARY'] || :cascade
47
+ end
48
+ $eventmachine_library = $eventmachine_library.to_sym
49
+
50
+ case $eventmachine_library
51
+ when :pure_ruby
52
+ require 'pr_eventmachine'
53
+ when :extension
54
+ require 'rubyeventmachine'
55
+ when :java
56
+ require 'jeventmachine'
57
+ else # :cascade
58
+ # This is the case that most user code will take.
59
+ # Prefer the extension if available.
60
+ begin
61
+ if RUBY_PLATFORM =~ /java/
62
+ require 'java'
63
+ require 'jeventmachine'
64
+ $eventmachine_library = :java
65
+ else
66
+ require 'rubyeventmachine'
67
+ $eventmachine_library = :extension
68
+ end
69
+ rescue LoadError
70
+ warn "# EventMachine fell back to pure ruby mode" if $DEBUG
71
+ require 'pr_eventmachine'
72
+ $eventmachine_library = :pure_ruby
73
+ end
74
+ end
75
+
76
+ require "eventmachine_version"
77
+ require 'em/deferrable'
78
+ require 'em/future'
79
+ require 'em/eventable'
80
+ require 'em/messages'
81
+ require 'em/streamer'
82
+ require 'em/spawnable'
83
+
84
+ require 'shellwords'
85
+
86
+ #-- Additional requires are at the BOTTOM of this file, because they
87
+ #-- depend on stuff defined in here. Refactor that someday.
88
+
89
+
90
+
91
+ # == Introduction
92
+ # EventMachine provides a fast, lightweight framework for implementing
93
+ # Ruby programs that can use the network to communicate with other
94
+ # processes. Using EventMachine, Ruby programmers can easily connect
95
+ # to remote servers and act as servers themselves. EventMachine does not
96
+ # supplant the Ruby IP libraries. It does provide an alternate technique
97
+ # for those applications requiring better performance, scalability,
98
+ # and discipline over the behavior of network sockets, than is easily
99
+ # obtainable using the built-in libraries, especially in applications
100
+ # which are structurally well-suited for the event-driven programming model.
101
+ #
102
+ # EventMachine provides a perpetual event-loop which your programs can
103
+ # start and stop. Within the event loop, TCP network connections are
104
+ # initiated and accepted, based on EventMachine methods called by your
105
+ # program. You also define callback methods which are called by EventMachine
106
+ # when events of interest occur within the event-loop.
107
+ #
108
+ # User programs will be called back when the following events occur:
109
+ # * When the event loop accepts network connections from remote peers
110
+ # * When data is received from network connections
111
+ # * When connections are closed, either by the local or the remote side
112
+ # * When user-defined timers expire
113
+ #
114
+ # == Usage example
115
+ #
116
+ # Here's a fully-functional echo server implemented in EventMachine:
117
+ #
118
+ # require 'rubygems'
119
+ # require 'eventmachine'
120
+ #
121
+ # module EchoServer
122
+ # def receive_data data
123
+ # send_data ">>>you sent: #{data}"
124
+ # close_connection if data =~ /quit/i
125
+ # end
126
+ # end
127
+ #
128
+ # EventMachine::run {
129
+ # EventMachine::start_server "192.168.0.100", 8081, EchoServer
130
+ # }
131
+ #
132
+ # What's going on here? Well, we have defined the module EchoServer to
133
+ # implement the semantics of the echo protocol (more about that shortly).
134
+ # The last three lines invoke the event-machine itself, which runs forever
135
+ # unless one of your callbacks terminates it. The block that you supply
136
+ # to EventMachine::run contains code that runs immediately after the event
137
+ # machine is initialized and before it starts looping. This is the place
138
+ # to open up a TCP server by specifying the address and port it will listen
139
+ # on, together with the module that will process the data.
140
+ #
141
+ # Our EchoServer is extremely simple as the echo protocol doesn't require
142
+ # much work. Basically you want to send back to the remote peer whatever
143
+ # data it sends you. We'll dress it up with a little extra text to make it
144
+ # interesting. Also, we'll close the connection in case the received data
145
+ # contains the word "quit."
146
+ #
147
+ # So what about this module EchoServer? Well, whenever a network connection
148
+ # (either a client or a server) starts up, EventMachine instantiates an anonymous
149
+ # class, that your module has been mixed into. Exactly one of these class
150
+ # instances is created for each connection. Whenever an event occurs on a
151
+ # given connection, its corresponding object automatically calls specific
152
+ # instance methods which your module may redefine. The code in your module
153
+ # always runs in the context of a class instance, so you can create instance
154
+ # variables as you wish and they will be carried over to other callbacks
155
+ # made on that same connection.
156
+ #
157
+ # Looking back up at EchoServer, you can see that we've defined the method
158
+ # receive_data which (big surprise) is called whenever data has been received
159
+ # from the remote end of the connection. Very simple. We get the data
160
+ # (a String object) and can do whatever we wish with it. In this case,
161
+ # we use the method send_data to return the received data to the caller,
162
+ # with some extra text added in. And if the user sends the word "quit,"
163
+ # we'll close the connection with (naturally) close_connection.
164
+ # (Notice that closing the connection doesn't terminate the processing loop,
165
+ # or change the fact that your echo server is still accepting connections!)
166
+ #
167
+ #
168
+ # == Questions and Futures
169
+ # Would it be useful for EventMachine to incorporate the Observer pattern
170
+ # and make use of the corresponding Ruby <tt>observer</tt> package?
171
+ # Interesting thought.
172
+ #
173
+ #
174
+ module EventMachine
175
+ class FileNotFoundException < Exception; end
176
+
177
+ class << self
178
+ attr_reader :threadpool
179
+ end
180
+
181
+
182
+ # EventMachine::run initializes and runs an event loop.
183
+ # This method only returns if user-callback code calls stop_event_loop.
184
+ # Use the supplied block to define your clients and servers.
185
+ # The block is called by EventMachine::run immediately after initializing
186
+ # its internal event loop but <i>before</i> running the loop.
187
+ # Therefore this block is the right place to call start_server if you
188
+ # want to accept connections from remote clients.
189
+ #
190
+ # For programs that are structured as servers, it's usually appropriate
191
+ # to start an event loop by calling EventMachine::run, and let it
192
+ # run forever. It's also possible to use EventMachine::run to make a single
193
+ # client-connection to a remote server, process the data flow from that
194
+ # single connection, and then call stop_event_loop to force EventMachine::run
195
+ # to return. Your program will then continue from the point immediately
196
+ # following the call to EventMachine::run.
197
+ #
198
+ # You can of course do both client and servers simultaneously in the same program.
199
+ # One of the strengths of the event-driven programming model is that the
200
+ # handling of network events on many different connections will be interleaved,
201
+ # and scheduled according to the actual events themselves. This maximizes
202
+ # efficiency.
203
+ #
204
+ # === Server usage example
205
+ #
206
+ # See the text at the top of this file for an example of an echo server.
207
+ #
208
+ # === Client usage example
209
+ #
210
+ # See the description of stop_event_loop for an extremely simple client example.
211
+ #
212
+ #--
213
+ # Obsoleted the use_threads mechanism.
214
+ # 25Nov06: Added the begin/ensure block. We need to be sure that release_machine
215
+ # gets called even if an exception gets thrown within any of the user code
216
+ # that the event loop runs. The best way to see this is to run a unit
217
+ # test with two functions, each of which calls EventMachine#run and each of
218
+ # which throws something inside of #run. Without the ensure, the second test
219
+ # will start without release_machine being called and will immediately throw
220
+ # a C++ runtime error.
221
+ #
222
+ def EventMachine::run blk=nil, tail=nil, &block
223
+ @tails ||= []
224
+ tail and @tails.unshift(tail)
225
+
226
+ if reactor_running?
227
+ (b = blk || block) and b.call # next_tick(b)
228
+ else
229
+ @conns = {}
230
+ @acceptors = {}
231
+ @timers = {}
232
+ @wrapped_exception = nil
233
+ begin
234
+ @reactor_running = true
235
+ initialize_event_machine
236
+ (b = blk || block) and add_timer(0, b)
237
+ run_machine
238
+ ensure
239
+ begin
240
+ release_machine
241
+ ensure
242
+ if @threadpool
243
+ @threadpool.each { |t| t.exit }
244
+ @threadpool.each { |t| t.kill! if t.alive? }
245
+ @threadqueue = nil
246
+ @resultqueue = nil
247
+ end
248
+ @threadpool = nil
249
+ end
250
+ @reactor_running = false
251
+ end
252
+
253
+ until @tails.empty?
254
+ @tails.pop.call
255
+ end
256
+
257
+ raise @wrapped_exception if @wrapped_exception
258
+ end
259
+ end
260
+
261
+
262
+ # Sugars a common use case. Will pass the given block to #run, but will terminate
263
+ # the reactor loop and exit the function as soon as the code in the block completes.
264
+ # (Normally, #run keeps running indefinitely, even after the block supplied to it
265
+ # finishes running, until user code calls #stop.)
266
+ #
267
+ def EventMachine::run_block &block
268
+ pr = proc {
269
+ block.call
270
+ EventMachine::stop
271
+ }
272
+ run(&pr)
273
+ end
274
+
275
+ # fork_reactor forks a new process and calls EM#run inside of it, passing your block.
276
+ #--
277
+ # This implementation is subject to change, especially if we clean up the relationship
278
+ # of EM#run to @reactor_running.
279
+ # Original patch by Aman Gupta.
280
+ #
281
+ def EventMachine::fork_reactor &block
282
+ Kernel.fork do
283
+ if self.reactor_running?
284
+ self.stop_event_loop
285
+ self.release_machine
286
+ self.instance_variable_set( '@reactor_running', false )
287
+ end
288
+ self.run block
289
+ end
290
+ end
291
+
292
+
293
+ # +deprecated+
294
+ #--
295
+ # EventMachine#run_without_threads is semantically identical
296
+ # to EventMachine#run, but it runs somewhat faster.
297
+ # However, it must not be used in applications that spin
298
+ # Ruby threads.
299
+ def EventMachine::run_without_threads &block
300
+ #EventMachine::run false, &block
301
+ EventMachine::run(&block)
302
+ end
303
+
304
+ # EventMachine#add_timer adds a one-shot timer to the event loop.
305
+ # Call it with one or two parameters. The first parameters is a delay-time
306
+ # expressed in <i>seconds</i> (not milliseconds). The second parameter, if
307
+ # present, must be a proc object. If a proc object is not given, then you
308
+ # can also simply pass a block to the method call.
309
+ #
310
+ # EventMachine#add_timer may be called from the block passed to EventMachine#run
311
+ # or from any callback method. It schedules execution of the proc or block
312
+ # passed to add_timer, after the passage of an interval of time equal to
313
+ # <i>at least</i> the number of seconds specified in the first parameter to
314
+ # the call.
315
+ #
316
+ # EventMachine#add_timer is a <i>non-blocking</i> call. Callbacks can and will
317
+ # be called during the interval of time that the timer is in effect.
318
+ # There is no built-in limit to the number of timers that can be outstanding at
319
+ # any given time.
320
+ #
321
+ # === Usage example
322
+ #
323
+ # This example shows how easy timers are to use. Observe that two timers are
324
+ # initiated simultaneously. Also, notice that the event loop will continue
325
+ # to run even after the second timer event is processed, since there was
326
+ # no call to EventMachine#stop_event_loop. There will be no activity, of
327
+ # course, since no network clients or servers are defined. Stop the program
328
+ # with Ctrl-C.
329
+ #
330
+ # require 'rubygems'
331
+ # require 'eventmachine'
332
+ #
333
+ # EventMachine::run {
334
+ # puts "Starting the run now: #{Time.now}"
335
+ # EventMachine::add_timer 5, proc { puts "Executing timer event: #{Time.now}" }
336
+ # EventMachine::add_timer( 10 ) { puts "Executing timer event: #{Time.now}" }
337
+ # }
338
+ #
339
+ #
340
+ #--
341
+ # Changed 04Oct06: We now pass the interval as an integer number of milliseconds.
342
+ #
343
+ def EventMachine::add_timer *args, &block
344
+ interval = args.shift
345
+ code = args.shift || block
346
+ if code
347
+ # check too many timers!
348
+ s = add_oneshot_timer((interval * 1000).to_i)
349
+ @timers[s] = code
350
+ s
351
+ end
352
+ end
353
+
354
+ # EventMachine#add_periodic_timer adds a periodic timer to the event loop.
355
+ # It takes the same parameters as the one-shot timer method, EventMachine#add_timer.
356
+ # This method schedules execution of the given block repeatedly, at intervals
357
+ # of time <i>at least</i> as great as the number of seconds given in the first
358
+ # parameter to the call.
359
+ #
360
+ # === Usage example
361
+ #
362
+ # The following sample program will write a dollar-sign to stderr every five seconds.
363
+ # (Of course if the program defined network clients and/or servers, they would
364
+ # be doing their work while the periodic timer is counting off.)
365
+ #
366
+ # EventMachine::run {
367
+ # EventMachine::add_periodic_timer( 5 ) { $stderr.write "$" }
368
+ # }
369
+ #
370
+ def EventMachine::add_periodic_timer *args, &block
371
+ interval = args.shift
372
+ code = args.shift || block
373
+ if code
374
+ block_1 = proc {
375
+ code.call
376
+ EventMachine::add_periodic_timer interval, code
377
+ }
378
+ add_timer interval, block_1
379
+ end
380
+ end
381
+
382
+ #--
383
+ #
384
+ def EventMachine::cancel_timer signature
385
+ @timers[signature] = proc{} if @timers.has_key?(signature)
386
+ end
387
+ private_class_method :cancel_timer
388
+
389
+
390
+ # stop_event_loop may called from within a callback method
391
+ # while EventMachine's processing loop is running.
392
+ # It causes the processing loop to stop executing, which
393
+ # will cause all open connections and accepting servers
394
+ # to be run down and closed. <i>Callbacks for connection-termination
395
+ # will be called</i> as part of the processing of stop_event_loop.
396
+ # (There currently is no option to panic-stop the loop without
397
+ # closing connections.) When all of this processing is complete,
398
+ # the call to EventMachine::run which started the processing loop
399
+ # will return and program flow will resume from the statement
400
+ # following EventMachine::run call.
401
+ #
402
+ # === Usage example
403
+ #
404
+ # require 'rubygems'
405
+ # require 'eventmachine'
406
+ #
407
+ # module Redmond
408
+ #
409
+ # def post_init
410
+ # puts "We're sending a dumb HTTP request to the remote peer."
411
+ # send_data "GET / HTTP/1.1\r\nHost: www.microsoft.com\r\n\r\n"
412
+ # end
413
+ #
414
+ # def receive_data data
415
+ # puts "We received #{data.length} bytes from the remote peer."
416
+ # puts "We're going to stop the event loop now."
417
+ # EventMachine::stop_event_loop
418
+ # end
419
+ #
420
+ # def unbind
421
+ # puts "A connection has terminated."
422
+ # end
423
+ #
424
+ # end
425
+ #
426
+ # puts "We're starting the event loop now."
427
+ # EventMachine::run {
428
+ # EventMachine::connect "www.microsoft.com", 80, Redmond
429
+ # }
430
+ # puts "The event loop has stopped."
431
+ #
432
+ # This program will produce approximately the following output:
433
+ #
434
+ # We're starting the event loop now.
435
+ # We're sending a dumb HTTP request to the remote peer.
436
+ # We received 1440 bytes from the remote peer.
437
+ # We're going to stop the event loop now.
438
+ # A connection has terminated.
439
+ # The event loop has stopped.
440
+ #
441
+ #
442
+ def EventMachine::stop_event_loop
443
+ EventMachine::stop
444
+ end
445
+
446
+ # EventMachine::start_server initiates a TCP server (socket
447
+ # acceptor) on the specified IP address and port.
448
+ # The IP address must be valid on the machine where the program
449
+ # runs, and the process must be privileged enough to listen
450
+ # on the specified port (on Unix-like systems, superuser privileges
451
+ # are usually required to listen on any port lower than 1024).
452
+ # Only one listener may be running on any given address/port
453
+ # combination. start_server will fail if the given address and port
454
+ # are already listening on the machine, either because of a prior call
455
+ # to start_server or some unrelated process running on the machine.
456
+ # If start_server succeeds, the new network listener becomes active
457
+ # immediately and starts accepting connections from remote peers,
458
+ # and these connections generate callback events that are processed
459
+ # by the code specified in the handler parameter to start_server.
460
+ #
461
+ # The optional handler which is passed to start_server is the key
462
+ # to EventMachine's ability to handle particular network protocols.
463
+ # The handler parameter passed to start_server must be a Ruby Module
464
+ # that you must define. When the network server that is started by
465
+ # start_server accepts a new connection, it instantiates a new
466
+ # object of an anonymous class that is inherited from EventMachine::Connection,
467
+ # <i>into which the methods from your handler have been mixed.</i>
468
+ # Your handler module may redefine any of the methods in EventMachine::Connection
469
+ # in order to implement the specific behavior of the network protocol.
470
+ #
471
+ # Callbacks invoked in response to network events <i>always</i> take place
472
+ # within the execution context of the object derived from EventMachine::Connection
473
+ # extended by your handler module. There is one object per connection, and
474
+ # all of the callbacks invoked for a particular connection take the form
475
+ # of instance methods called against the corresponding EventMachine::Connection
476
+ # object. Therefore, you are free to define whatever instance variables you
477
+ # wish, in order to contain the per-connection state required by the network protocol you are
478
+ # implementing.
479
+ #
480
+ # start_server is often called inside the block passed to EventMachine::run,
481
+ # but it can be called from any EventMachine callback. start_server will fail
482
+ # unless the EventMachine event loop is currently running (which is why
483
+ # it's often called in the block suppled to EventMachine::run).
484
+ #
485
+ # You may call start_server any number of times to start up network
486
+ # listeners on different address/port combinations. The servers will
487
+ # all run simultaneously. More interestingly, each individual call to start_server
488
+ # can specify a different handler module and thus implement a different
489
+ # network protocol from all the others.
490
+ #
491
+ # === Usage example
492
+ # Here is an example of a server that counts lines of input from the remote
493
+ # peer and sends back the total number of lines received, after each line.
494
+ # Try the example with more than one client connection opened via telnet,
495
+ # and you will see that the line count increments independently on each
496
+ # of the client connections. Also very important to note, is that the
497
+ # handler for the receive_data function, which our handler redefines, may
498
+ # not assume that the data it receives observes any kind of message boundaries.
499
+ # Also, to use this example, be sure to change the server and port parameters
500
+ # to the start_server call to values appropriate for your environment.
501
+ #
502
+ # require 'rubygems'
503
+ # require 'eventmachine'
504
+ #
505
+ # module LineCounter
506
+ #
507
+ # MaxLinesPerConnection = 10
508
+ #
509
+ # def post_init
510
+ # puts "Received a new connection"
511
+ # @data_received = ""
512
+ # @line_count = 0
513
+ # end
514
+ #
515
+ # def receive_data data
516
+ # @data_received << data
517
+ # while @data_received.slice!( /^[^\n]*[\n]/m )
518
+ # @line_count += 1
519
+ # send_data "received #{@line_count} lines so far\r\n"
520
+ # @line_count == MaxLinesPerConnection and close_connection_after_writing
521
+ # end
522
+ # end
523
+ #
524
+ # end # module LineCounter
525
+ #
526
+ # EventMachine::run {
527
+ # host,port = "192.168.0.100", 8090
528
+ # EventMachine::start_server host, port, LineCounter
529
+ # puts "Now accepting connections on address #{host}, port #{port}..."
530
+ # EventMachine::add_periodic_timer( 10 ) { $stderr.write "*" }
531
+ # }
532
+ #
533
+ #
534
+ def EventMachine::start_server server, port=nil, handler=nil, *args, &block
535
+
536
+ begin
537
+ port = Integer(port)
538
+ rescue ArgumentError, TypeError
539
+ args.unshift handler if handler
540
+ handler = port
541
+ port = nil
542
+ end if port
543
+
544
+ klass = if (handler and handler.is_a?(Class))
545
+ handler
546
+ else
547
+ Class.new( Connection ) {handler and include handler}
548
+ end
549
+
550
+ arity = klass.instance_method(:initialize).arity
551
+ expected = arity >= 0 ? arity : -(arity + 1)
552
+ if (arity >= 0 and args.size != expected) or (arity < 0 and args.size < expected)
553
+ raise ArgumentError, "wrong number of arguments for #{klass}#initialize (#{args.size} for #{expected})"
554
+ end
555
+
556
+ s = if port
557
+ start_tcp_server server, port
558
+ else
559
+ start_unix_server server
560
+ end
561
+ @acceptors[s] = [klass,args,block]
562
+ s
563
+ end
564
+
565
+
566
+ # Stop a TCP server socket that was started with EventMachine#start_server.
567
+ #--
568
+ # Requested by Kirk Haines. TODO, this isn't OOP enough. We ought somehow
569
+ # to have #start_server return an object that has a close or a stop method on it.
570
+ #
571
+ def EventMachine::stop_server signature
572
+ EventMachine::stop_tcp_server signature
573
+ end
574
+
575
+ def EventMachine::start_unix_domain_server filename, *args, &block
576
+ start_server filename, *args, &block
577
+ end
578
+
579
+ # EventMachine#connect initiates a TCP connection to a remote
580
+ # server and sets up event-handling for the connection.
581
+ # You can call EventMachine#connect in the block supplied
582
+ # to EventMachine#run or in any callback method.
583
+ #
584
+ # EventMachine#connect takes the IP address (or hostname) and
585
+ # port of the remote server you want to connect to.
586
+ # It also takes an optional handler Module which you must define, that
587
+ # contains the callbacks that will be invoked by the event loop
588
+ # on behalf of the connection.
589
+ #
590
+ # See the description of EventMachine#start_server for a discussion
591
+ # of the handler Module. All of the details given in that description
592
+ # apply for connections created with EventMachine#connect.
593
+ #
594
+ # === Usage Example
595
+ #
596
+ # Here's a program which connects to a web server, sends a naive
597
+ # request, parses the HTTP header of the response, and then
598
+ # (antisocially) ends the event loop, which automatically drops the connection
599
+ # (and incidentally calls the connection's unbind method).
600
+ #
601
+ # require 'rubygems'
602
+ # require 'eventmachine'
603
+ #
604
+ # module DumbHttpClient
605
+ #
606
+ # def post_init
607
+ # send_data "GET / HTTP/1.1\r\nHost: _\r\n\r\n"
608
+ # @data = ""
609
+ # end
610
+ #
611
+ # def receive_data data
612
+ # @data << data
613
+ # if @data =~ /[\n][\r]*[\n]/m
614
+ # puts "RECEIVED HTTP HEADER:"
615
+ # $`.each {|line| puts ">>> #{line}" }
616
+ #
617
+ # puts "Now we'll terminate the loop, which will also close the connection"
618
+ # EventMachine::stop_event_loop
619
+ # end
620
+ # end
621
+ #
622
+ # def unbind
623
+ # puts "A connection has terminated"
624
+ # end
625
+ #
626
+ # end # DumbHttpClient
627
+ #
628
+ #
629
+ # EventMachine::run {
630
+ # EventMachine::connect "www.bayshorenetworks.com", 80, DumbHttpClient
631
+ # }
632
+ # puts "The event loop has ended"
633
+ #
634
+ #
635
+ # There are times when it's more convenient to define a protocol handler
636
+ # as a Class rather than a Module. Here's how to do this:
637
+ #
638
+ # class MyProtocolHandler < EventMachine::Connection
639
+ # def initialize *args
640
+ # super
641
+ # # whatever else you want to do here
642
+ # end
643
+ #
644
+ # #.......your other class code
645
+ # end # class MyProtocolHandler
646
+ #
647
+ # If you do this, then an instance of your class will be instantiated to handle
648
+ # every network connection created by your code or accepted by servers that you
649
+ # create. If you redefine #post_init in your protocol-handler class, your
650
+ # #post_init method will be called _inside_ the call to #super that you will
651
+ # make in your #initialize method (if you provide one).
652
+ #
653
+ #--
654
+ # EventMachine::connect initiates a TCP connection to a remote
655
+ # server and sets up event-handling for the connection.
656
+ # It internally creates an object that should not be handled
657
+ # by the caller. HOWEVER, it's often convenient to get the
658
+ # object to set up interfacing to other objects in the system.
659
+ # We return the newly-created anonymous-class object to the caller.
660
+ # It's expected that a considerable amount of code will depend
661
+ # on this behavior, so don't change it.
662
+ #
663
+ # Ok, added support for a user-defined block, 13Apr06.
664
+ # This leads us to an interesting choice because of the
665
+ # presence of the post_init call, which happens in the
666
+ # initialize method of the new object. We call the user's
667
+ # block and pass the new object to it. This is a great
668
+ # way to do protocol-specific initiation. It happens
669
+ # AFTER post_init has been called on the object, which I
670
+ # certainly hope is the right choice.
671
+ # Don't change this lightly, because accepted connections
672
+ # are different from connected ones and we don't want
673
+ # to have them behave differently with respect to post_init
674
+ # if at all possible.
675
+ #
676
+ def EventMachine::connect server, port=nil, handler=nil, *args
677
+ begin
678
+ port = Integer(port)
679
+ rescue ArgumentError, TypeError
680
+ args.unshift handler if handler
681
+ handler = port
682
+ port = nil
683
+ end if port
684
+
685
+ klass = if (handler and handler.is_a?(Class))
686
+ handler
687
+ else
688
+ Class.new( Connection ) {handler and include handler}
689
+ end
690
+
691
+ arity = klass.instance_method(:initialize).arity
692
+ expected = arity >= 0 ? arity : -(arity + 1)
693
+ if (arity >= 0 and args.size != expected) or (arity < 0 and args.size < expected)
694
+ raise ArgumentError, "wrong number of arguments for #{klass}#initialize (#{args.size} for #{expected})"
695
+ end
696
+
697
+ s = if port
698
+ connect_server server, port
699
+ else
700
+ connect_unix_server server
701
+ end
702
+
703
+ c = klass.new s, *args
704
+ @conns[s] = c
705
+ block_given? and yield c
706
+ c
707
+ end
708
+
709
+ # EventMachine::attach registers a given file descriptor or IO object with the eventloop
710
+ #
711
+ # If the handler provided has the functions notify_readable or notify_writable defined,
712
+ # EventMachine will not read or write from the socket, and instead fire the corresponding
713
+ # callback on the handler.
714
+ #
715
+ # To detach the file descriptor, use EventMachine::Connection#detach
716
+ #
717
+ # === Usage Example
718
+ #
719
+ # module SimpleHttpClient
720
+ # def initialize sock
721
+ # @sock = sock
722
+ # end
723
+ #
724
+ # def notify_readable
725
+ # header = @sock.readline
726
+ #
727
+ # if header == "\r\n"
728
+ # # detach returns the file descriptor number (fd == @sock.fileno)
729
+ # fd = detach
730
+ # end
731
+ # rescue EOFError
732
+ # detach
733
+ # end
734
+ #
735
+ # def unbind
736
+ # EM.next_tick do
737
+ # # socket is detached from the eventloop, but still open
738
+ # data = @sock.read
739
+ # end
740
+ # end
741
+ # end
742
+ #
743
+ # EM.run{
744
+ # $sock = TCPSocket.new('site.com', 80)
745
+ # $sock.write("GET / HTTP/1.0\r\n\r\n")
746
+ # EM.attach $sock, SimpleHttpClient, $sock
747
+ # }
748
+ #
749
+ #--
750
+ # Thanks to Riham Aldakkak (eSpace Technologies) for the initial patch
751
+ def EventMachine::attach io, handler=nil, *args
752
+ klass = if (handler and handler.is_a?(Class))
753
+ handler
754
+ else
755
+ Class.new( Connection ) {handler and include handler}
756
+ end
757
+
758
+ arity = klass.instance_method(:initialize).arity
759
+ expected = arity >= 0 ? arity : -(arity + 1)
760
+ if (arity >= 0 and args.size != expected) or (arity < 0 and args.size < expected)
761
+ raise ArgumentError, "wrong number of arguments for #{klass}#initialize (#{args.size} for #{expected})"
762
+ end
763
+
764
+ readmode = klass.public_instance_methods.any?{|m| m.to_sym == :notify_readable }
765
+ writemode = klass.public_instance_methods.any?{|m| m.to_sym == :notify_writable }
766
+
767
+ s = attach_fd io.respond_to?(:fileno) ? io.fileno : io, readmode, writemode
768
+
769
+ c = klass.new s, *args
770
+ @conns[s] = c
771
+ block_given? and yield c
772
+ c
773
+ end
774
+
775
+ #--
776
+ # EXPERIMENTAL. DO NOT RELY ON THIS METHOD TO BE HERE IN THIS FORM, OR AT ALL.
777
+ # (03Nov06)
778
+ # Observe, the test for already-connected FAILS if we call a reconnect inside post_init,
779
+ # because we haven't set up the connection in @conns by that point.
780
+ # RESIST THE TEMPTATION to "fix" this problem by redefining the behavior of post_init.
781
+ #
782
+ # Changed 22Nov06: if called on an already-connected handler, just return the
783
+ # handler and do nothing more. Originally this condition raised an exception.
784
+ # We may want to change it yet again and call the block, if any.
785
+ #
786
+ def EventMachine::reconnect server, port, handler
787
+ raise "invalid handler" unless handler.respond_to?(:connection_completed)
788
+ #raise "still connected" if @conns.has_key?(handler.signature)
789
+ return handler if @conns.has_key?(handler.signature)
790
+ s = connect_server server, port
791
+ handler.signature = s
792
+ @conns[s] = handler
793
+ block_given? and yield handler
794
+ handler
795
+ end
796
+
797
+
798
+
799
+
800
+ # Make a connection to a Unix-domain socket. This is not implemented on Windows platforms.
801
+ # The parameter socketname is a String which identifies the Unix-domain socket you want
802
+ # to connect to. socketname is the name of a file on your local system, and in most cases
803
+ # is a fully-qualified path name. Make sure that your process has enough local permissions
804
+ # to open the Unix-domain socket.
805
+ # See also the documentation for #connect_server. This method behaves like #connect_server
806
+ # in all respects except for the fact that it connects to a local Unix-domain
807
+ # socket rather than a TCP socket.
808
+ # NOTE: this functionality will soon be subsumed into the #connect method. This method
809
+ # will still be supported as an alias.
810
+ #--
811
+ # For making connections to Unix-domain sockets.
812
+ # Eventually this has to get properly documented and unified with the TCP-connect methods.
813
+ # Note how nearly identical this is to EventMachine#connect
814
+ def EventMachine::connect_unix_domain socketname, *args, &blk
815
+ connect socketname, *args, &blk
816
+ end
817
+
818
+
819
+ # EventMachine#open_datagram_socket is for support of UDP-based
820
+ # protocols. Its usage is similar to that of EventMachine#start_server.
821
+ # It takes three parameters: an IP address (which must be valid
822
+ # on the machine which executes the method), a port number,
823
+ # and an optional Module name which will handle the data.
824
+ # This method will create a new UDP (datagram) socket and
825
+ # bind it to the address and port that you specify.
826
+ # The normal callbacks (see EventMachine#start_server) will
827
+ # be called as events of interest occur on the newly-created
828
+ # socket, but there are some differences in how they behave.
829
+ #
830
+ # Connection#receive_data will be called when a datagram packet
831
+ # is received on the socket, but unlike TCP sockets, the message
832
+ # boundaries of the received data will be respected. In other words,
833
+ # if the remote peer sent you a datagram of a particular size,
834
+ # you may rely on Connection#receive_data to give you the
835
+ # exact data in the packet, with the original data length.
836
+ # Also observe that Connection#receive_data may be called with a
837
+ # <i>zero-length</i> data payload, since empty datagrams are permitted
838
+ # in UDP.
839
+ #
840
+ # Connection#send_data is available with UDP packets as with TCP,
841
+ # but there is an important difference. Because UDP communications
842
+ # are <i>connectionless,</i> there is no implicit recipient for the packets you
843
+ # send. Ordinarily you must specify the recipient for each packet you send.
844
+ # However, EventMachine
845
+ # provides for the typical pattern of receiving a UDP datagram
846
+ # from a remote peer, performing some operation, and then sending
847
+ # one or more packets in response to the same remote peer.
848
+ # To support this model easily, just use Connection#send_data
849
+ # in the code that you supply for Connection:receive_data.
850
+ # EventMachine will
851
+ # provide an implicit return address for any messages sent to
852
+ # Connection#send_data within the context of a Connection#receive_data callback,
853
+ # and your response will automatically go to the correct remote peer.
854
+ # (TODO: Example-code needed!)
855
+ #
856
+ # Observe that the port number that you supply to EventMachine#open_datagram_socket
857
+ # may be zero. In this case, EventMachine will create a UDP socket
858
+ # that is bound to an <i>ephemeral</i> (not well-known) port.
859
+ # This is not appropriate for servers that must publish a well-known
860
+ # port to which remote peers may send datagrams. But it can be useful
861
+ # for clients that send datagrams to other servers.
862
+ # If you do this, you will receive any responses from the remote
863
+ # servers through the normal Connection#receive_data callback.
864
+ # Observe that you will probably have issues with firewalls blocking
865
+ # the ephemeral port numbers, so this technique is most appropriate for LANs.
866
+ # (TODO: Need an example!)
867
+ #
868
+ # If you wish to send datagrams to arbitrary remote peers (not
869
+ # necessarily ones that have sent data to which you are responding),
870
+ # then see Connection#send_datagram.
871
+ #
872
+ # DO NOT call send_data from a datagram socket
873
+ # outside of a #receive_data method. Use #send_datagram. If you do use #send_data
874
+ # outside of a #receive_data method, you'll get a confusing error
875
+ # because there is no "peer," as #send_data requires. (Inside of #receive_data,
876
+ # #send_data "fakes" the peer as described above.)
877
+ #
878
+ #--
879
+ # Replaced the implementation on 01Oct06. Thanks to Tobias Gustafsson for pointing
880
+ # out that this originally did not take a class but only a module.
881
+ #
882
+ def self::open_datagram_socket address, port, handler=nil, *args
883
+ klass = if (handler and handler.is_a?(Class))
884
+ handler
885
+ else
886
+ Class.new( Connection ) {handler and include handler}
887
+ end
888
+
889
+ arity = klass.instance_method(:initialize).arity
890
+ expected = arity >= 0 ? arity : -(arity + 1)
891
+ if (arity >= 0 and args.size != expected) or (arity < 0 and args.size < expected)
892
+ raise ArgumentError, "wrong number of arguments for #{klass}#initialize (#{args.size} for #{expected})"
893
+ end
894
+
895
+ s = open_udp_socket address, port
896
+ c = klass.new s, *args
897
+ @conns[s] = c
898
+ block_given? and yield c
899
+ c
900
+ end
901
+
902
+
903
+ # For advanced users. This function sets the default timer granularity, which by default is
904
+ # slightly smaller than 100 milliseconds. Call this function to set a higher or lower granularity.
905
+ # The function affects the behavior of #add_timer and #add_periodic_timer. Most applications
906
+ # will not need to call this function.
907
+ #
908
+ # The argument is a number of milliseconds. Avoid setting the quantum to very low values because
909
+ # that may reduce performance under some extreme conditions. We recommend that you not set a quantum
910
+ # lower than 10.
911
+ #
912
+ # You may only call this function while an EventMachine loop is running (that is, after a call to
913
+ # EventMachine#run and before a subsequent call to EventMachine#stop).
914
+ #
915
+ def self::set_quantum mills
916
+ set_timer_quantum mills.to_i
917
+ end
918
+
919
+ # Sets the maximum number of timers and periodic timers that may be outstanding at any
920
+ # given time. You only need to call #set_max_timers if you need more than the default
921
+ # number of timers, which on most platforms is 1000.
922
+ # Call this method before calling EventMachine#run.
923
+ #
924
+ def self::set_max_timers ct
925
+ set_max_timer_count ct
926
+ end
927
+
928
+ #--
929
+ # The is the responder for the loopback-signalled event.
930
+ # It can be fired either by code running on a separate thread (EM#defer) or on
931
+ # the main thread (EM#next_tick).
932
+ # It will often happen that a next_tick handler will reschedule itself. We
933
+ # consume a copy of the tick queue so that tick events scheduled by tick events
934
+ # have to wait for the next pass through the reactor core.
935
+ #
936
+ def self::run_deferred_callbacks # :nodoc:
937
+ until (@resultqueue ||= []).empty?
938
+ result,cback = @resultqueue.pop
939
+ cback.call result if cback
940
+ end
941
+
942
+ @next_tick_queue ||= []
943
+ if (l = @next_tick_queue.length) > 0
944
+ l.times {|i| @next_tick_queue[i].call}
945
+ @next_tick_queue.slice!( 0...l )
946
+ end
947
+
948
+ =begin
949
+ (@next_tick_queue ||= []).length.times {
950
+ cback=@next_tick_queue.pop and cback.call
951
+ }
952
+ =end
953
+ =begin
954
+ if (@next_tick_queue ||= []) and @next_tick_queue.length > 0
955
+ ary = @next_tick_queue.dup
956
+ @next_tick_queue.clear
957
+ until ary.empty?
958
+ cback=ary.pop and cback.call
959
+ end
960
+ end
961
+ =end
962
+ end
963
+
964
+
965
+ # #defer is for integrating blocking operations into EventMachine's control flow.
966
+ # Call #defer with one or two blocks, as shown below (the second block is <i>optional</i>):
967
+ #
968
+ # operation = proc {
969
+ # # perform a long-running operation here, such as a database query.
970
+ # "result" # as usual, the last expression evaluated in the block will be the return value.
971
+ # }
972
+ # callback = proc {|result|
973
+ # # do something with result here, such as send it back to a network client.
974
+ # }
975
+ #
976
+ # EventMachine.defer( operation, callback )
977
+ #
978
+ # The action of #defer is to take the block specified in the first parameter (the "operation")
979
+ # and schedule it for asynchronous execution on an internal thread pool maintained by EventMachine.
980
+ # When the operation completes, it will pass the result computed by the block (if any)
981
+ # back to the EventMachine reactor. Then, EventMachine calls the block specified in the
982
+ # second parameter to #defer (the "callback"), as part of its normal, synchronous
983
+ # event handling loop. The result computed by the operation block is passed as a parameter
984
+ # to the callback. You may omit the callback parameter if you don't need to execute any code
985
+ # after the operation completes.
986
+ #
987
+ # <i>Caveats:</i>
988
+ # Note carefully that the code in your deferred operation will be executed on a separate
989
+ # thread from the main EventMachine processing and all other Ruby threads that may exist in
990
+ # your program. Also, multiple deferred operations may be running at once! Therefore, you
991
+ # are responsible for ensuring that your operation code is threadsafe. [Need more explanation
992
+ # and examples.]
993
+ # Don't write a deferred operation that will block forever. If so, the current implementation will
994
+ # not detect the problem, and the thread will never be returned to the pool. EventMachine limits
995
+ # the number of threads in its pool, so if you do this enough times, your subsequent deferred
996
+ # operations won't get a chance to run. [We might put in a timer to detect this problem.]
997
+ #
998
+ #--
999
+ # OBSERVE that #next_tick hacks into this mechanism, so don't make any changes here
1000
+ # without syncing there.
1001
+ #
1002
+ # Running with $VERBOSE set to true gives a warning unless all ivars are defined when
1003
+ # they appear in rvalues. But we DON'T ever want to initialize @threadqueue unless we
1004
+ # need it, because the Ruby threads are so heavyweight. We end up with this bizarre
1005
+ # way of initializing @threadqueue because EventMachine is a Module, not a Class, and
1006
+ # has no constructor.
1007
+ #
1008
+ def self::defer op = nil, callback = nil, &blk
1009
+ unless @threadpool
1010
+ require 'thread'
1011
+ @threadpool = []
1012
+ @threadqueue = Queue.new
1013
+ @resultqueue = Queue.new
1014
+ spawn_threadpool
1015
+ end
1016
+
1017
+ @threadqueue << [op||blk,callback]
1018
+ end
1019
+
1020
+ def self.spawn_threadpool
1021
+ until @threadpool.size == 20
1022
+ thread = Thread.new do
1023
+ while true
1024
+ op, cback = *@threadqueue.pop
1025
+ result = op.call
1026
+ @resultqueue << [result, cback]
1027
+ EventMachine.signal_loopbreak
1028
+ end
1029
+ end
1030
+ @threadpool << thread
1031
+ end
1032
+ end
1033
+
1034
+
1035
+ # Schedules a proc for execution immediately after the next "turn" through the reactor
1036
+ # core. An advanced technique, this can be useful for improving memory management and/or
1037
+ # application responsiveness, especially when scheduling large amounts of data for
1038
+ # writing to a network connection. TODO, we need a FAQ entry on this subject.
1039
+ #
1040
+ # #next_tick takes either a single argument (which must be a Proc) or a block.
1041
+ # And I'm taking suggestions for a better name for this method.
1042
+ #--
1043
+ # This works by adding to the @resultqueue that's used for #defer.
1044
+ # The general idea is that next_tick is used when we want to give the reactor a chance
1045
+ # to let other operations run, either to balance the load out more evenly, or to let
1046
+ # outbound network buffers drain, or both. So we probably do NOT want to block, and
1047
+ # we probably do NOT want to be spinning any threads. A program that uses next_tick
1048
+ # but not #defer shouldn't suffer the penalty of having Ruby threads running. They're
1049
+ # extremely expensive even if they're just sleeping.
1050
+ #
1051
+ def self::next_tick pr=nil, &block
1052
+ raise "no argument or block given" unless ((pr && pr.respond_to?(:call)) or block)
1053
+ (@next_tick_queue ||= []) << ( pr || block )
1054
+ EventMachine.signal_loopbreak
1055
+ =begin
1056
+ (@next_tick_procs ||= []) << (pr || block)
1057
+ if @next_tick_procs.length == 1
1058
+ add_timer(0) {
1059
+ @next_tick_procs.each {|t| t.call}
1060
+ @next_tick_procs.clear
1061
+ }
1062
+ end
1063
+ =end
1064
+ end
1065
+
1066
+ # A wrapper over the setuid system call. Particularly useful when opening a network
1067
+ # server on a privileged port because you can use this call to drop privileges
1068
+ # after opening the port. Also very useful after a call to #set_descriptor_table_size,
1069
+ # which generally requires that you start your process with root privileges.
1070
+ #
1071
+ # This method has no effective implementation on Windows or in the pure-Ruby
1072
+ # implementation of EventMachine.
1073
+ # Call #set_effective_user by passing it a string containing the effective name
1074
+ # of the user whose privilege-level your process should attain.
1075
+ # This method is intended for use in enforcing security requirements, consequently
1076
+ # it will throw a fatal error and end your program if it fails.
1077
+ #
1078
+ def self::set_effective_user username
1079
+ EventMachine::setuid_string username
1080
+ end
1081
+
1082
+
1083
+ # Sets the maximum number of file or socket descriptors that your process may open.
1084
+ # You can pass this method an integer specifying the new size of the descriptor table.
1085
+ # Returns the new descriptor-table size, which may be less than the number you
1086
+ # requested. If you call this method with no arguments, it will simply return
1087
+ # the current size of the descriptor table without attempting to change it.
1088
+ #
1089
+ # The new limit on open descriptors ONLY applies to sockets and other descriptors
1090
+ # that belong to EventMachine. It has NO EFFECT on the number of descriptors
1091
+ # you can create in ordinary Ruby code.
1092
+ #
1093
+ # Not available on all platforms. Increasing the number of descriptors beyond its
1094
+ # default limit usually requires superuser privileges. (See #set_effective_user
1095
+ # for a way to drop superuser privileges while your program is running.)
1096
+ #
1097
+ def self::set_descriptor_table_size n_descriptors=nil
1098
+ EventMachine::set_rlimit_nofile n_descriptors
1099
+ end
1100
+
1101
+
1102
+
1103
+ # TODO, must document popen. At this moment, it's only available on Unix.
1104
+ # This limitation is expected to go away.
1105
+ #--
1106
+ # Perhaps misnamed since the underlying function uses socketpair and is full-duplex.
1107
+ #
1108
+ def self::popen cmd, handler=nil
1109
+ klass = if (handler and handler.is_a?(Class))
1110
+ handler
1111
+ else
1112
+ Class.new( Connection ) {handler and include handler}
1113
+ end
1114
+
1115
+ w = Shellwords::shellwords( cmd )
1116
+ w.unshift( w.first ) if w.first
1117
+ s = invoke_popen( w )
1118
+ c = klass.new s
1119
+ @conns[s] = c
1120
+ yield(c) if block_given?
1121
+ c
1122
+ end
1123
+
1124
+
1125
+ # Tells you whether the EventMachine reactor loop is currently running. Returns true or
1126
+ # false. Useful when writing libraries that want to run event-driven code, but may
1127
+ # be running in programs that are already event-driven. In such cases, if EventMachine#reactor_running?
1128
+ # returns false, your code can invoke EventMachine#run and run your application code inside
1129
+ # the block passed to that method. If EventMachine#reactor_running? returns true, just
1130
+ # execute your event-aware code.
1131
+ #
1132
+ # This method is necessary because calling EventMachine#run inside of another call to
1133
+ # EventMachine#run generates a fatal error.
1134
+ #
1135
+ def self::reactor_running?
1136
+ (@reactor_running || false)
1137
+ end
1138
+
1139
+
1140
+ # (Experimental)
1141
+ #
1142
+ #
1143
+ def EventMachine::open_keyboard handler=nil, *args
1144
+ klass = if (handler and handler.is_a?(Class))
1145
+ handler
1146
+ else
1147
+ Class.new( Connection ) {handler and include handler}
1148
+ end
1149
+
1150
+ arity = klass.instance_method(:initialize).arity
1151
+ expected = arity >= 0 ? arity : -(arity + 1)
1152
+ if (arity >= 0 and args.size != expected) or (arity < 0 and args.size < expected)
1153
+ raise ArgumentError, "wrong number of arguments for #{klass}#initialize (#{args.size} for #{expected})"
1154
+ end
1155
+
1156
+ s = read_keyboard
1157
+ c = klass.new s, *args
1158
+ @conns[s] = c
1159
+ block_given? and yield c
1160
+ c
1161
+ end
1162
+
1163
+
1164
+
1165
+ private
1166
+ def EventMachine::event_callback conn_binding, opcode, data
1167
+ #
1168
+ # Changed 27Dec07: Eliminated the hookable error handling.
1169
+ # No one was using it, and it degraded performance significantly.
1170
+ # It's in original_event_callback, which is dead code.
1171
+ #
1172
+ # Changed 25Jul08: Added a partial solution to the problem of exceptions
1173
+ # raised in user-written event-handlers. If such exceptions are not caught,
1174
+ # we must cause the reactor to stop, and then re-raise the exception.
1175
+ # Otherwise, the reactor doesn't stop and it's left on the call stack.
1176
+ # This is partial because we only added it to #unbind, where it's critical
1177
+ # (to keep unbind handlers from being re-entered when a stopping reactor
1178
+ # runs down open connections). It should go on the other calls to user
1179
+ # code, but the performance impact may be too large.
1180
+ #
1181
+ if opcode == ConnectionData
1182
+ c = @conns[conn_binding] or raise ConnectionNotBound, "received data #{data} for unknown signature: #{conn_binding}"
1183
+ c.receive_data data
1184
+ elsif opcode == ConnectionUnbound
1185
+ if c = @conns.delete( conn_binding )
1186
+ begin
1187
+ c.unbind
1188
+ rescue
1189
+ @wrapped_exception = $!
1190
+ stop
1191
+ end
1192
+ elsif c = @acceptors.delete( conn_binding )
1193
+ # no-op
1194
+ else
1195
+ raise ConnectionNotBound, "recieved ConnectionUnbound for an unknown signature: #{conn_binding}"
1196
+ end
1197
+ elsif opcode == ConnectionAccepted
1198
+ accep,args,blk = @acceptors[conn_binding]
1199
+ raise NoHandlerForAcceptedConnection unless accep
1200
+ c = accep.new data, *args
1201
+ @conns[data] = c
1202
+ blk and blk.call(c)
1203
+ c # (needed?)
1204
+ elsif opcode == TimerFired
1205
+ t = @timers.delete( data ) or raise UnknownTimerFired, "timer data: #{data}"
1206
+ t.call
1207
+ elsif opcode == ConnectionCompleted
1208
+ c = @conns[conn_binding] or raise ConnectionNotBound, "received ConnectionCompleted for unknown signature: #{conn_binding}"
1209
+ c.connection_completed
1210
+ elsif opcode == LoopbreakSignalled
1211
+ run_deferred_callbacks
1212
+ elsif opcode == ConnectionNotifyReadable
1213
+ c = @conns[conn_binding] or raise ConnectionNotBound
1214
+ c.notify_readable
1215
+ elsif opcode == ConnectionNotifyWritable
1216
+ c = @conns[conn_binding] or raise ConnectionNotBound
1217
+ c.notify_writable
1218
+ end
1219
+ end
1220
+
1221
+ private
1222
+ def EventMachine::original_event_callback conn_binding, opcode, data
1223
+ #
1224
+ # Added 03Oct07: Any code path that invokes user-written code must
1225
+ # wrap itself in a begin/rescue for RuntimeErrors, that calls the
1226
+ # user-overridable class method #handle_runtime_error.
1227
+ #
1228
+ if opcode == ConnectionData
1229
+ c = @conns[conn_binding] or raise ConnectionNotBound
1230
+ begin
1231
+ c.receive_data data
1232
+ rescue
1233
+ EventMachine.handle_runtime_error
1234
+ end
1235
+ elsif opcode == ConnectionUnbound
1236
+ if c = @conns.delete( conn_binding )
1237
+ begin
1238
+ c.unbind
1239
+ rescue
1240
+ EventMachine.handle_runtime_error
1241
+ end
1242
+ elsif c = @acceptors.delete( conn_binding )
1243
+ # no-op
1244
+ else
1245
+ raise ConnectionNotBound
1246
+ end
1247
+ elsif opcode == ConnectionAccepted
1248
+ accep,args,blk = @acceptors[conn_binding]
1249
+ raise NoHandlerForAcceptedConnection unless accep
1250
+ c = accep.new data, *args
1251
+ @conns[data] = c
1252
+ begin
1253
+ blk and blk.call(c)
1254
+ rescue
1255
+ EventMachine.handle_runtime_error
1256
+ end
1257
+ c # (needed?)
1258
+ elsif opcode == TimerFired
1259
+ t = @timers.delete( data ) or raise UnknownTimerFired
1260
+ begin
1261
+ t.call
1262
+ rescue
1263
+ EventMachine.handle_runtime_error
1264
+ end
1265
+ elsif opcode == ConnectionCompleted
1266
+ c = @conns[conn_binding] or raise ConnectionNotBound
1267
+ begin
1268
+ c.connection_completed
1269
+ rescue
1270
+ EventMachine.handle_runtime_error
1271
+ end
1272
+ elsif opcode == LoopbreakSignalled
1273
+ begin
1274
+ run_deferred_callbacks
1275
+ rescue
1276
+ EventMachine.handle_runtime_error
1277
+ end
1278
+ end
1279
+ end
1280
+
1281
+
1282
+ # Default handler for RuntimeErrors that are raised in user code.
1283
+ # The default behavior is to re-raise the error, which ends your program.
1284
+ # To override the default behavior, re-implement this method in your code.
1285
+ # For example:
1286
+ #
1287
+ # module EventMachine
1288
+ # def self.handle_runtime_error
1289
+ # $>.puts $!
1290
+ # end
1291
+ # end
1292
+ #
1293
+ #--
1294
+ # We need to ensure that any code path which invokes user code rescues RuntimeError
1295
+ # and calls this method. The obvious place to do that is in #event_callback,
1296
+ # but, scurrilously, it turns out that we need to be finer grained that that.
1297
+ # Periodic timers, in particular, wrap their invocations of user code inside
1298
+ # procs that do other stuff we can't not do, like schedule the next invocation.
1299
+ # This is a potential non-robustness, since we need to remember to hook in the
1300
+ # error handler whenever and wherever we change how user code is invoked.
1301
+ #
1302
+ def EventMachine::handle_runtime_error
1303
+ @runtime_error_hook ? @runtime_error_hook.call : raise
1304
+ end
1305
+
1306
+ # Sets a handler for RuntimeErrors that are raised in user code.
1307
+ # Pass a block with no parameters. You can also call this method without a block,
1308
+ # which restores the default behavior (see #handle_runtime_error).
1309
+ #
1310
+ def EventMachine::set_runtime_error_hook &blk
1311
+ @runtime_error_hook = blk
1312
+ end
1313
+
1314
+ # Documentation stub
1315
+ #--
1316
+ # This is a provisional implementation of a stream-oriented file access object.
1317
+ # We also experiment with wrapping up some better exception reporting.
1318
+ class << self
1319
+ def _open_file_for_writing filename, handler=nil
1320
+ klass = if (handler and handler.is_a?(Class))
1321
+ handler
1322
+ else
1323
+ Class.new( Connection ) {handler and include handler}
1324
+ end
1325
+
1326
+ s = _write_file filename
1327
+ c = klass.new s
1328
+ @conns[s] = c
1329
+ block_given? and yield c
1330
+ c
1331
+ end
1332
+ end
1333
+
1334
+
1335
+ # EventMachine::Connection is a class that is instantiated
1336
+ # by EventMachine's processing loop whenever a new connection
1337
+ # is created. (New connections can be either initiated locally
1338
+ # to a remote server or accepted locally from a remote client.)
1339
+ # When a Connection object is instantiated, it <i>mixes in</i>
1340
+ # the functionality contained in the user-defined module
1341
+ # specified in calls to EventMachine#connect or EventMachine#start_server.
1342
+ # User-defined handler modules may redefine any or all of the standard
1343
+ # methods defined here, as well as add arbitrary additional code
1344
+ # that will also be mixed in.
1345
+ #
1346
+ # EventMachine manages one object inherited from EventMachine::Connection
1347
+ # (and containing the mixed-in user code) for every network connection
1348
+ # that is active at any given time.
1349
+ # The event loop will automatically call methods on EventMachine::Connection
1350
+ # objects whenever specific events occur on the corresponding connections,
1351
+ # as described below.
1352
+ #
1353
+ # This class is never instantiated by user code, and does not publish an
1354
+ # initialize method. The instance methods of EventMachine::Connection
1355
+ # which may be called by the event loop are: post_init, receive_data,
1356
+ # and unbind. All of the other instance methods defined here are called
1357
+ # only by user code.
1358
+ #
1359
+ class Connection
1360
+ # EXPERIMENTAL. Added the reconnect methods, which may go away.
1361
+ attr_accessor :signature
1362
+
1363
+ # Override .new so subclasses don't have to call super and can ignore
1364
+ # connection-specific arguments
1365
+ #
1366
+ def self.new(sig, *args) #:nodoc:
1367
+ allocate.instance_eval do
1368
+ # Call a superclass's #initialize if it has one
1369
+ initialize(*args)
1370
+
1371
+ # Store signature and run #post_init
1372
+ @signature = sig
1373
+ associate_callback_target sig
1374
+ post_init
1375
+
1376
+ self
1377
+ end
1378
+ end
1379
+
1380
+ # Stubbed initialize so legacy superclasses can safely call super
1381
+ #
1382
+ def initialize(*args) #:nodoc:
1383
+ end
1384
+
1385
+ # EventMachine::Connection#post_init is called by the event loop
1386
+ # immediately after the network connection has been established,
1387
+ # and before resumption of the network loop.
1388
+ # This method is generally not called by user code, but is called automatically
1389
+ # by the event loop. The base-class implementation is a no-op.
1390
+ # This is a very good place to initialize instance variables that will
1391
+ # be used throughout the lifetime of the network connection.
1392
+ #
1393
+ def post_init
1394
+ end
1395
+
1396
+ # EventMachine::Connection#receive_data is called by the event loop
1397
+ # whenever data has been received by the network connection.
1398
+ # It is never called by user code.
1399
+ # receive_data is called with a single parameter, a String containing
1400
+ # the network protocol data, which may of course be binary. You will
1401
+ # generally redefine this method to perform your own processing of the incoming data.
1402
+ #
1403
+ # Here's a key point which is essential to understanding the event-driven
1404
+ # programming model: <i>EventMachine knows absolutely nothing about the protocol
1405
+ # which your code implements.</i> You must not make any assumptions about
1406
+ # the size of the incoming data packets, or about their alignment on any
1407
+ # particular intra-message or PDU boundaries (such as line breaks).
1408
+ # receive_data can and will send you arbitrary chunks of data, with the
1409
+ # only guarantee being that the data is presented to your code in the order
1410
+ # it was collected from the network. Don't even assume that the chunks of
1411
+ # data will correspond to network packets, as EventMachine can and will coalesce
1412
+ # several incoming packets into one, to improve performance. The implication for your
1413
+ # code is that you generally will need to implement some kind of a state machine
1414
+ # in your redefined implementation of receive_data. For a better understanding
1415
+ # of this, read through the examples of specific protocol handlers given
1416
+ # elsewhere in this package. (STUB, WE MUST ADD THESE!)
1417
+ #
1418
+ # The base-class implementation of receive_data (which will be invoked if
1419
+ # you don't redefine it) simply prints the size of each incoming data packet
1420
+ # to stdout.
1421
+ #
1422
+ def receive_data data
1423
+ puts "............>>>#{data.length}"
1424
+ end
1425
+
1426
+ # EventMachine::Connection#unbind is called by the framework whenever a connection
1427
+ # (either a server or client connection) is closed. The close can occur because
1428
+ # your code intentionally closes it (see close_connection and close_connection_after_writing),
1429
+ # because the remote peer closed the connection, or because of a network error.
1430
+ # You may not assume that the network connection is still open and able to send or
1431
+ # receive data when the callback to unbind is made. This is intended only to give
1432
+ # you a chance to clean up associations your code may have made to the connection
1433
+ # object while it was open.
1434
+ #
1435
+ def unbind
1436
+ end
1437
+
1438
+ # EventMachine::Connection#close_connection is called only by user code, and never
1439
+ # by the event loop. You may call this method against a connection object in any
1440
+ # callback handler, whether or not the callback was made against the connection
1441
+ # you want to close. close_connection <i>schedules</i> the connection to be closed
1442
+ # at the next available opportunity within the event loop. You may not assume that
1443
+ # the connection is closed when close_connection returns. In particular, the framework
1444
+ # will callback the unbind method for the particular connection at a point shortly
1445
+ # after you call close_connection. You may assume that the unbind callback will
1446
+ # take place sometime after your call to close_connection completes. In other words,
1447
+ # the unbind callback will not re-enter your code "inside" of your call to close_connection.
1448
+ # However, it's not guaranteed that a future version of EventMachine will not change
1449
+ # this behavior.
1450
+ #
1451
+ # close_connection will <i>silently discard</i> any outbound data which you have
1452
+ # sent to the connection using EventMachine::Connection#send_data but which has not
1453
+ # yet been sent across the network. If you want to avoid this behavior, use
1454
+ # EventMachine::Connection#close_connection_after_writing.
1455
+ #
1456
+ def close_connection after_writing = false
1457
+ EventMachine::close_connection @signature, after_writing
1458
+ end
1459
+
1460
+ # EventMachine::Connection#detach will remove the given connection from the event loop.
1461
+ # The connection's socket remains open and its file descriptor number is returned
1462
+ def detach
1463
+ EventMachine::detach_fd @signature
1464
+ end
1465
+
1466
+ # EventMachine::Connection#close_connection_after_writing is a variant of close_connection.
1467
+ # All of the descriptive comments given for close_connection also apply to
1468
+ # close_connection_after_writing, <i>with one exception:</i> If the connection has
1469
+ # outbound data sent using send_dat but which has not yet been sent across the network,
1470
+ # close_connection_after_writing will schedule the connection to be closed <i>after</i>
1471
+ # all of the outbound data has been safely written to the remote peer.
1472
+ #
1473
+ # Depending on the amount of outgoing data and the speed of the network,
1474
+ # considerable time may elapse between your call to close_connection_after_writing
1475
+ # and the actual closing of the socket (at which time the unbind callback will be called
1476
+ # by the event loop). During this time, you <i>may not</i> call send_data to transmit
1477
+ # additional data (that is, the connection is closed for further writes). In very
1478
+ # rare cases, you may experience a receive_data callback after your call to close_connection_after_writing,
1479
+ # depending on whether incoming data was in the process of being received on the connection
1480
+ # at the moment when you called close_connection_after_writing. Your protocol handler must
1481
+ # be prepared to properly deal with such data (probably by ignoring it).
1482
+ #
1483
+ def close_connection_after_writing
1484
+ close_connection true
1485
+ end
1486
+
1487
+ # EventMachine::Connection#send_data is only called by user code, never by
1488
+ # the event loop. You call this method to send data to the remote end of the
1489
+ # network connection. send_data is called with a single String argument, which
1490
+ # may of course contain binary data. You can call send_data any number of times.
1491
+ # send_data is an instance method of an object derived from EventMachine::Connection
1492
+ # and containing your mixed-in handler code), so if you call it without qualification
1493
+ # within a callback function, the data will be sent to the same network connection
1494
+ # that generated the callback. Calling self.send_data is exactly equivalent.
1495
+ #
1496
+ # You can also call send_data to write to a connection <i>other than the one
1497
+ # whose callback you are calling send_data from.</i> This is done by recording
1498
+ # the value of the connection in any callback function (the value self), in any
1499
+ # variable visible to other callback invocations on the same or different
1500
+ # connection objects. (Need an example to make that clear.)
1501
+ #
1502
+ def send_data data
1503
+ EventMachine::send_data @signature, data, data.length
1504
+ end
1505
+
1506
+ # Returns true if the connection is in an error state, false otherwise.
1507
+ # In general, you can detect the occurrence of communication errors or unexpected
1508
+ # disconnection by the remote peer by handing the #unbind method. In some cases, however,
1509
+ # it's useful to check the status of the connection using #error? before attempting to send data.
1510
+ # This function is synchronous: it will return immediately without blocking.
1511
+ #
1512
+ #
1513
+ def error?
1514
+ EventMachine::report_connection_error_status(@signature) != 0
1515
+ end
1516
+
1517
+ # #connection_completed is called by the event loop when a remote TCP connection
1518
+ # attempt completes successfully. You can expect to get this notification after calls
1519
+ # to EventMachine#connect. Remember that EventMachine makes remote connections
1520
+ # asynchronously, just as with any other kind of network event. #connection_completed
1521
+ # is intended primarily to assist with network diagnostics. For normal protocol
1522
+ # handling, use #post_init to perform initial work on a new connection (such as
1523
+ # send an initial set of data).
1524
+ # #post_init will always be called. #connection_completed will only be called in case
1525
+ # of a successful completion. A connection-attempt which fails will receive a call
1526
+ # to #unbind after the failure.
1527
+ def connection_completed
1528
+ end
1529
+
1530
+ # Call #start_tls at any point to initiate TLS encryption on connected streams.
1531
+ # The method is smart enough to know whether it should perform a server-side
1532
+ # or a client-side handshake. An appropriate place to call #start_tls is in
1533
+ # your redefined #post_init method, or in the #connection_completed handler for
1534
+ # an outbound connection.
1535
+ #
1536
+ # #start_tls takes an optional parameter hash that allows you to specify certificate
1537
+ # and other options to be used with this Connection object. Here are the currently-supported
1538
+ # options:
1539
+ # :cert_chain_file : takes a String, which is interpreted as the name of a readable file in the
1540
+ # local filesystem. The file is expected to contain a chain of X509 certificates in
1541
+ # PEM format, with the most-resolved certificate at the top of the file, successive
1542
+ # intermediate certs in the middle, and the root (or CA) cert at the bottom.
1543
+ #
1544
+ # :private_key_file : tales a String, which is interpreted as the name of a readable file in the
1545
+ # local filesystem. The file must contain a private key in PEM format.
1546
+ #
1547
+ #--
1548
+ # TODO: support passing an encryption parameter, which can be string or Proc, to get a passphrase
1549
+ # for encrypted private keys.
1550
+ # TODO: support passing key material via raw strings or Procs that return strings instead of
1551
+ # just filenames.
1552
+ # What will get nasty is whether we have to define a location for storing this stuff as files.
1553
+ # In general, the OpenSSL interfaces for dealing with certs and keys in files are much better
1554
+ # behaved than the ones for raw chunks of memory.
1555
+ #
1556
+ def start_tls args={}
1557
+ priv_key, cert_chain = args.values_at(:private_key_file, :cert_chain_file)
1558
+
1559
+ [priv_key, cert_chain].each do |file|
1560
+ next if file.nil? or file.empty?
1561
+ raise FileNotFoundException,
1562
+ "Could not find #{file} for start_tls" unless File.exists? file
1563
+ end
1564
+
1565
+ EventMachine::set_tls_parms(@signature, priv_key || '', cert_chain || '')
1566
+
1567
+ EventMachine::start_tls @signature
1568
+ end
1569
+
1570
+
1571
+ # send_datagram is for sending UDP messages.
1572
+ # This method may be called from any Connection object that refers
1573
+ # to an open datagram socket (see EventMachine#open_datagram_socket).
1574
+ # The method sends a UDP (datagram) packet containing the data you specify,
1575
+ # to a remote peer specified by the IP address and port that you give
1576
+ # as parameters to the method.
1577
+ # Observe that you may send a zero-length packet (empty string).
1578
+ # However, you may not send an arbitrarily-large data packet because
1579
+ # your operating system will enforce a platform-specific limit on
1580
+ # the size of the outbound packet. (Your kernel
1581
+ # will respond in a platform-specific way if you send an overlarge
1582
+ # packet: some will send a truncated packet, some will complain, and
1583
+ # some will silently drop your request).
1584
+ # On LANs, it's usually OK to send datagrams up to about 4000 bytes in length,
1585
+ # but to be really safe, send messages smaller than the Ethernet-packet
1586
+ # size (typically about 1400 bytes). Some very restrictive WANs
1587
+ # will either drop or truncate packets larger than about 500 bytes.
1588
+ #--
1589
+ # Added the Integer wrapper around the port parameter per suggestion by
1590
+ # Matthieu Riou, after he passed a String and spent hours tearing his hair out.
1591
+ #
1592
+ def send_datagram data, recipient_address, recipient_port
1593
+ data = data.to_s
1594
+ EventMachine::send_datagram @signature, data, data.length, recipient_address, Integer(recipient_port)
1595
+ end
1596
+
1597
+
1598
+ # #get_peername is used with stream-connections to obtain the identity
1599
+ # of the remotely-connected peer. If a peername is available, this method
1600
+ # returns a sockaddr structure. The method returns nil if no peername is available.
1601
+ # You can use Socket#unpack_sockaddr_in and its variants to obtain the
1602
+ # values contained in the peername structure returned from #get_peername.
1603
+ def get_peername
1604
+ EventMachine::get_peername @signature
1605
+ end
1606
+
1607
+ # #get_sockname is used with stream-connections to obtain the identity
1608
+ # of the local side of the connection. If a local name is available, this method
1609
+ # returns a sockaddr structure. The method returns nil if no local name is available.
1610
+ # You can use Socket#unpack_sockaddr_in and its variants to obtain the
1611
+ # values contained in the local-name structure returned from #get_sockname.
1612
+ def get_sockname
1613
+ EventMachine::get_sockname @signature
1614
+ end
1615
+
1616
+ # Returns the PID (kernel process identifier) of a subprocess
1617
+ # associated with this Connection object. For use with EventMachine#popen
1618
+ # and similar methods. Returns nil when there is no meaningful subprocess.
1619
+ #--
1620
+ #
1621
+ def get_pid
1622
+ EventMachine::get_subprocess_pid @signature
1623
+ end
1624
+
1625
+ # Returns a subprocess exit status. Only useful for #popen. Call it in your
1626
+ # #unbind handler.
1627
+ #
1628
+ def get_status
1629
+ EventMachine::get_subprocess_status @signature
1630
+ end
1631
+
1632
+ # comm_inactivity_timeout returns the current value (in seconds) of the inactivity-timeout
1633
+ # property of network-connection and datagram-socket objects. A nonzero value
1634
+ # indicates that the connection or socket will automatically be closed if no read or write
1635
+ # activity takes place for at least that number of seconds.
1636
+ # A zero value (the default) specifies that no automatic timeout will take place.
1637
+ def comm_inactivity_timeout
1638
+ EventMachine::get_comm_inactivity_timeout @signature
1639
+ end
1640
+
1641
+ # Alias for #set_comm_inactivity_timeout.
1642
+ def comm_inactivity_timeout= value
1643
+ self.send :set_comm_inactivity_timeout, value
1644
+ end
1645
+
1646
+ # comm_inactivity_timeout= allows you to set the inactivity-timeout property for
1647
+ # a network connection or datagram socket. Specify a non-negative numeric value in seconds.
1648
+ # If the value is greater than zero, the connection or socket will automatically be closed
1649
+ # if no read or write activity takes place for at least that number of seconds.
1650
+ # Specify a value of zero to indicate that no automatic timeout should take place.
1651
+ # Zero is the default value.
1652
+ def set_comm_inactivity_timeout value
1653
+ EventMachine::set_comm_inactivity_timeout @signature, value
1654
+ end
1655
+
1656
+ #--
1657
+ # EXPERIMENTAL. DO NOT RELY ON THIS METHOD TO REMAIN SUPPORTED.
1658
+ # (03Nov06)
1659
+ def reconnect server, port
1660
+ EventMachine::reconnect server, port, self
1661
+ end
1662
+
1663
+
1664
+ # Like EventMachine::Connection#send_data, this sends data to the remote end of
1665
+ # the network connection. EventMachine::Connection@send_file_data takes a
1666
+ # filename as an argument, though, and sends the contents of the file, in one
1667
+ # chunk. Contributed by Kirk Haines.
1668
+ #
1669
+ def send_file_data filename
1670
+ EventMachine::send_file_data @signature, filename
1671
+ end
1672
+
1673
+ # Open a file on the filesystem and send it to the remote peer. This returns an
1674
+ # object of type EventMachine::Deferrable. The object's callbacks will be executed
1675
+ # on the reactor main thread when the file has been completely scheduled for
1676
+ # transmission to the remote peer. Its errbacks will be called in case of an error
1677
+ # (such as file-not-found). #stream_file_data employs various strategems to achieve
1678
+ # the fastest possible performance, balanced against minimum consumption of memory.
1679
+ #
1680
+ # You can control the behavior of #stream_file_data with the optional arguments parameter.
1681
+ # Currently-supported arguments are:
1682
+ # :http_chunks, a boolean flag which defaults false. If true, this flag streams the
1683
+ # file data in a format compatible with the HTTP chunked-transfer encoding.
1684
+ #
1685
+ # Warning: this feature has an implicit dependency on an outboard extension,
1686
+ # evma_fastfilereader. You must install this extension in order to use #stream_file_data
1687
+ # with files larger than a certain size (currently 8192 bytes).
1688
+ #
1689
+ def stream_file_data filename, args={}
1690
+ EventMachine::FileStreamer.new( self, filename, args )
1691
+ end
1692
+
1693
+
1694
+ # TODO, document this
1695
+ #
1696
+ #
1697
+ class EventMachine::PeriodicTimer
1698
+ attr_accessor :interval
1699
+ def initialize *args, &block
1700
+ @interval = args.shift
1701
+ @code = args.shift || block
1702
+ schedule
1703
+ end
1704
+ def schedule
1705
+ EventMachine::add_timer @interval, proc {self.fire}
1706
+ end
1707
+ def fire
1708
+ unless @cancelled
1709
+ @code.call
1710
+ schedule
1711
+ end
1712
+ end
1713
+ def cancel
1714
+ @cancelled = true
1715
+ end
1716
+ end
1717
+
1718
+ # TODO, document this
1719
+ #
1720
+ #
1721
+ class EventMachine::Timer
1722
+ def initialize *args, &block
1723
+ @signature = EventMachine::add_timer(*args, &block)
1724
+ end
1725
+ def cancel
1726
+ EventMachine.send :cancel_timer, @signature
1727
+ end
1728
+ end
1729
+
1730
+ end
1731
+
1732
+ # Is inside of protocols/ but not in the namespace?
1733
+ require 'protocols/buftok'
1734
+
1735
+ module Protocols
1736
+ # In this module, we define standard protocol implementations.
1737
+ # They get included from separate source files.
1738
+
1739
+ # TODO / XXX: We're munging the LOAD_PATH!
1740
+ # A good citizen would use eventmachine/protocols/tcptest.
1741
+ # TODO : various autotools are completely useless with the lack of naming
1742
+ # convention, we need to correct that!
1743
+ autoload :TcpConnectTester, 'protocols/tcptest'
1744
+ autoload :HttpClient, 'protocols/httpclient'
1745
+ autoload :LineAndTextProtocol, 'protocols/line_and_text'
1746
+ autoload :HeaderAndContentProtocol, 'protocols/header_and_content'
1747
+ autoload :LineText2, 'protocols/linetext2'
1748
+ autoload :HttpClient2, 'protocols/httpcli2'
1749
+ autoload :Stomp, 'protocols/stomp'
1750
+ autoload :SmtpClient, 'protocols/smtpclient'
1751
+ autoload :SmtpServer, 'protocols/smtpserver'
1752
+ autoload :SASLauth, 'protocols/saslauth'
1753
+
1754
+ #require 'protocols/postgres' UNCOMMENT THIS LINE WHEN THE POSTGRES CODE IS READY FOR PRIME TIME.
1755
+ end
1756
+
1757
+ end # module EventMachine
1758
+
1759
+ # Save everyone some typing.
1760
+ EM = EventMachine
1761
+ EM::P = EventMachine::Protocols
1762
+
1763
+ require 'em/processes'