root/trunk/lib/eventmachine.rb

Revision 794, 68.5 kB (checked in by raggi, 1 year ago)

Added start_tls argument checks from brianmario

  • Property svn:keywords set to Id
Line 
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'
Note: See TracBrowser for help on using the browser.