eventmachine 1.0.0.beta.3 → 1.0.0.beta.4

Sign up to get free protection for your applications and to get access to all the features.
Files changed (96) hide show
  1. data/.gitignore +5 -0
  2. data/.yardopts +5 -1
  3. data/{docs/GNU → GNU} +0 -0
  4. data/Gemfile +1 -0
  5. data/{docs/COPYING → LICENSE} +0 -0
  6. data/README.md +109 -0
  7. data/Rakefile +8 -0
  8. data/docs/DocumentationGuidesIndex.md +27 -0
  9. data/docs/GettingStarted.md +521 -0
  10. data/docs/{ChangeLog → old/ChangeLog} +0 -0
  11. data/docs/{DEFERRABLES → old/DEFERRABLES} +0 -0
  12. data/docs/{EPOLL → old/EPOLL} +0 -0
  13. data/docs/{INSTALL → old/INSTALL} +0 -0
  14. data/docs/{KEYBOARD → old/KEYBOARD} +0 -0
  15. data/docs/{LEGAL → old/LEGAL} +0 -0
  16. data/docs/{LIGHTWEIGHT_CONCURRENCY → old/LIGHTWEIGHT_CONCURRENCY} +0 -0
  17. data/docs/{PURE_RUBY → old/PURE_RUBY} +0 -0
  18. data/docs/{RELEASE_NOTES → old/RELEASE_NOTES} +0 -0
  19. data/docs/{SMTP → old/SMTP} +0 -0
  20. data/docs/{SPAWNED_PROCESSES → old/SPAWNED_PROCESSES} +0 -0
  21. data/docs/{TODO → old/TODO} +0 -0
  22. data/eventmachine.gemspec +4 -1
  23. data/examples/guides/getting_started/01_eventmachine_echo_server.rb +18 -0
  24. data/examples/guides/getting_started/02_eventmachine_echo_server_that_recognizes_exit_command.rb +22 -0
  25. data/examples/guides/getting_started/03_simple_chat_server.rb +149 -0
  26. data/examples/guides/getting_started/04_simple_chat_server_step_one.rb +27 -0
  27. data/examples/guides/getting_started/05_simple_chat_server_step_two.rb +43 -0
  28. data/examples/guides/getting_started/06_simple_chat_server_step_three.rb +98 -0
  29. data/examples/guides/getting_started/07_simple_chat_server_step_four.rb +121 -0
  30. data/examples/guides/getting_started/08_simple_chat_server_step_five.rb +141 -0
  31. data/examples/{ex_channel.rb → old/ex_channel.rb} +3 -3
  32. data/examples/{ex_queue.rb → old/ex_queue.rb} +0 -0
  33. data/examples/{ex_tick_loop_array.rb → old/ex_tick_loop_array.rb} +0 -0
  34. data/examples/{ex_tick_loop_counter.rb → old/ex_tick_loop_counter.rb} +0 -0
  35. data/examples/{helper.rb → old/helper.rb} +0 -0
  36. data/ext/cmain.cpp +3 -3
  37. data/ext/ed.cpp +90 -15
  38. data/ext/ed.h +5 -5
  39. data/ext/em.cpp +47 -55
  40. data/ext/em.h +12 -2
  41. data/ext/pipe.cpp +2 -2
  42. data/ext/project.h +1 -1
  43. data/ext/rubymain.cpp +48 -3
  44. data/ext/ssl.cpp +5 -0
  45. data/java/src/com/rubyeventmachine/EmReactor.java +2 -2
  46. data/lib/em/buftok.rb +35 -63
  47. data/lib/em/callback.rb +43 -11
  48. data/lib/em/channel.rb +21 -14
  49. data/lib/em/completion.rb +304 -0
  50. data/lib/em/connection.rb +339 -209
  51. data/lib/em/deferrable.rb +4 -0
  52. data/lib/em/deferrable/pool.rb +2 -0
  53. data/lib/em/file_watch.rb +37 -18
  54. data/lib/em/iterator.rb +42 -42
  55. data/lib/em/pool.rb +146 -0
  56. data/lib/em/process_watch.rb +5 -4
  57. data/lib/em/processes.rb +8 -4
  58. data/lib/em/protocols/httpclient.rb +22 -11
  59. data/lib/em/protocols/httpclient2.rb +15 -5
  60. data/lib/em/protocols/line_protocol.rb +2 -1
  61. data/lib/em/protocols/memcache.rb +17 -9
  62. data/lib/em/protocols/object_protocol.rb +2 -1
  63. data/lib/em/protocols/postgres3.rb +8 -9
  64. data/lib/em/protocols/smtpclient.rb +19 -11
  65. data/lib/em/protocols/smtpserver.rb +1 -1
  66. data/lib/em/protocols/stomp.rb +8 -6
  67. data/lib/em/protocols/tcptest.rb +3 -2
  68. data/lib/em/pure_ruby.rb +212 -208
  69. data/lib/em/queue.rb +22 -13
  70. data/lib/em/resolver.rb +70 -64
  71. data/lib/em/spawnable.rb +6 -3
  72. data/lib/em/streamer.rb +33 -45
  73. data/lib/em/threaded_resource.rb +90 -0
  74. data/lib/em/timers.rb +6 -2
  75. data/lib/em/version.rb +1 -1
  76. data/lib/eventmachine.rb +538 -602
  77. data/lib/jeventmachine.rb +22 -1
  78. data/tasks/package.rake +12 -2
  79. data/tasks/test.rake +1 -0
  80. data/tests/em_test_helper.rb +12 -3
  81. data/tests/test_completion.rb +177 -0
  82. data/tests/test_epoll.rb +2 -2
  83. data/tests/test_httpclient.rb +9 -9
  84. data/tests/test_httpclient2.rb +11 -9
  85. data/tests/test_ltp.rb +2 -10
  86. data/tests/test_pool.rb +128 -0
  87. data/tests/test_processes.rb +20 -2
  88. data/tests/test_queue.rb +8 -0
  89. data/tests/test_resolver.rb +1 -1
  90. data/tests/test_set_sock_opt.rb +37 -0
  91. data/tests/test_shutdown_hooks.rb +23 -0
  92. data/tests/test_threaded_resource.rb +53 -0
  93. data/tests/test_unbind_reason.rb +31 -0
  94. metadata +262 -192
  95. data/README +0 -81
  96. data/tasks/doc.rake +0 -30
@@ -0,0 +1,304 @@
1
+ # = EM::Completion
2
+ #
3
+ # A completion is a callback container for various states of completion. In
4
+ # it's most basic form it has a start state and a finish state.
5
+ #
6
+ # This implementation includes some hold-back from the EM::Deferrable
7
+ # interface in order to be compatible - but it has a much cleaner
8
+ # implementation.
9
+ #
10
+ # In general it is preferred that this implementation be used as a state
11
+ # callback container than EM::DefaultDeferrable or other classes including
12
+ # EM::Deferrable. This is because it is generally more sane to keep this level
13
+ # of state in a dedicated state-back container. This generally leads to more
14
+ # malleable interfaces and software designs, as well as eradicating nasty bugs
15
+ # that result from abstraction leakage.
16
+ #
17
+ # == Basic Usage
18
+ #
19
+ # As already mentioned, the basic usage of a Completion is simply for its two
20
+ # final states, :succeeded and :failed.
21
+ #
22
+ # An asynchronous operation will complete at some future point in time, and
23
+ # users often want to react to this event. API authors will want to expose
24
+ # some common interface to react to these events.
25
+ #
26
+ # In the following example, the user wants to know when a short lived
27
+ # connection has completed its exchange with the remote server. The simple
28
+ # protocol just waits for an ack to its message.
29
+ #
30
+ # class Protocol < EM::Connection
31
+ # include EM::P::LineText2
32
+ #
33
+ # def initialize(message, completion)
34
+ # @message, @completion = message, completion
35
+ # @completion.completion { close_connection }
36
+ # @completion.timeout(1, :timeout)
37
+ # end
38
+ #
39
+ # def post_init
40
+ # send_data(@message)
41
+ # end
42
+ #
43
+ # def receive_line(line)
44
+ # case line
45
+ # when /ACK/i
46
+ # @completion.succeed line
47
+ # when /ERR/i
48
+ # @completion.fail :error, line
49
+ # else
50
+ # @completion.fail :unknown, line
51
+ # end
52
+ # end
53
+ #
54
+ # def unbind
55
+ # @completion.fail :disconnected unless @completion.completed?
56
+ # end
57
+ # end
58
+ #
59
+ # class API
60
+ # attr_reader :host, :port
61
+ #
62
+ # def initialize(host = 'example.org', port = 8000)
63
+ # @host, @port = host, port
64
+ # end
65
+ #
66
+ # def request(message)
67
+ # completion = EM::Deferrable::Completion.new
68
+ # EM.connect(host, port, Protocol, message, completion)
69
+ # completion
70
+ # end
71
+ # end
72
+ #
73
+ # api = API.new
74
+ # completion = api.request('stuff')
75
+ # completion.callback do |line|
76
+ # puts "API responded with: #{line}"
77
+ # end
78
+ # completion.errback do |type, line|
79
+ # case type
80
+ # when :error
81
+ # puts "API error: #{line}"
82
+ # when :unknown
83
+ # puts "API returned unknown response: #{line}"
84
+ # when :disconnected
85
+ # puts "API server disconnected prematurely"
86
+ # when :timeout
87
+ # puts "API server did not respond in a timely fashion"
88
+ # end
89
+ # end
90
+ #
91
+ # == Advanced Usage
92
+ #
93
+ # This completion implementation also supports more state callbacks and
94
+ # arbitrary states (unlike the original Deferrable API). This allows for basic
95
+ # stateful process encapsulation. One might use this to setup state callbacks
96
+ # for various states in an exchange like in the basic usage example, except
97
+ # where the applicaiton could be made to react to "connected" and
98
+ # "disconnected" states additionally.
99
+ #
100
+ # class Protocol < EM::Connection
101
+ # def initialize(completion)
102
+ # @response = []
103
+ # @completion = completion
104
+ # @completion.stateback(:disconnected) do
105
+ # @completion.succeed @response.join
106
+ # end
107
+ # end
108
+ #
109
+ # def connection_completed
110
+ # @host, @port = Socket.unpack_sockaddr_in get_peername
111
+ # @completion.change_state(:connected, @host, @port)
112
+ # send_data("GET http://example.org/ HTTP/1.0\r\n\r\n")
113
+ # end
114
+ #
115
+ # def receive_data(data)
116
+ # @response << data
117
+ # end
118
+ #
119
+ # def unbind
120
+ # @completion.change_state(:disconnected, @host, @port)
121
+ # end
122
+ # end
123
+ #
124
+ # completion = EM::Deferrable::Completion.new
125
+ # completion.stateback(:connected) do |host, port|
126
+ # puts "Connected to #{host}:#{port}"
127
+ # end
128
+ # completion.stateback(:disconnected) do |host, port|
129
+ # puts "Disconnected from #{host}:#{port}"
130
+ # end
131
+ # completion.callback do |response|
132
+ # puts response
133
+ # end
134
+ #
135
+ # EM.connect('example.org', 80, Protocol, completion)
136
+ #
137
+ # == Timeout
138
+ #
139
+ # The Completion also has a timeout. The timeout is global and is not aware of
140
+ # states apart from completion states. The timeout is only engaged if #timeout
141
+ # is called, and it will call fail if it is reached.
142
+ #
143
+ # == Completion states
144
+ #
145
+ # By default there are two completion states, :succeeded and :failed. These
146
+ # states can be modified by subclassing and overrding the #completion_states
147
+ # method. Completion states are special, in that callbacks for all completion
148
+ # states are explcitly cleared when a completion state is entered. This
149
+ # prevents errors that could arise from accidental unterminated timeouts, and
150
+ # other such user errors.
151
+ #
152
+ # == Other notes
153
+ #
154
+ # Several APIs have been carried over from EM::Deferrable for compatibility
155
+ # reasons during a transitionary period. Specifically cancel_errback and
156
+ # cancel_callback are implemented, but their usage is to be strongly
157
+ # discouraged. Due to the already complex nature of reaction systems, dynamic
158
+ # callback deletion only makes the problem much worse. It is always better to
159
+ # add correct conditionals to the callback code, or use more states, than to
160
+ # address such implementaiton issues with conditional callbacks.
161
+
162
+ module EventMachine
163
+
164
+ class Completion
165
+ # This is totally not used (re-implemented), it's here in case people check
166
+ # for kind_of?
167
+ include EventMachine::Deferrable
168
+
169
+ attr_reader :state, :value
170
+
171
+ def initialize
172
+ @state = :unknown
173
+ @callbacks = Hash.new { |h,k| h[k] = [] }
174
+ @value = []
175
+ @timeout_timer = nil
176
+ end
177
+
178
+ # Enter the :succeeded state, setting the result value if given.
179
+ def succeed(*args)
180
+ change_state(:succeeded, *args)
181
+ end
182
+ # The old EM method:
183
+ alias set_deferred_success succeed
184
+
185
+ # Enter the :failed state, setting the result value if given.
186
+ def fail(*args)
187
+ change_state(:failed, *args)
188
+ end
189
+ # The old EM method:
190
+ alias set_deferred_failure fail
191
+
192
+ # Statebacks are called when you enter (or are in) the named state.
193
+ def stateback(state, *a, &b)
194
+ # The following is quite unfortunate special casing for :completed
195
+ # statebacks, but it's a necessary evil for latent completion
196
+ # definitions.
197
+
198
+ if :completed == state || !completed? || @state == state
199
+ @callbacks[state] << EM::Callback(*a, &b)
200
+ end
201
+ execute_callbacks
202
+ self
203
+ end
204
+
205
+ # Callbacks are called when you enter (or are in) a :succeeded state.
206
+ def callback(*a, &b)
207
+ stateback(:succeeded, *a, &b)
208
+ end
209
+
210
+ # Errbacks are called when you enter (or are in) a :failed state.
211
+ def errback(*a, &b)
212
+ stateback(:failed, *a, &b)
213
+ end
214
+
215
+ # Completions are called when you enter (or are in) either a :failed or a
216
+ # :succeeded state. They are stored as a special (reserved) state called
217
+ # :completed.
218
+ def completion(*a, &b)
219
+ stateback(:completed, *a, &b)
220
+ end
221
+
222
+ # Enter a new state, setting the result value if given. If the state is one
223
+ # of :succeeded or :failed, then :completed callbacks will also be called.
224
+ def change_state(state, *args)
225
+ @value = args
226
+ @state = state
227
+
228
+ EM.schedule { execute_callbacks }
229
+ end
230
+
231
+ # The old EM method:
232
+ alias set_deferred_status change_state
233
+
234
+ # Indicates that we've reached some kind of completion state, by default
235
+ # this is :succeeded or :failed. Due to these semantics, the :completed
236
+ # state is reserved for internal use.
237
+ def completed?
238
+ completion_states.any? { |s| state == s }
239
+ end
240
+
241
+ # Completion states simply returns a list of completion states, by default
242
+ # this is :succeeded and :failed.
243
+ def completion_states
244
+ [:succeeded, :failed]
245
+ end
246
+
247
+ # Schedule a time which if passes before we enter a completion state, this
248
+ # deferrable will be failed with the given arguments.
249
+ def timeout(time, *args)
250
+ cancel_timeout
251
+ @timeout_timer = EM::Timer.new(time) do
252
+ fail(*args) unless completed?
253
+ end
254
+ end
255
+
256
+ # Disable the timeout
257
+ def cancel_timeout
258
+ if @timeout_timer
259
+ @timeout_timer.cancel
260
+ @timeout_timer = nil
261
+ end
262
+ end
263
+
264
+ # Remove an errback. N.B. Some errbacks cannot be deleted. Usage is NOT
265
+ # recommended, this is an anti-pattern.
266
+ def cancel_errback(*a, &b)
267
+ @callbacks[:failed].delete(EM::Callback(*a, &b))
268
+ end
269
+
270
+ # Remove a callback. N.B. Some callbacks cannot be deleted. Usage is NOT
271
+ # recommended, this is an anti-pattern.
272
+ def cancel_callback(*a, &b)
273
+ @callbacks[:succeeded].delete(EM::Callback(*a, &b))
274
+ end
275
+
276
+ private
277
+ # Execute all callbacks for the current state. If in a completed state, then
278
+ # call any statebacks associated with the completed state.
279
+ def execute_callbacks
280
+ execute_state_callbacks(state)
281
+ if completed?
282
+ execute_state_callbacks(:completed)
283
+ clear_dead_callbacks
284
+ cancel_timeout
285
+ end
286
+ end
287
+
288
+ # Iterate all callbacks for a given state, and remove then call them.
289
+ def execute_state_callbacks(state)
290
+ while callback = @callbacks[state].shift
291
+ callback.call(*value)
292
+ end
293
+ end
294
+
295
+ # If we enter a completion state, clear other completion states after all
296
+ # callback chains are completed. This means that operation specific
297
+ # callbacks can't be dual-called, which is most common user error.
298
+ def clear_dead_callbacks
299
+ completion_states.each do |state|
300
+ @callbacks[state].clear
301
+ end
302
+ end
303
+ end
304
+ end
@@ -1,5 +1,5 @@
1
1
  module EventMachine
2
- class FileNotFoundException < Exception # :nodoc:
2
+ class FileNotFoundException < Exception
3
3
  end
4
4
 
5
5
  # EventMachine::Connection is a class that is instantiated
@@ -8,7 +8,7 @@ module EventMachine
8
8
  # to a remote server or accepted locally from a remote client.)
9
9
  # When a Connection object is instantiated, it <i>mixes in</i>
10
10
  # the functionality contained in the user-defined module
11
- # specified in calls to EventMachine#connect or EventMachine#start_server.
11
+ # specified in calls to {EventMachine.connect} or {EventMachine.start_server}.
12
12
  # User-defined handler modules may redefine any or all of the standard
13
13
  # methods defined here, as well as add arbitrary additional code
14
14
  # that will also be mixed in.
@@ -22,17 +22,30 @@ module EventMachine
22
22
  #
23
23
  # This class is never instantiated by user code, and does not publish an
24
24
  # initialize method. The instance methods of EventMachine::Connection
25
- # which may be called by the event loop are: post_init, receive_data,
26
- # and unbind. All of the other instance methods defined here are called
27
- # only by user code.
25
+ # which may be called by the event loop are:
28
26
  #
27
+ # * {#post_init}
28
+ # * {#connection_completed}
29
+ # * {#receive_data}
30
+ # * {#unbind}
31
+ # * {#ssl_verify_peer} (if TLS is used)
32
+ # * {#ssl_handshake_completed}
33
+ #
34
+ # All of the other instance methods defined here are called only by user code.
35
+ #
36
+ # @see file:docs/GettingStarted.md EventMachine tutorial
29
37
  class Connection
30
- attr_accessor :signature # :nodoc:
38
+ # @private
39
+ attr_accessor :signature
40
+
41
+ # @private
42
+ alias original_method method
31
43
 
32
44
  # Override .new so subclasses don't have to call super and can ignore
33
45
  # connection-specific arguments
34
46
  #
35
- def self.new(sig, *args) #:nodoc:
47
+ # @private
48
+ def self.new(sig, *args)
36
49
  allocate.instance_eval do
37
50
  # Store signature
38
51
  @signature = sig
@@ -50,28 +63,26 @@ module EventMachine
50
63
 
51
64
  # Stubbed initialize so legacy superclasses can safely call super
52
65
  #
53
- def initialize(*args) #:nodoc:
66
+ # @private
67
+ def initialize(*args)
54
68
  end
55
69
 
56
- # def associate_callback_target(sig) #:nodoc:
57
- # # no-op for the time being, to match similar no-op in rubymain.cpp
58
- # end
59
-
60
- # EventMachine::Connection#post_init is called by the event loop
61
- # immediately after the network connection has been established,
70
+ # Called by the event loop immediately after the network connection has been established,
62
71
  # and before resumption of the network loop.
63
72
  # This method is generally not called by user code, but is called automatically
64
73
  # by the event loop. The base-class implementation is a no-op.
65
74
  # This is a very good place to initialize instance variables that will
66
75
  # be used throughout the lifetime of the network connection.
67
76
  #
77
+ # @see #connection_completed
78
+ # @see #unbind
79
+ # @see #send_data
80
+ # @see #receive_data
68
81
  def post_init
69
82
  end
70
83
 
71
- # EventMachine::Connection#receive_data is called by the event loop
72
- # whenever data has been received by the network connection.
73
- # It is never called by user code.
74
- # receive_data is called with a single parameter, a String containing
84
+ # Called by the event loop whenever data has been received by the network connection.
85
+ # It is never called by user code. {#receive_data} is called with a single parameter, a String containing
75
86
  # the network protocol data, which may of course be binary. You will
76
87
  # generally redefine this method to perform your own processing of the incoming data.
77
88
  #
@@ -89,52 +100,126 @@ module EventMachine
89
100
  # in your redefined implementation of receive_data. For a better understanding
90
101
  # of this, read through the examples of specific protocol handlers in EventMachine::Protocols
91
102
  #
92
- # The base-class implementation of receive_data (which will be invoked if
93
- # you don't redefine it) simply prints the size of each incoming data packet
94
- # to stdout.
103
+ # The base-class implementation (which will be invoked only if you didn't override it in your protocol handler)
104
+ # simply prints incoming data packet size to stdout.
105
+ #
106
+ # @param [String] data Opaque incoming data.
107
+ # @note Depending on the protocol, buffer sizes and OS networking stack configuration, incoming data may or may not be "a complete message".
108
+ # It is up to this handler to detect content boundaries to determine whether all the content (for example, full HTTP request)
109
+ # has been received and can be processed.
95
110
  #
111
+ # @see #post_init
112
+ # @see #connection_completed
113
+ # @see #unbind
114
+ # @see #send_data
115
+ # @see file:docs/GettingStarted.md EventMachine tutorial
96
116
  def receive_data data
97
117
  puts "............>>>#{data.length}"
98
118
  end
99
119
 
100
- # #ssl_handshake_completed is called by EventMachine when the SSL/TLS handshake has
120
+ # Called by EventMachine when the SSL/TLS handshake has
101
121
  # been completed, as a result of calling #start_tls to initiate SSL/TLS on the connection.
102
122
  #
103
- # This callback exists because #post_init and #connection_completed are <b>not</b> reliable
104
- # for indicating when an SSL/TLS connection is ready to have it's certificate queried for.
123
+ # This callback exists because {#post_init} and {#connection_completed} are **not** reliable
124
+ # for indicating when an SSL/TLS connection is ready to have its certificate queried for.
105
125
  #
106
- # See #get_peer_cert for application and example.
126
+ # @see #get_peer_cert
107
127
  def ssl_handshake_completed
108
128
  end
109
129
 
110
- # #ssl_verify_peer is called by EventMachine when :verify_peer => true has been passed to #start_tls.
130
+ # Called by EventMachine when :verify_peer => true has been passed to {#start_tls}.
111
131
  # It will be called with each certificate in the certificate chain provided by the remote peer.
112
- # The cert will be passed as a String in PEM format, the same as in #get_peer_cert. It is up to user defined
132
+ #
133
+ # The cert will be passed as a String in PEM format, the same as in {#get_peer_cert}. It is up to user defined
113
134
  # code to perform a check on the certificates. The return value from this callback is used to accept or deny the peer.
114
135
  # A return value that is not nil or false triggers acceptance. If the peer is not accepted, the connection
115
- # will be subsequently closed. See 'tests/test_ssl_verify.rb' for a simple example.
136
+ # will be subsequently closed.
137
+ #
138
+ # @example This server always accepts all peers
139
+ #
140
+ # module AcceptServer
141
+ # def post_init
142
+ # start_tls(:verify_peer => true)
143
+ # end
144
+ #
145
+ # def ssl_verify_peer(cert)
146
+ # true
147
+ # end
148
+ #
149
+ # def ssl_handshake_completed
150
+ # $server_handshake_completed = true
151
+ # end
152
+ # end
153
+ #
154
+ #
155
+ # @example This server never accepts any peers
156
+ #
157
+ # module DenyServer
158
+ # def post_init
159
+ # start_tls(:verify_peer => true)
160
+ # end
161
+ #
162
+ # def ssl_verify_peer(cert)
163
+ # # Do not accept the peer. This should now cause the connection to shut down
164
+ # # without the SSL handshake being completed.
165
+ # false
166
+ # end
167
+ #
168
+ # def ssl_handshake_completed
169
+ # $server_handshake_completed = true
170
+ # end
171
+ # end
172
+ #
173
+ # @see #start_tls
116
174
  def ssl_verify_peer(cert)
117
175
  end
118
176
 
119
- # EventMachine::Connection#unbind is called by the framework whenever a connection
120
- # (either a server or client connection) is closed. The close can occur because
121
- # your code intentionally closes it (see close_connection and close_connection_after_writing),
177
+ # called by the framework whenever a connection (either a server or client connection) is closed.
178
+ # The close can occur because your code intentionally closes it (using {#close_connection} and {#close_connection_after_writing}),
122
179
  # because the remote peer closed the connection, or because of a network error.
123
180
  # You may not assume that the network connection is still open and able to send or
124
181
  # receive data when the callback to unbind is made. This is intended only to give
125
182
  # you a chance to clean up associations your code may have made to the connection
126
183
  # object while it was open.
127
184
  #
185
+ # If you want to detect which peer has closed the connection, you can override {#close_connection} in your protocol handler
186
+ # and set an @ivar.
187
+ #
188
+ # @example Overriding Connection#close_connection to distinguish connections closed on our side
189
+ #
190
+ # class MyProtocolHandler < EventMachine::Connection
191
+ #
192
+ # # ...
193
+ #
194
+ # def close_connection(*args)
195
+ # @intentionally_closed_connection = true
196
+ # super(*args)
197
+ # end
198
+ #
199
+ # def unbind
200
+ # if @intentionally_closed_connection
201
+ # # ...
202
+ # end
203
+ # end
204
+ #
205
+ # # ...
206
+ #
207
+ # end
208
+ #
209
+ # @see #post_init
210
+ # @see #connection_completed
211
+ # @see file:docs/GettingStarted.md EventMachine tutorial
128
212
  def unbind
129
213
  end
130
214
 
131
- # EventMachine::Connection#proxy_target_unbound is called by the reactor after attempting
132
- # to relay incoming data to a descriptor (set as a proxy target descriptor with
133
- # EventMachine::enable_proxy) that has already been closed.
215
+ # Called by the reactor after attempting to relay incoming data to a descriptor (set as a proxy target descriptor with
216
+ # {EventMachine.enable_proxy}) that has already been closed.
217
+ #
218
+ # @see EventMachine.enable_proxy
134
219
  def proxy_target_unbound
135
220
  end
136
221
 
137
- # EventMachine::Connection#proxy_completed is called when the reactor finished proxying all
222
+ # called when the reactor finished proxying all
138
223
  # of the requested bytes.
139
224
  def proxy_completed
140
225
  end
@@ -142,12 +227,13 @@ module EventMachine
142
227
  # EventMachine::Connection#proxy_incoming_to is called only by user code. It sets up
143
228
  # a low-level proxy relay for all data inbound for this connection, to the connection given
144
229
  # as the argument. This is essentially just a helper method for enable_proxy.
145
- # See EventMachine::enable_proxy documentation for details.
230
+ #
231
+ # @see EventMachine.enable_proxy
146
232
  def proxy_incoming_to(conn,bufsize=0)
147
233
  EventMachine::enable_proxy(self, conn, bufsize)
148
234
  end
149
235
 
150
- # Helper method for EventMachine::disable_proxy(self)
236
+ # A helper method for {EventMachine.disable_proxy}
151
237
  def stop_proxying
152
238
  EventMachine::disable_proxy(self)
153
239
  end
@@ -165,17 +251,17 @@ module EventMachine
165
251
  # However, it's not guaranteed that a future version of EventMachine will not change
166
252
  # this behavior.
167
253
  #
168
- # close_connection will <i>silently discard</i> any outbound data which you have
169
- # sent to the connection using EventMachine::Connection#send_data but which has not
254
+ # {#close_connection} will *silently discard* any outbound data which you have
255
+ # sent to the connection using {EventMachine::Connection#send_data} but which has not
170
256
  # yet been sent across the network. If you want to avoid this behavior, use
171
- # EventMachine::Connection#close_connection_after_writing.
257
+ # {EventMachine::Connection#close_connection_after_writing}.
172
258
  #
173
259
  def close_connection after_writing = false
174
260
  EventMachine::close_connection @signature, after_writing
175
261
  end
176
262
 
177
- # EventMachine::Connection#detach will remove the given connection from the event loop.
178
- # The connection's socket remains open and its file descriptor number is returned
263
+ # Removes given connection from the event loop.
264
+ # The connection's socket remains open and its file descriptor number is returned.
179
265
  def detach
180
266
  EventMachine::detach_fd @signature
181
267
  end
@@ -184,42 +270,51 @@ module EventMachine
184
270
  EventMachine::get_sock_opt @signature, level, option
185
271
  end
186
272
 
187
- # EventMachine::Connection#close_connection_after_writing is a variant of close_connection.
273
+ def set_sock_opt level, optname, optval
274
+ EventMachine::set_sock_opt @signature, level, optname, optval
275
+ end
276
+
277
+ # A variant of {#close_connection}.
188
278
  # All of the descriptive comments given for close_connection also apply to
189
- # close_connection_after_writing, <i>with one exception:</i> If the connection has
279
+ # close_connection_after_writing, *with one exception*: if the connection has
190
280
  # outbound data sent using send_dat but which has not yet been sent across the network,
191
- # close_connection_after_writing will schedule the connection to be closed <i>after</i>
281
+ # close_connection_after_writing will schedule the connection to be closed *after*
192
282
  # all of the outbound data has been safely written to the remote peer.
193
283
  #
194
284
  # Depending on the amount of outgoing data and the speed of the network,
195
285
  # considerable time may elapse between your call to close_connection_after_writing
196
286
  # and the actual closing of the socket (at which time the unbind callback will be called
197
- # by the event loop). During this time, you <i>may not</i> call send_data to transmit
287
+ # by the event loop). During this time, you *may not* call send_data to transmit
198
288
  # additional data (that is, the connection is closed for further writes). In very
199
- # rare cases, you may experience a receive_data callback after your call to close_connection_after_writing,
289
+ # rare cases, you may experience a receive_data callback after your call to {#close_connection_after_writing},
200
290
  # depending on whether incoming data was in the process of being received on the connection
201
- # at the moment when you called close_connection_after_writing. Your protocol handler must
291
+ # at the moment when you called {#close_connection_after_writing}. Your protocol handler must
202
292
  # be prepared to properly deal with such data (probably by ignoring it).
203
293
  #
294
+ # @see #close_connection
295
+ # @see #send_data
204
296
  def close_connection_after_writing
205
297
  close_connection true
206
298
  end
207
299
 
208
- # EventMachine::Connection#send_data is only called by user code, never by
209
- # the event loop. You call this method to send data to the remote end of the
210
- # network connection. send_data is called with a single String argument, which
211
- # may of course contain binary data. You can call send_data any number of times.
212
- # send_data is an instance method of an object derived from EventMachine::Connection
213
- # and containing your mixed-in handler code), so if you call it without qualification
214
- # within a callback function, the data will be sent to the same network connection
215
- # that generated the callback. Calling self.send_data is exactly equivalent.
300
+ # Call this method to send data to the remote end of the network connection. It takes a single String argument,
301
+ # which may contain binary data. Data is buffered to be sent at the end of this event loop tick (cycle).
302
+ #
303
+ # When used in a method that is event handler (for example, {#post_init} or {#connection_completed}, it will send
304
+ # data to the other end of the connection that generated the event.
305
+ # You can also call {#send_data} to write to other connections. For more information see The Chat Server Example in the
306
+ # {file:docs/GettingStarted.md EventMachine tutorial}.
307
+ #
308
+ # If you want to send some data and then immediately close the connection, make sure to use {#close_connection_after_writing}
309
+ # instead of {#close_connection}.
216
310
  #
217
- # You can also call send_data to write to a connection <i>other than the one
218
- # whose callback you are calling send_data from.</i> This is done by recording
219
- # the value of the connection in any callback function (the value self), in any
220
- # variable visible to other callback invocations on the same or different
221
- # connection objects. (Need an example to make that clear.)
222
311
  #
312
+ # @param [String] data Data to send asynchronously
313
+ #
314
+ # @see file:docs/GettingStarted.md EventMachine tutorial
315
+ # @see Connection#receive_data
316
+ # @see Connection#post_init
317
+ # @see Connection#unbind
223
318
  def send_data data
224
319
  data = data.to_s
225
320
  size = data.bytesize if data.respond_to?(:bytesize)
@@ -228,56 +323,58 @@ module EventMachine
228
323
  end
229
324
 
230
325
  # Returns true if the connection is in an error state, false otherwise.
231
- # In general, you can detect the occurrence of communication errors or unexpected
232
- # disconnection by the remote peer by handing the #unbind method. In some cases, however,
233
- # it's useful to check the status of the connection using #error? before attempting to send data.
234
- # This function is synchronous: it will return immediately without blocking.
235
326
  #
327
+ # In general, you can detect the occurrence of communication errors or unexpected
328
+ # disconnection by the remote peer by handing the {#unbind} method. In some cases, however,
329
+ # it's useful to check the status of the connection using {#error?} before attempting to send data.
330
+ # This function is synchronous but it will return immediately without blocking.
236
331
  #
332
+ # @return [Boolean] true if the connection is in an error state, false otherwise
237
333
  def error?
238
- EventMachine::report_connection_error_status(@signature) != 0
334
+ errno = EventMachine::report_connection_error_status(@signature)
335
+ case errno
336
+ when 0
337
+ false
338
+ when -1
339
+ true
340
+ else
341
+ EventMachine::ERRNOS[errno]
342
+ end
239
343
  end
240
344
 
241
- # #connection_completed is called by the event loop when a remote TCP connection
242
- # attempt completes successfully. You can expect to get this notification after calls
243
- # to EventMachine#connect. Remember that EventMachine makes remote connections
244
- # asynchronously, just as with any other kind of network event. #connection_completed
345
+ # Called by the event loop when a remote TCP connection attempt completes successfully.
346
+ # You can expect to get this notification after calls to {EventMachine.connect}. Remember that EventMachine makes remote connections
347
+ # asynchronously, just as with any other kind of network event. This method
245
348
  # is intended primarily to assist with network diagnostics. For normal protocol
246
- # handling, use #post_init to perform initial work on a new connection (such as
247
- # send an initial set of data).
248
- # #post_init will always be called. #connection_completed will only be called in case
249
- # of a successful completion. A connection-attempt which fails will receive a call
250
- # to #unbind after the failure.
349
+ # handling, use #post_init to perform initial work on a new connection (such as sending initial set of data).
350
+ # {Connection#post_init} will always be called. This method will only be called in case of a successful completion.
351
+ # A connection attempt which fails will result a call to {Connection#unbind} after the failure.
352
+ #
353
+ # @see Connection#post_init
354
+ # @see Connection#unbind
355
+ # @see file:docs/GettingStarted.md EventMachine tutorial
251
356
  def connection_completed
252
357
  end
253
358
 
254
- # Call #start_tls at any point to initiate TLS encryption on connected streams.
359
+ # Call {#start_tls} at any point to initiate TLS encryption on connected streams.
255
360
  # The method is smart enough to know whether it should perform a server-side
256
- # or a client-side handshake. An appropriate place to call #start_tls is in
257
- # your redefined #post_init method, or in the #connection_completed handler for
361
+ # or a client-side handshake. An appropriate place to call {#start_tls} is in
362
+ # your redefined {#post_init} method, or in the {#connection_completed} handler for
258
363
  # an outbound connection.
259
364
  #
260
- # #start_tls takes an optional parameter hash that allows you to specify certificate
261
- # and other options to be used with this Connection object. Here are the currently-supported
262
- # options:
263
365
  #
264
- # * :cert_chain_file :
265
- # takes a String, which is interpreted as the name of a readable file in the
266
- # local filesystem. The file is expected to contain a chain of X509 certificates in
267
- # PEM format, with the most-resolved certificate at the top of the file, successive
268
- # intermediate certs in the middle, and the root (or CA) cert at the bottom.
366
+ # @option args [String] :cert_chain_file (nil) local path of a readable file that contants a chain of X509 certificates in
367
+ # the [PEM format](http://en.wikipedia.org/wiki/Privacy_Enhanced_Mail),
368
+ # with the most-resolved certificate at the top of the file, successive intermediate
369
+ # certs in the middle, and the root (or CA) cert at the bottom.
269
370
  #
270
- # * :private_key_file :
271
- # takes a String, which is interpreted as the name of a readable file in the
272
- # local filesystem. The file must contain a private key in PEM format.
371
+ # @option args [String] :private_key_file (nil) local path of a readable file that must contain a private key in the [PEM format](http://en.wikipedia.org/wiki/Privacy_Enhanced_Mail).
273
372
  #
274
- # * :verify_peer :
275
- # takes either true or false. Default is false. This indicates whether a server should request a
276
- # certificate from a peer, to be verified by user code. If true, the #ssl_verify_peer callback
277
- # on the Connection object is called with each certificate in the certificate chain provided by
278
- # the peer. See documentation on #ssl_verify_peer for how to use this.
373
+ # @option args [String] :verify_peer (false) indicates whether a server should request a certificate from a peer, to be verified by user code.
374
+ # If true, the {#ssl_verify_peer} callback on the {EventMachine::Connection} object is called with each certificate
375
+ # in the certificate chain provided by the peer. See documentation on {#ssl_verify_peer} for how to use this.
279
376
  #
280
- # === Usage example:
377
+ # @example Using TLS with EventMachine
281
378
  #
282
379
  # require 'rubygems'
283
380
  # require 'eventmachine'
@@ -288,101 +385,106 @@ module EventMachine
288
385
  # end
289
386
  # end
290
387
  #
291
- # EM.run {
292
- # EM.start_server("127.0.0.1", 9999, Handler)
293
- # }
388
+ # EventMachine.run do
389
+ # EventMachine.start_server("127.0.0.1", 9999, Handler)
390
+ # end
391
+ #
392
+ # @param [Hash] args
294
393
  #
295
- #--
296
- # TODO: support passing an encryption parameter, which can be string or Proc, to get a passphrase
394
+ # @todo support passing an encryption parameter, which can be string or Proc, to get a passphrase
297
395
  # for encrypted private keys.
298
- # TODO: support passing key material via raw strings or Procs that return strings instead of
396
+ # @todo support passing key material via raw strings or Procs that return strings instead of
299
397
  # just filenames.
300
- # What will get nasty is whether we have to define a location for storing this stuff as files.
301
- # In general, the OpenSSL interfaces for dealing with certs and keys in files are much better
302
- # behaved than the ones for raw chunks of memory.
303
398
  #
399
+ # @see #ssl_verify_peer
304
400
  def start_tls args={}
305
401
  priv_key, cert_chain, verify_peer = args.values_at(:private_key_file, :cert_chain_file, :verify_peer)
306
402
 
307
403
  [priv_key, cert_chain].each do |file|
308
404
  next if file.nil? or file.empty?
309
405
  raise FileNotFoundException,
310
- "Could not find #{file} for start_tls" unless File.exists? file
406
+ "Could not find #{file} for start_tls" unless File.exists? file
311
407
  end
312
408
 
313
409
  EventMachine::set_tls_parms(@signature, priv_key || '', cert_chain || '', verify_peer)
314
410
  EventMachine::start_tls @signature
315
411
  end
316
412
 
317
- # If SSL/TLS is active on the connection, #get_peer_cert returns the remote X509 certificate
318
- # as a String, in the popular PEM format. This can then be used for arbitrary validation
413
+ # If [TLS](http://en.wikipedia.org/wiki/Transport_Layer_Security) is active on the connection, returns the remote [X509 certificate](http://en.wikipedia.org/wiki/X.509)
414
+ # as a string, in the popular [PEM format](http://en.wikipedia.org/wiki/Privacy_Enhanced_Mail). This can then be used for arbitrary validation
319
415
  # of a peer's certificate in your code.
320
416
  #
321
- # This should be called in/after the #ssl_handshake_completed callback, which indicates
417
+ # This should be called in/after the {#ssl_handshake_completed} callback, which indicates
322
418
  # that SSL/TLS is active. Using this callback is important, because the certificate may not
323
419
  # be available until the time it is executed. Using #post_init or #connection_completed is
324
420
  # not adequate, because the SSL handshake may still be taking place.
325
421
  #
326
- # #get_peer_cert will return <b>nil</b> if:
422
+ # This method will return `nil` if:
327
423
  #
328
- # * EventMachine is not built with OpenSSL support
329
- # * SSL/TLS is not active on the connection
330
- # * SSL/TLS handshake is not yet complete
424
+ # * EventMachine is not built with [OpenSSL](http://www.openssl.org) support
425
+ # * [TLS](http://en.wikipedia.org/wiki/Transport_Layer_Security) is not active on the connection
426
+ # * TLS handshake is not yet complete
331
427
  # * Remote peer for any other reason has not presented a certificate
332
428
  #
333
- # === Example:
334
429
  #
335
- # module Handler
430
+ # @example Getting peer TLS certificate information in EventMachine
336
431
  #
337
- # def post_init
338
- # puts "Starting TLS"
339
- # start_tls
340
- # end
432
+ # module Handler
433
+ # def post_init
434
+ # puts "Starting TLS"
435
+ # start_tls
436
+ # end
341
437
  #
342
- # def ssl_handshake_completed
343
- # puts get_peer_cert
344
- # close_connection
345
- # end
438
+ # def ssl_handshake_completed
439
+ # puts get_peer_cert
440
+ # close_connection
441
+ # end
346
442
  #
347
- # def unbind
348
- # EventMachine::stop_event_loop
349
- # end
443
+ # def unbind
444
+ # EventMachine::stop_event_loop
445
+ # end
446
+ # end
350
447
  #
448
+ # EventMachine.run do
449
+ # EventMachine.connect "mail.google.com", 443, Handler
351
450
  # end
352
451
  #
353
- # EM.run {
354
- # EventMachine::connect "mail.google.com", 443, Handler
355
- # }
356
- #
357
- # Output:
358
- # -----BEGIN CERTIFICATE-----
359
- # MIIDIjCCAougAwIBAgIQbldpChBPqv+BdPg4iwgN8TANBgkqhkiG9w0BAQUFADBM
360
- # MQswCQYDVQQGEwJaQTElMCMGA1UEChMcVGhhd3RlIENvbnN1bHRpbmcgKFB0eSkg
361
- # THRkLjEWMBQGA1UEAxMNVGhhd3RlIFNHQyBDQTAeFw0wODA1MDIxNjMyNTRaFw0w
362
- # OTA1MDIxNjMyNTRaMGkxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlh
363
- # MRYwFAYDVQQHEw1Nb3VudGFpbiBWaWV3MRMwEQYDVQQKEwpHb29nbGUgSW5jMRgw
364
- # FgYDVQQDEw9tYWlsLmdvb2dsZS5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJ
365
- # AoGBALlkxdh2QXegdElukCSOV2+8PKiONIS+8Tu9K7MQsYpqtLNC860zwOPQ2NLI
366
- # 3Zp4jwuXVTrtzGuiqf5Jioh35Ig3CqDXtLyZoypjZUQcq4mlLzHlhIQ4EhSjDmA7
367
- # Ffw9y3ckSOQgdBQWNLbquHh9AbEUjmhkrYxIqKXeCnRKhv6nAgMBAAGjgecwgeQw
368
- # KAYDVR0lBCEwHwYIKwYBBQUHAwEGCCsGAQUFBwMCBglghkgBhvhCBAEwNgYDVR0f
369
- # BC8wLTAroCmgJ4YlaHR0cDovL2NybC50aGF3dGUuY29tL1RoYXd0ZVNHQ0NBLmNy
370
- # bDByBggrBgEFBQcBAQRmMGQwIgYIKwYBBQUHMAGGFmh0dHA6Ly9vY3NwLnRoYXd0
371
- # ZS5jb20wPgYIKwYBBQUHMAKGMmh0dHA6Ly93d3cudGhhd3RlLmNvbS9yZXBvc2l0
372
- # b3J5L1RoYXd0ZV9TR0NfQ0EuY3J0MAwGA1UdEwEB/wQCMAAwDQYJKoZIhvcNAQEF
373
- # BQADgYEAsRwpLg1dgCR1gYDK185MFGukXMeQFUvhGqF8eT/CjpdvezyKVuz84gSu
374
- # 6ccMXgcPQZGQN/F4Xug+Q01eccJjRSVfdvR5qwpqCj+6BFl5oiKDBsveSkrmL5dz
375
- # s2bn7TdTSYKcLeBkjXxDLHGBqLJ6TNCJ3c4/cbbG5JhGvoema94=
376
- # -----END CERTIFICATE-----
452
+ # # Will output:
453
+ # # -----BEGIN CERTIFICATE-----
454
+ # # MIIDIjCCAougAwIBAgIQbldpChBPqv+BdPg4iwgN8TANBgkqhkiG9w0BAQUFADBM
455
+ # # MQswCQYDVQQGEwJaQTElMCMGA1UEChMcVGhhd3RlIENvbnN1bHRpbmcgKFB0eSkg
456
+ # # THRkLjEWMBQGA1UEAxMNVGhhd3RlIFNHQyBDQTAeFw0wODA1MDIxNjMyNTRaFw0w
457
+ # # OTA1MDIxNjMyNTRaMGkxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlh
458
+ # # MRYwFAYDVQQHEw1Nb3VudGFpbiBWaWV3MRMwEQYDVQQKEwpHb29nbGUgSW5jMRgw
459
+ # # FgYDVQQDEw9tYWlsLmdvb2dsZS5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJ
460
+ # # AoGBALlkxdh2QXegdElukCSOV2+8PKiONIS+8Tu9K7MQsYpqtLNC860zwOPQ2NLI
461
+ # # 3Zp4jwuXVTrtzGuiqf5Jioh35Ig3CqDXtLyZoypjZUQcq4mlLzHlhIQ4EhSjDmA7
462
+ # # Ffw9y3ckSOQgdBQWNLbquHh9AbEUjmhkrYxIqKXeCnRKhv6nAgMBAAGjgecwgeQw
463
+ # # KAYDVR0lBCEwHwYIKwYBBQUHAwEGCCsGAQUFBwMCBglghkgBhvhCBAEwNgYDVR0f
464
+ # # BC8wLTAroCmgJ4YlaHR0cDovL2NybC50aGF3dGUuY29tL1RoYXd0ZVNHQ0NBLmNy
465
+ # # bDByBggrBgEFBQcBAQRmMGQwIgYIKwYBBQUHMAGGFmh0dHA6Ly9vY3NwLnRoYXd0
466
+ # # ZS5jb20wPgYIKwYBBQUHMAKGMmh0dHA6Ly93d3cudGhhd3RlLmNvbS9yZXBvc2l0
467
+ # # b3J5L1RoYXd0ZV9TR0NfQ0EuY3J0MAwGA1UdEwEB/wQCMAAwDQYJKoZIhvcNAQEF
468
+ # # BQADgYEAsRwpLg1dgCR1gYDK185MFGukXMeQFUvhGqF8eT/CjpdvezyKVuz84gSu
469
+ # # 6ccMXgcPQZGQN/F4Xug+Q01eccJjRSVfdvR5qwpqCj+6BFl5oiKDBsveSkrmL5dz
470
+ # # s2bn7TdTSYKcLeBkjXxDLHGBqLJ6TNCJ3c4/cbbG5JhGvoema94=
471
+ # # -----END CERTIFICATE-----
377
472
  #
378
473
  # You can do whatever you want with the certificate String, such as load it
379
- # as a certificate object using the OpenSSL library, and check it's fields.
474
+ # as a certificate object using the OpenSSL library, and check its fields.
475
+ #
476
+ # @return [String] the remote [X509 certificate](http://en.wikipedia.org/wiki/X.509), in the popular [PEM format](http://en.wikipedia.org/wiki/Privacy_Enhanced_Mail),
477
+ # if TLS is active on the connection
478
+ #
479
+ # @see Connection#start_tls
480
+ # @see Connection#ssl_handshake_completed
380
481
  def get_peer_cert
381
482
  EventMachine::get_peer_cert @signature
382
483
  end
383
484
 
384
485
 
385
- # send_datagram is for sending UDP messages.
486
+ # Sends UDP messages.
487
+ #
386
488
  # This method may be called from any Connection object that refers
387
489
  # to an open datagram socket (see EventMachine#open_datagram_socket).
388
490
  # The method sends a UDP (datagram) packet containing the data you specify,
@@ -399,10 +501,10 @@ module EventMachine
399
501
  # but to be really safe, send messages smaller than the Ethernet-packet
400
502
  # size (typically about 1400 bytes). Some very restrictive WANs
401
503
  # will either drop or truncate packets larger than about 500 bytes.
402
- #--
403
- # Added the Integer wrapper around the port parameter per suggestion by
404
- # Matthieu Riou, after he passed a String and spent hours tearing his hair out.
405
504
  #
505
+ # @param [String] data Data to send asynchronously
506
+ # @param [String] recipient_address IP address of the recipient
507
+ # @param [String] recipient_port Port of the recipient
406
508
  def send_datagram data, recipient_address, recipient_port
407
509
  data = data.to_s
408
510
  size = data.bytesize if data.respond_to?(:bytesize)
@@ -411,13 +513,16 @@ module EventMachine
411
513
  end
412
514
 
413
515
 
414
- # #get_peername is used with stream-connections to obtain the identity
516
+ # This method is used with stream-connections to obtain the identity
415
517
  # of the remotely-connected peer. If a peername is available, this method
416
518
  # returns a sockaddr structure. The method returns nil if no peername is available.
417
519
  # You can use Socket.unpack_sockaddr_in and its variants to obtain the
418
520
  # values contained in the peername structure returned from #get_peername.
419
521
  #
522
+ # @example How to get peer IP address and port with EventMachine
523
+ #
420
524
  # require 'socket'
525
+ #
421
526
  # module Handler
422
527
  # def receive_data data
423
528
  # port, ip = Socket.unpack_sockaddr_in(get_peername)
@@ -428,27 +533,39 @@ module EventMachine
428
533
  EventMachine::get_peername @signature
429
534
  end
430
535
 
431
- # #get_sockname is used with stream-connections to obtain the identity
536
+ # Used with stream-connections to obtain the identity
432
537
  # of the local side of the connection. If a local name is available, this method
433
538
  # returns a sockaddr structure. The method returns nil if no local name is available.
434
- # You can use Socket#unpack_sockaddr_in and its variants to obtain the
435
- # values contained in the local-name structure returned from #get_sockname.
539
+ # You can use {Socket.unpack_sockaddr_in} and its variants to obtain the
540
+ # values contained in the local-name structure returned from this method.
541
+ #
542
+ # @example
543
+ #
544
+ # require 'socket'
545
+ #
546
+ # module Handler
547
+ # def receive_data data
548
+ # port, ip = Socket.unpack_sockaddr_in(get_sockname)
549
+ # puts "got #{data.inspect}"
550
+ # end
551
+ # end
436
552
  def get_sockname
437
553
  EventMachine::get_sockname @signature
438
554
  end
439
555
 
440
556
  # Returns the PID (kernel process identifier) of a subprocess
441
- # associated with this Connection object. For use with EventMachine#popen
557
+ # associated with this Connection object. For use with {EventMachine.popen}
442
558
  # and similar methods. Returns nil when there is no meaningful subprocess.
443
- #--
444
559
  #
560
+ # @return [Integer]
445
561
  def get_pid
446
562
  EventMachine::get_subprocess_pid @signature
447
563
  end
448
564
 
449
- # Returns a subprocess exit status. Only useful for #popen. Call it in your
450
- # #unbind handler.
565
+ # Returns a subprocess exit status. Only useful for {EventMachine.popen}. Call it in your
566
+ # {#unbind} handler.
451
567
  #
568
+ # @return [Integer]
452
569
  def get_status
453
570
  EventMachine::get_subprocess_status @signature
454
571
  end
@@ -462,88 +579,97 @@ module EventMachine
462
579
  EventMachine::get_comm_inactivity_timeout @signature
463
580
  end
464
581
 
465
- # Alias for #set_comm_inactivity_timeout.
466
- def comm_inactivity_timeout= value
467
- self.set_comm_inactivity_timeout value
468
- end
469
-
470
- # comm_inactivity_timeout= allows you to set the inactivity-timeout property for
582
+ # Allows you to set the inactivity-timeout property for
471
583
  # a network connection or datagram socket. Specify a non-negative float value in seconds.
472
584
  # If the value is greater than zero, the connection or socket will automatically be closed
473
585
  # if no read or write activity takes place for at least that number of seconds.
474
586
  # Specify a value of zero to indicate that no automatic timeout should take place.
475
587
  # Zero is the default value.
476
- def set_comm_inactivity_timeout value
588
+ def comm_inactivity_timeout= value
477
589
  EventMachine::set_comm_inactivity_timeout @signature, value.to_f
478
590
  end
591
+ alias set_comm_inactivity_timeout comm_inactivity_timeout=
479
592
 
480
- # pending_connect_timeout is the duration after which a TCP connection in the connecting
481
- # state will fail. It is important to distinguish this value from comm_inactivity_timeout,
482
- # which looks at how long since data was passed on an already established connection.
483
- # The value is a float in seconds.
484
- def pending_connect_timeout
485
- EventMachine::get_pending_connect_timeout @signature
486
- end
593
+ # The duration after which a TCP connection in the connecting state will fail.
594
+ # It is important to distinguish this value from {EventMachine::Connection#comm_inactivity_timeout},
595
+ # which looks at how long since data was passed on an already established connection.
596
+ # The value is a float in seconds.
597
+ #
598
+ # @return [Float] The duration after which a TCP connection in the connecting state will fail, in seconds.
599
+ def pending_connect_timeout
600
+ EventMachine::get_pending_connect_timeout @signature
601
+ end
487
602
 
488
- # Alias for #set_pending_connect_timeout.
603
+ # Sets the duration after which a TCP connection in a
604
+ # connecting state will fail.
605
+ #
606
+ # @param [Float, #to_f] value Connection timeout in seconds
489
607
  def pending_connect_timeout= value
490
- self.set_pending_connect_timeout value
491
- end
492
-
493
- # set_pending_connect_timeout sets the duration after which a TCP connection in a
494
- # connecting state will fail. Takes a float in seconds.
495
- def set_pending_connect_timeout value
496
608
  EventMachine::set_pending_connect_timeout @signature, value.to_f
497
609
  end
610
+ alias set_pending_connect_timeout pending_connect_timeout=
498
611
 
499
- # Reconnect to a given host/port with the current EventMachine::Connection instance
500
- def reconnect server, port
501
- EventMachine::reconnect server, port, self
502
- end
612
+ # Reconnect to a given host/port with the current instance
613
+ #
614
+ # @param [String] server Hostname or IP address
615
+ # @param [Integer] port Port to reconnect to
616
+ def reconnect server, port
617
+ EventMachine::reconnect server, port, self
618
+ end
503
619
 
504
620
 
505
- # Like EventMachine::Connection#send_data, this sends data to the remote end of
506
- # the network connection. EventMachine::Connection@send_file_data takes a
621
+ # Like {EventMachine::Connection#send_data}, this sends data to the remote end of
622
+ # the network connection. {EventMachine::Connection#send_file_data} takes a
507
623
  # filename as an argument, though, and sends the contents of the file, in one
508
- # chunk. Contributed by Kirk Haines.
624
+ # chunk.
625
+ #
626
+ # @param [String] filename Local path of the file to send
509
627
  #
628
+ # @see #send_data
629
+ # @author Kirk Haines
510
630
  def send_file_data filename
511
631
  EventMachine::send_file_data @signature, filename
512
632
  end
513
633
 
514
634
  # Open a file on the filesystem and send it to the remote peer. This returns an
515
- # object of type EventMachine::Deferrable. The object's callbacks will be executed
635
+ # object of type {EventMachine::Deferrable}. The object's callbacks will be executed
516
636
  # on the reactor main thread when the file has been completely scheduled for
517
- # transmission to the remote peer. Its errbacks will be called in case of an error
518
- # (such as file-not-found). #stream_file_data employs various strategems to achieve
519
- # the fastest possible performance, balanced against minimum consumption of memory.
520
- #
521
- # You can control the behavior of #stream_file_data with the optional arguments parameter.
522
- # Currently-supported arguments are:
523
- # :http_chunks, a boolean flag which defaults false. If true, this flag streams the
524
- # file data in a format compatible with the HTTP chunked-transfer encoding.
637
+ # transmission to the remote peer. Its errbacks will be called in case of an error (such as file-not-found).
638
+ # This method employs various strategies to achieve the fastest possible performance,
639
+ # balanced against minimum consumption of memory.
525
640
  #
526
641
  # Warning: this feature has an implicit dependency on an outboard extension,
527
- # evma_fastfilereader. You must install this extension in order to use #stream_file_data
642
+ # evma_fastfilereader. You must install this extension in order to use {#stream_file_data}
528
643
  # with files larger than a certain size (currently 8192 bytes).
529
644
  #
645
+ # @option args [Boolean] :http_chunks (false) If true, this method will stream the file data in a format
646
+ # compatible with the HTTP chunked-transfer encoding
647
+ #
648
+ # @param [String] filename Local path of the file to stream
649
+ # @param [Hash] args Options
650
+ #
651
+ # @return [EventMachine::Deferrable]
530
652
  def stream_file_data filename, args={}
531
653
  EventMachine::FileStreamer.new( self, filename, args )
532
654
  end
533
655
 
534
- # Enable notify_readable callbacks on this connection. Only possible if the connection was created
535
- # using EM.attach and had notify_readable/notify_writable defined on the handler.
656
+ # Watches connection for readability. Only possible if the connection was created
657
+ # using {EventMachine.attach} and had {EventMachine.notify_readable}/{EventMachine.notify_writable} defined on the handler.
658
+ #
659
+ # @see #notify_readable?
536
660
  def notify_readable= mode
537
661
  EventMachine::set_notify_readable @signature, mode
538
662
  end
539
663
 
540
- # Returns true if the connection is being watched for readability.
664
+ # @return [Boolean] true if the connection is being watched for readability.
541
665
  def notify_readable?
542
666
  EventMachine::is_notify_readable @signature
543
667
  end
544
668
 
545
- # Enable notify_writable callbacks on this connection. Only possible if the connection was created
546
- # using EM.attach and had notify_readable/notify_writable defined on the handler.
669
+ # Watches connection for writeability. Only possible if the connection was created
670
+ # using {EventMachine.attach} and had {EventMachine.notify_readable}/{EventMachine.notify_writable} defined on the handler.
671
+ #
672
+ # @see #notify_writable?
547
673
  def notify_writable= mode
548
674
  EventMachine::set_notify_writable @signature, mode
549
675
  end
@@ -553,19 +679,23 @@ module EventMachine
553
679
  EventMachine::is_notify_writable @signature
554
680
  end
555
681
 
556
- # Pause a connection so that #send_data and #receive_data events are not fired until #resume is called.
682
+ # Pause a connection so that {#send_data} and {#receive_data} events are not fired until {#resume} is called.
683
+ # @see #resume
557
684
  def pause
558
685
  EventMachine::pause_connection @signature
559
686
  end
560
687
 
561
- # Resume a connection's #send_data and #receive_data events.
688
+ # Resume a connection's {#send_data} and {#receive_data} events.
689
+ # @see #pause
562
690
  def resume
563
691
  EventMachine::resume_connection @signature
564
692
  end
565
693
 
566
- # True if the connect was paused using #pause.
694
+ # @return [Boolean] true if the connect was paused using {EventMachine::Connection#pause}.
695
+ # @see #pause
696
+ # @see #resume
567
697
  def paused?
568
698
  EventMachine::connection_paused? @signature
569
699
  end
570
700
  end
571
- end
701
+ end