Module: Object::EM

### Home Classes Methods

### In Files

- lib/em/callback.rb
- lib/em/channel.rb
- lib/em/completion.rb
- lib/em/connection.rb
- lib/em/deferrable.rb
- lib/em/file_watch.rb
- lib/em/future.rb
- lib/em/iterator.rb
- lib/em/pool.rb
- lib/em/process_watch.rb
- lib/em/processes.rb
- lib/em/protocols.rb
- lib/em/protocols/header_and_content.rb
- lib/em/protocols/httpclient.rb
- lib/em/protocols/httpclient2.rb
- lib/em/protocols/line_and_text.rb
- lib/em/protocols/line_protocol.rb
- lib/em/protocols/linetext2.rb
- lib/em/protocols/memcache.rb
- lib/em/protocols/object_protocol.rb
- lib/em/protocols/postgres3.rb
- lib/em/protocols/saslauth.rb
- lib/em/protocols/smtpclient.rb
- lib/em/protocols/smtpserver.rb
- lib/em/protocols/socks4.rb
- lib/em/protocols/stomp.rb
- lib/em/protocols/tcptest.rb
- lib/em/pure_ruby.rb
- lib/em/queue.rb
- lib/em/resolver.rb
- lib/em/spawnable.rb
- lib/em/streamer.rb
- lib/em/threaded_resource.rb
- lib/em/tick_loop.rb
- lib/em/timers.rb
- lib/eventmachine.rb

### Namespace

- MODULE EventMachine::DNS
- MODULE EventMachine::Deferrable
- MODULE EventMachine::Protocols
- MODULE EventMachine::UuidGenerator
- CLASS EventMachine::Channel
- CLASS EventMachine::Completion
- CLASS EventMachine::Connection
- CLASS EventMachine::DatagramObject
- CLASS EventMachine::DefaultDeferrable
- CLASS EventMachine::DeferrableChildProcess
- CLASS EventMachine::Error
- CLASS EventMachine::EvmaKeyboard
- CLASS EventMachine::EvmaTCPClient
- CLASS EventMachine::EvmaTCPServer
- CLASS EventMachine::EvmaUDPSocket
- CLASS EventMachine::EvmaUNIXClient
- CLASS EventMachine::EvmaUNIXServer
- CLASS EventMachine::FileNotFoundException
- CLASS EventMachine::FileStreamer
- CLASS EventMachine::FileWatch
- CLASS EventMachine::Iterator
- CLASS EventMachine::LoopbreakReader
- CLASS EventMachine::PeriodicTimer
- CLASS EventMachine::Pool
- CLASS EventMachine::ProcessWatch
- CLASS EventMachine::Queue
- CLASS EventMachine::Reactor
- CLASS EventMachine::Selectable
- CLASS EventMachine::SpawnedProcess
- CLASS EventMachine::StreamObject
- CLASS EventMachine::SystemCmd
- CLASS EventMachine::ThreadedResource
- CLASS EventMachine::TickLoop
- CLASS EventMachine::Timer
- CLASS EventMachine::YieldBlockFromSpawnedProcess

### Methods

- ::Callback
- ::_open_file_for_writing
- ::add_oneshot_timer
- ::add_periodic_timer
- ::add_shutdown_hook
- ::add_timer
- ::attach
- ::attach_io
- ::bind_connect
- ::bind_connect_server
- ::cancel_timer
- ::close_connection
- ::connect
- ::connect_server
- ::connect_unix_domain
- ::connect_unix_server
- ::connection_count
- ::defer
- ::defers_finished?
- ::disable_proxy
- ::enable_proxy
- ::epoll
- ::error_handler
- ::event_callback
- ::fork_reactor
- ::get_max_timers
- ::get_outbound_data_size
- ::get_peername
- ::get_sock_opt
- ::heartbeat_interval
- ::heartbeat_interval=
- ::initialize_event_machine
- ::klass_from_handler
- ::library_type
- ::next_tick
- ::open_datagram_socket
- ::open_keyboard
- ::open_udp_socket
- ::popen
- ::reactor_running?
- ::reactor_thread?
- ::read_keyboard
- ::reconnect
- ::release_machine
- ::run
- ::run_block
- ::run_deferred_callbacks
- ::run_machine
- ::schedule
- ::send_data
- ::send_datagram
- ::send_file_data
- ::set_comm_inactivity_timeout
- ::set_descriptor_table_size
- ::set_effective_user
- ::set_max_timer_count
- ::set_max_timers
- ::set_quantum
- ::set_rlimit_nofile
- ::set_sock_opt
- ::set_timer_quantum
- ::signal_loopbreak
- ::spawn
- ::spawn_threadpool
- ::ssl?
- ::start_server
- ::start_tcp_server
- ::start_unix_domain_server
- ::start_unix_server
- ::stop
- ::stop_event_loop
- ::stop_server
- ::stop_tcp_server
- ::system
- ::tick_loop
- ::watch
- ::watch_file
- ::watch_process
- ::yield
- ::yield_and_notify

### Files

- ChangeLog
- DEFERRABLES
- EPOLL
- INSTALL
- KEYBOARD
- LEGAL
- LIGHTWEIGHT_CONCURRENCY
- PURE_RUBY
- RELEASE_NOTES
- SMTP
- SPAWNED_PROCESSES
- TODO

### Class/Module Index

Quicksearch

- EventMachine
- EventMachine
- EventMachine::Channel
- EventMachine::Completion
- EventMachine::Connection
- EventMachine::DNS
- EventMachine::DNS::Request
- EventMachine::DNS::RequestIdAlreadyUsed
- EventMachine::DNS::Resolver
- EventMachine::DNS::Socket
- EventMachine::DatagramObject
- EventMachine::DefaultDeferrable
- EventMachine::Deferrable
- EventMachine::DeferrableChildProcess
- EventMachine::Error
- EventMachine::EvmaKeyboard
- EventMachine::EvmaTCPClient
- EventMachine::EvmaTCPServer
- EventMachine::EvmaUDPSocket
- EventMachine::EvmaUNIXClient
- EventMachine::EvmaUNIXServer
- EventMachine::FileNotFoundException
- EventMachine::FileStreamer
- EventMachine::FileWatch
- EventMachine::Iterator
- EventMachine::LoopbreakReader
- EventMachine::PeriodicTimer
- EventMachine::Pool
- EventMachine::ProcessWatch
- EventMachine::Protocols
- EventMachine::Protocols
- EventMachine::Protocols::HeaderAndContentProtocol
- EventMachine::Protocols::HttpClient
- EventMachine::Protocols::HttpClient2
- EventMachine::Protocols::HttpClient2::Request
- EventMachine::Protocols::LineAndTextProtocol
- EventMachine::Protocols::LineProtocol
- EventMachine::Protocols::LineText2
- EventMachine::Protocols::Memcache
- EventMachine::Protocols::Memcache::ParserError
- EventMachine::Protocols::ObjectProtocol
- EventMachine::Protocols::Postgres3
- EventMachine::Protocols::SASLauth
- EventMachine::Protocols::SASLauthclient
- EventMachine::Protocols::SmtpClient
- EventMachine::Protocols::SmtpServer
- EventMachine::Protocols::Socks4
- EventMachine::Protocols::Stomp
- EventMachine::Protocols::Stomp::Message
- EventMachine::Protocols::TcpConnectTester
- EventMachine::Queue
- EventMachine::Reactor
- EventMachine::Selectable
- EventMachine::SpawnedProcess
- EventMachine::StreamObject
- EventMachine::SystemCmd
- EventMachine::ThreadedResource
- EventMachine::TickLoop
- EventMachine::Timer
- EventMachine::UuidGenerator
- EventMachine::YieldBlockFromSpawnedProcess
- Object
- Object::EM
- Object::P
- BufferedTokenizer
- IO
- StringIO
- TestConnection

No matching classes.

# Object::EM

# EM::Completion

A completion is a callback container for various states of completion. In it's most basic form it has a start state and a finish state.

This implementation includes some hold-back from the EM::Deferrable interface in order to be compatible - but it has a much cleaner implementation.

In general it is preferred that this implementation be used as a state callback container than EM::DefaultDeferrable or other classes including EM::Deferrable. This is because it is generally more sane to keep this level of state in a dedicated state-back container. This generally leads to more malleable interfaces and software designs, as well as eradicating nasty bugs that result from abstraction leakage.

## Basic Usage

As already mentioned, the basic usage of a Completion is simply for its two final states, :succeeded and :failed.

An asynchronous operation will complete at some future point in time, and users often want to react to this event. API authors will want to expose some common interface to react to these events.

In the following example, the user wants to know when a short lived connection has completed its exchange with the remote server. The simple protocol just waits for an ack to its message.

    class Protocol < EM::Connection
      include EM::P::LineText2

      def initialize(message, completion)
        @message, @completion = message, completion
        @completion.completion { close_connection }
        @completion.timeout(1, :timeout)
      end

      def post_init
        send_data(@message)
      end

      def receive_line(line)
        case line
        when /ACK/i
          @completion.succeed line
        when /ERR/i
          @completion.fail :error, line
        else
          @completion.fail :unknown, line
        end
      end

      def unbind
        @completion.fail :disconnected unless @completion.completed?
      end
    end

    class API
      attr_reader :host, :port

      def initialize(host = 'example.org', port = 8000)
        @host, @port = host, port
      end

      def request(message)
        completion = EM::Deferrable::Completion.new
        EM.connect(host, port, Protocol, message, completion)
        completion
      end
    end

    api = API.new
    completion = api.request('stuff')
    completion.callback do |line|
      puts "API responded with: #{line}"
    end
    completion.errback do |type, line|
      case type
      when :error
        puts "API error: #{line}"
      when :unknown
        puts "API returned unknown response: #{line}"
      when :disconnected
        puts "API server disconnected prematurely"
      when :timeout
        puts "API server did not respond in a timely fashion"
      end
    end

## Advanced Usage

This completion implementation also supports more state callbacks and arbitrary states (unlike the original Deferrable API). This allows for basic stateful process encapsulation. One might use this to setup state callbacks for various states in an exchange like in the basic usage example, except where the applicaiton could be made to react to "connected" and "disconnected" states additionally.

    class Protocol < EM::Connection
      def initialize(completion)
        @response = []
        @completion = completion
        @completion.stateback(:disconnected) do
          @completion.succeed @response.join
        end
      end

      def connection_completed
        @host, @port = Socket.unpack_sockaddr_in get_peername
        @completion.change_state(:connected, @host, @port)
        send_data("GET http://example.org/ HTTP/1.0\r\n\r\n")
      end

      def receive_data(data)
        @response << data
      end

      def unbind
        @completion.change_state(:disconnected, @host, @port)
      end
    end

    completion = EM::Deferrable::Completion.new
    completion.stateback(:connected) do |host, port|
      puts "Connected to #{host}:#{port}"
    end
    completion.stateback(:disconnected) do |host, port|
      puts "Disconnected from #{host}:#{port}"
    end
    completion.callback do |response|
      puts response
    end

    EM.connect('example.org', 80, Protocol, completion)

## Timeout

The Completion also has a timeout. The timeout is global and is not aware of states apart from completion states. The timeout is only engaged if timeout is called, and it will call fail if it is reached.

## Completion states

By default there are two completion states, :succeeded and :failed. These states can be modified by subclassing and overrding the completion_states method. Completion states are special, in that callbacks for all completion states are explcitly cleared when a completion state is entered. This prevents errors that could arise from accidental unterminated timeouts, and other such user errors.

## Other notes

Several APIs have been carried over from EM::Deferrable for compatibility reasons during a transitionary period. Specifically cancel_errback and cancel_callback are implemented, but their usage is to be strongly discouraged. Due to the already complex nature of reaction systems, dynamic callback deletion only makes the problem much worse. It is always better to add correct conditionals to the callback code, or use more states, than to address such implementaiton issues with conditional callbacks.

@private

@private

Top-level EventMachine namespace. If you are looking for EventMachine examples, see {file:docs/GettingStarted.md EventMachine tutorial}.

## Key methods ## ### Starting and stopping the event loop ###

- {EventMachine.run}

- {EventMachine.stop_event_loop}

### Implementing clients ###

- {EventMachine.connect}

### Implementing servers ###

- {EventMachine.start_server}

### Working with timers ###

- {EventMachine.add_timer}

- {EventMachine.add_periodic_timer}

- {EventMachine.cancel_timer}

### Working with blocking tasks ###

- {EventMachine.defer}

- {EventMachine.next_tick}

### Efficient proxying ###

- {EventMachine.enable_proxy}

- {EventMachine.disable_proxy}

### Constants

ConnectionAccepted

  @private

ConnectionCompleted

  @private

ConnectionData

  @private

ConnectionUnbound

  @private

ERRNOS

  System errnos @private

LoopbreakSignalled

  @private

TimerFired

  @private

### Attributes

reactor_thread[R]

Exposed to allow joining on the thread, when run in a multithreaded environment. Performing other actions on the thread has undefined semantics (read: a dangerous endevor).

@return [Thread]

threadpool[R]

@private

threadpool_size[RW]

Size of the EventMachine.defer threadpool (defaults to 20) @return [Number]

### Public Class Methods

Callback(object = nil, method = nil, &blk) click to toggle source

Utility method for coercing arguments to an object that responds to :call. Accepts an object and a method name to send to, or a block, or an object that responds to :call.

@example EventMachine.Callback used with a block. Returns that block.

    cb = EventMachine.Callback do |msg|
      puts(msg)
    end
    # returned object is a callable
    cb.call('hello world')

@example EventMachine.Callback used with an object (to be more specific, class object) and a method name, returns an object that responds to call

    cb = EventMachine.Callback(Object, :puts)
    # returned object is a callable that delegates to Kernel#puts (in this case Object.puts)
    cb.call('hello world')

@example EventMachine.Callback used with an object that responds to call. Returns the argument.

    cb = EventMachine.Callback(proc{ |msg| puts(msg) })
    # returned object is a callable
    cb.call('hello world')

@overload Callback(object, method)

    Wraps `method` invocation on `object` into an object that responds to #call that proxies all the arguments to that method
    @param [Object] Object to invoke method on
    @param [Symbol] Method name
    @return [<#call>] An object that responds to #call that takes any number of arguments and invokes method on object with those arguments

@overload Callback(object)

    Returns callable object as is, without any coercion
    @param [<#call>] An object that responds to #call
    @return [<#call>] Its argument

@overload Callback(&block)

    Returns block passed to it without any coercion
    @return [<#call>] Block passed to this method

@raise [ArgumentError] When argument doesn't respond to call, method name is missing or when invoked without arguments and block isn't given

@return [<call>]

    # File lib/em/callback.rb, line 47
    def self.Callback(object = nil, method = nil, &blk)
      if object && method
        lambda { |*args| object.__send__ method, *args }
      else
        if object.respond_to? :call
          object
        else
          blk || raise(ArgumentError)
        end # if
      end # if
    end

_open_file_for_writing(filename, handler=nil) click to toggle source

@private

    # File lib/eventmachine.rb, line 1499
    def self._open_file_for_writing filename, handler=nil
      klass = klass_from_handler(Connection, handler)

      s = _write_file filename
      c = klass.new s
      @conns[s] = c
      block_given? and yield c
      c
    end

add_oneshot_timer(interval) click to toggle source

Changed 04Oct06: intervals from the caller are now in milliseconds, but our native-ruby processor still wants them in seconds. @private

    # File lib/em/pure_ruby.rb, line 56
    def add_oneshot_timer interval
      Reactor.instance.install_oneshot_timer(interval / 1000)
    end

add_periodic_timer(*args, &block) click to toggle source

Adds a periodic timer to the event loop. It takes the same parameters as the one-shot timer method, {EventMachine.add_timer}. This method schedules execution of the given block repeatedly, at intervals of time *at least* as great as the number of seconds given in the first parameter to the call.

@example Write a dollar-sign to stderr every five seconds, without blocking

    EventMachine.run {
      EventMachine.add_periodic_timer( 5 ) { $stderr.write "$" }
    }

@param [Integer] delay Delay in seconds

@see EventMachine::PeriodicTimer @see EventMachine.add_timer

    # File lib/eventmachine.rb, line 346
    def self.add_periodic_timer *args, &block
      interval = args.shift
      code = args.shift || block

      EventMachine::PeriodicTimer.new(interval, code)
    end

add_shutdown_hook(&block) click to toggle source

Adds a block to call as the reactor is shutting down.

These callbacks are called in the reverse order to which they are added.

@example Scheduling operations to be run when EventMachine event loop is stopped

    EventMachine.run do
      EventMachine.add_shutdown_hook { puts "b" }
      EventMachine.add_shutdown_hook { puts "a" }
      EventMachine.stop
    end

    # Outputs:
    #   a
    #   b

    # File lib/eventmachine.rb, line 286
    def self.add_shutdown_hook &block
      @tails << block
    end

add_timer(*args, &block) click to toggle source

Adds a one-shot timer to the event loop. Call it with one or two parameters. The first parameters is a delay-time expressed in seconds (not milliseconds). The second parameter, if present, must be an object that responds to :call. If 2nd parameter is not given, then you can also simply pass a block to the method call.

This method may be called from the block passed to {EventMachine.run} or from any callback method. It schedules execution of the proc or block passed to it, after the passage of an interval of time equal to *at least* the number of seconds specified in the first parameter to the call.

{EventMachine.add_timer} is a non-blocking method. Callbacks can and will be called during the interval of time that the timer is in effect. There is no built-in limit to the number of timers that can be outstanding at any given time.

@example Setting a one-shot timer with EventMachine

    EventMachine.run {
      puts "Starting the run now: #{Time.now}"
      EventMachine.add_timer 5, proc { puts "Executing timer event: #{Time.now}" }
      EventMachine.add_timer(10) { puts "Executing timer event: #{Time.now}" }
    }

@param [Integer] delay Delay in seconds @see EventMachine::Timer @see EventMachine.add_periodic_timer

    # File lib/eventmachine.rb, line 318
    def self.add_timer *args, &block
      interval = args.shift
      code = args.shift || block
      if code
        # check too many timers!
        s = add_oneshot_timer((interval.to_f * 1000).to_i)
        @timers[s] = code
        s
      end
    end

attach(io, handler=nil, *args, &blk) click to toggle source

Attaches an IO object or file descriptor to the eventloop as a regular connection. The file descriptor will be set as non-blocking, and EventMachine will process receive_data and send_data events on it as it would for any other connection.

To watch a fd instead, use {EventMachine.watch}, which will not alter the state of the socket and fire notify_readable and notify_writable events instead.

    # File lib/eventmachine.rb, line 727
    def EventMachine::attach io, handler=nil, *args, &blk
      attach_io io, false, handler, *args, &blk
    end

attach_io(io, watch_mode, handler=nil, *args) click to toggle source

@private

    # File lib/eventmachine.rb, line 732
    def EventMachine::attach_io io, watch_mode, handler=nil, *args
      klass = klass_from_handler(Connection, handler, *args)

      if !watch_mode and klass.public_instance_methods.any?{|m| [:notify_readable, :notify_writable].include? m.to_sym }
        raise ArgumentError, "notify_readable/writable with EM.attach is not supported. Use EM.watch(io){ |c| c.notify_readable = true }"
      end

      if io.respond_to?(:fileno)
        fd = defined?(JRuby) ? JRuby.runtime.getDescriptorByFileno(io.fileno).getChannel : io.fileno
      else
        fd = io
      end

      s = attach_fd fd, watch_mode
      c = klass.new s, *args

      c.instance_variable_set(:@io, io)
      c.instance_variable_set(:@watch_mode, watch_mode)
      c.instance_variable_set(:@fd, fd)

      @conns[s] = c
      block_given? and yield c
      c
    end

bind_connect(bind_addr, bind_port, server, port=nil, handler=nil, *args) click to toggle source

This method is like {EventMachine.connect}, but allows for a local address/port to bind the connection to.

@see EventMachine.connect

    # File lib/eventmachine.rb, line 647
    def self.bind_connect bind_addr, bind_port, server, port=nil, handler=nil, *args
      begin
        port = Integer(port)
      rescue ArgumentError, TypeError
        # there was no port, so server must be a unix domain socket
        # the port argument is actually the handler, and the handler is one of the args
        args.unshift handler if handler
        handler = port
        port = nil
      end if port

      klass = klass_from_handler(Connection, handler, *args)

      s = if port
            if bind_addr
              bind_connect_server bind_addr, bind_port.to_i, server, port
            else
              connect_server server, port
            end
          else
            connect_unix_server server
          end

      c = klass.new s, *args
      @conns[s] = c
      block_given? and yield c
      c
    end

bind_connect_server(bind_addr, bind_port, host, port) click to toggle source

@private

    # File lib/em/pure_ruby.rb, line 80
    def bind_connect_server bind_addr, bind_port, host, port
      EvmaTCPClient.connect(bind_addr, bind_port, host, port).uuid
    end

cancel_timer(timer_or_sig) click to toggle source

Cancel a timer (can be a callback or an {EventMachine::Timer} instance).

@param [cancel, call] timer_or_sig A timer to cancel @see EventMachine::Timer#cancel

    # File lib/eventmachine.rb, line 358
    def self.cancel_timer timer_or_sig
      if timer_or_sig.respond_to? :cancel
        timer_or_sig.cancel
      else
        @timers[timer_or_sig] = false if @timers.has_key?(timer_or_sig)
      end
    end

close_connection(target, after_writing) click to toggle source

The extension version does NOT raise any kind of an error if an attempt is made to close a non-existent connection. Not sure whether we should. For now, we'll raise an error here in that case. @private

    # File lib/em/pure_ruby.rb, line 95
    def close_connection target, after_writing
      selectable = Reactor.instance.get_selectable( target ) or raise "unknown close_connection target"
      selectable.schedule_close after_writing
    end

connect(server, port=nil, handler=nil, *args, &blk) click to toggle source

Initiates a TCP connection to a remote server and sets up event handling for the connection. {EventMachine.connect} requires event loop to be running (see {EventMachine.run}).

{EventMachine.connect} takes the IP address (or hostname) and port of the remote server you want to connect to. It also takes an optional handler (a module or a subclass of {EventMachine::Connection}) which you must define, that contains the callbacks that will be invoked by the event loop on behalf of the connection.

Learn more about connection lifecycle callbacks in the {file:docs/GettingStarted.md EventMachine tutorial} and {file:docs/ConnectionLifecycleCallbacks.md Connection lifecycle guide}.

@example

    # Here's a program which connects to a web server, sends a naive
    # request, parses the HTTP header of the response, and then
    # (antisocially) ends the event loop, which automatically drops the connection
    # (and incidentally calls the connection's unbind method).
    module DumbHttpClient
      def post_init
        send_data "GET / HTTP/1.1\r\nHost: _\r\n\r\n"
        @data = ""
        @parsed = false
      end

      def receive_data data
        @data << data
        if !@parsed and @data =~ /[\n][\r]*[\n]/m
          @parsed = true
          puts "RECEIVED HTTP HEADER:"
          $`.each {|line| puts ">>> #{line}" }

          puts "Now we'll terminate the loop, which will also close the connection"
          EventMachine::stop_event_loop
        end
      end

      def unbind
        puts "A connection has terminated"
      end
    end

    EventMachine.run {
      EventMachine.connect "www.bayshorenetworks.com", 80, DumbHttpClient
    }
    puts "The event loop has ended"

@example Defining protocol handler as a class

    class MyProtocolHandler < EventMachine::Connection
      def initialize *args
        super
        # whatever else you want to do here
      end

      # ...
    end

@param [String] server Host to connect to @param [Integer] port Port to connect to @param [Module, Class] handler A module or class that implements connection lifecycle callbacks

@see EventMachine.start_server @see file:docs/GettingStarted.md EventMachine tutorial

    # File lib/eventmachine.rb, line 617
    def self.connect server, port=nil, handler=nil, *args, &blk
      # EventMachine::connect initiates a TCP connection to a remote
      # server and sets up event-handling for the connection.
      # It internally creates an object that should not be handled
      # by the caller. HOWEVER, it's often convenient to get the
      # object to set up interfacing to other objects in the system.
      # We return the newly-created anonymous-class object to the caller.
      # It's expected that a considerable amount of code will depend
      # on this behavior, so don't change it.
      #
      # Ok, added support for a user-defined block, 13Apr06.
      # This leads us to an interesting choice because of the
      # presence of the post_init call, which happens in the
      # initialize method of the new object. We call the user's
      # block and pass the new object to it. This is a great
      # way to do protocol-specific initiation. It happens
      # AFTER post_init has been called on the object, which I
      # certainly hope is the right choice.
      # Don't change this lightly, because accepted connections
      # are different from connected ones and we don't want
      # to have them behave differently with respect to post_init
      # if at all possible.

      bind_connect nil, nil, server, port, handler, *args, &blk
    end

connect_server(host, port) click to toggle source

@private

    # File lib/em/pure_ruby.rb, line 75
    def connect_server host, port
      bind_connect_server nil, nil, host, port
    end

connect_unix_domain(socketname, *args, &blk) click to toggle source

Make a connection to a Unix-domain socket. This method is simply an alias for {.connect}, which can connect to both TCP and Unix-domain sockets. Make sure that your process has sufficient permissions to open the socket it is given.

@param [String] socketname Unix domain socket (local fully-qualified path) you want to connect to.

@note UNIX sockets, as the name suggests, are not available on Microsoft Windows.

    # File lib/eventmachine.rb, line 794
    def self.connect_unix_domain socketname, *args, &blk
      connect socketname, *args, &blk
    end

connect_unix_server(chain) click to toggle source

@private

    # File lib/em/pure_ruby.rb, line 119
    def connect_unix_server chain
      EvmaUNIXClient.connect(chain).uuid
    end

connection_count() click to toggle source

Returns the total number of connections (file descriptors) currently held by the reactor. Note that a tick must pass after the 'initiation' of a connection for this number to increment. It's usually accurate, but don't rely on the exact precision of this number unless you really know EM internals.

@example

    EventMachine.run {
      EventMachine.connect("rubyeventmachine.com", 80)
      # count will be 0 in this case, because connection is not
      # established yet
      count = EventMachine.connection_count
    }

@example

    EventMachine.run {
      EventMachine.connect("rubyeventmachine.com", 80)

      EventMachine.next_tick {
        # In this example, count will be 1 since the connection has been established in
        # the next loop of the reactor.
        count = EventMachine.connection_count
      }
    }

@return [Integer] Number of connections currently held by the reactor.

    # File lib/eventmachine.rb, line 936
    def self.connection_count
      self.get_connection_count
    end

defer(op = nil, callback = nil, &blk) click to toggle source

EventMachine.defer is used for integrating blocking operations into EventMachine's control flow. The action of {.defer} is to take the block specified in the first parameter (the "operation") and schedule it for asynchronous execution on an internal thread pool maintained by EventMachine. When the operation completes, it will pass the result computed by the block (if any) back to the EventMachine reactor. Then, EventMachine calls the block specified in the second parameter to {.defer} (the "callback"), as part of its normal event handling loop. The result computed by the operation block is passed as a parameter to the callback. You may omit the callback parameter if you don't need to execute any code after the operation completes.

## Caveats ##

Note carefully that the code in your deferred operation will be executed on a separate thread from the main EventMachine processing and all other Ruby threads that may exist in your program. Also, multiple deferred operations may be running at once! Therefore, you are responsible for ensuring that your operation code is threadsafe.

Don't write a deferred operation that will block forever. If so, the current implementation will not detect the problem, and the thread will never be returned to the pool. EventMachine limits the number of threads in its pool, so if you do this enough times, your subsequent deferred operations won't get a chance to run.

@example

    operation = proc {
      # perform a long-running operation here, such as a database query.
      "result" # as usual, the last expression evaluated in the block will be the return value.
    }
    callback = proc {|result|
      # do something with result here, such as send it back to a network client.
    }

    EventMachine.defer(operation, callback)

@param [call] op An operation you want to offload to EventMachine thread pool @param [call] callback A callback that will be run on the event loop thread after `operation` finishes.

@see EventMachine.threadpool_size

    # File lib/eventmachine.rb, line 1009
    def self.defer op = nil, callback = nil, &blk
      # OBSERVE that #next_tick hacks into this mechanism, so don't make any changes here
      # without syncing there.
      #
      # Running with $VERBOSE set to true gives a warning unless all ivars are defined when
      # they appear in rvalues. But we DON'T ever want to initialize @threadqueue unless we
      # need it, because the Ruby threads are so heavyweight. We end up with this bizarre
      # way of initializing @threadqueue because EventMachine is a Module, not a Class, and
      # has no constructor.

      unless @threadpool
        @threadpool = []
        @threadqueue = ::Queue.new
        @resultqueue = ::Queue.new
        spawn_threadpool
      end

      @threadqueue << [op||blk,callback]
    end

defers_finished?() click to toggle source

Returns `true` if all deferred actions are done executing and their callbacks have been fired.

    # File lib/eventmachine.rb, line 1051
    def self.defers_finished?
      return false if @threadpool and !@all_threads_spawned
      return false if @threadqueue and not @threadqueue.empty?
      return false if @resultqueue and not @resultqueue.empty?
      return false if @threadpool and @threadqueue.num_waiting != @threadpool.size
      return true
    end

disable_proxy(from) click to toggle source

Takes just one argument, a {Connection} that has proxying enabled via {EventMachine.enable_proxy}. Calling this method will remove that functionality and your connection will begin receiving data via {Connection#receive_data} again.

@param [EventMachine::Connection] from Source of data that is being proxied @see EventMachine.enable_proxy

    # File lib/eventmachine.rb, line 1396
    def self.disable_proxy(from)
      EM::stop_proxy(from.signature)
    end

enable_proxy(from, to, bufsize=0, length=0) click to toggle source

This method allows for direct writing of incoming data back out to another descriptor, at the C++ level in the reactor. This is very efficient and especially useful for proxies where high performance is required. Propogating data from a server response all the way up to Ruby, and then back down to the reactor to be sent back to the client, is often unnecessary and incurs a significant performance decrease.

The two arguments are instance of {EventMachine::Connection} subclasses, 'from' and 'to'. 'from' is the connection whose inbound data you want relayed back out. 'to' is the connection to write it to.

Once you call this method, the 'from' connection will no longer get receive_data callbacks from the reactor, except in the case that 'to' connection has already closed when attempting to write to it. You can see in the example, that proxy_target_unbound will be called when this occurs. After that, further incoming data will be passed into receive_data as normal.

Note also that this feature supports different types of descriptors: TCP, UDP, and pipes. You can relay data from one kind to another, for example, feed a pipe from a UDP stream.

@example

    module ProxyConnection
      def initialize(client, request)
        @client, @request = client, request
      end

      def post_init
        EM::enable_proxy(self, @client)
      end

      def connection_completed
        send_data @request
      end

      def proxy_target_unbound
        close_connection
      end

      def unbind
        @client.close_connection_after_writing
      end
    end

    module ProxyServer
      def receive_data(data)
        (@buf ||= "") << data
        if @buf =~ /\r\n\r\n/ # all http headers received
          EventMachine.connect("10.0.0.15", 80, ProxyConnection, self, data)
        end
      end
    end

    EventMachine.run {
      EventMachine.start_server("127.0.0.1", 8080, ProxyServer)
    }

@param [EventMachine::Connection] from Source of data to be proxies/streamed. @param [EventMachine::Connection] to Destination of data to be proxies/streamed. @param [Integer] bufsize Buffer size to use @param [Integer] length Maximum number of bytes to proxy.

@see EventMachine.disable_proxy

    # File lib/eventmachine.rb, line 1386
    def self.enable_proxy(from, to, bufsize=0, length=0)
      EM::start_proxy(from.signature, to.signature, bufsize, length)
    end

epoll() click to toggle source

This method is a harmless no-op in the pure-Ruby implementation. This is intended to ensure that user code behaves properly across different EM implementations. @private

    # File lib/em/pure_ruby.rb, line 158
    def epoll
    end

error_handler(cb = nil, &blk) click to toggle source

Catch-all for errors raised during event loop callbacks.

@example

    EventMachine.error_handler{ |e|
      puts "Error raised during event loop: #{e.message}"
    }

@param [call] cb Global catch-all errback

    # File lib/eventmachine.rb, line 1319
    def self.error_handler cb = nil, &blk
      if cb or blk
        @error_handler = cb || blk
      elsif instance_variable_defined? :@error_handler
        remove_instance_variable :@error_handler
      end
    end

event_callback(conn_binding, opcode, data) click to toggle source

@private

    # File lib/eventmachine.rb, line 1419
    def self.event_callback conn_binding, opcode, data
      #
      # Changed 27Dec07: Eliminated the hookable error handling.
      # No one was using it, and it degraded performance significantly.
      # It's in original_event_callback, which is dead code.
      #
      # Changed 25Jul08: Added a partial solution to the problem of exceptions
      # raised in user-written event-handlers. If such exceptions are not caught,
      # we must cause the reactor to stop, and then re-raise the exception.
      # Otherwise, the reactor doesn't stop and it's left on the call stack.
      # This is partial because we only added it to #unbind, where it's critical
      # (to keep unbind handlers from being re-entered when a stopping reactor
      # runs down open connections). It should go on the other calls to user
      # code, but the performance impact may be too large.
      #
      if opcode == ConnectionUnbound
        if c = @conns.delete( conn_binding )
          begin
            if c.original_method(:unbind).arity != 0
              c.unbind(data == 0 ? nil : EventMachine::ERRNOS[data])
            else
              c.unbind
            end
            # If this is an attached (but not watched) connection, close the underlying io object.
            if c.instance_variable_defined?(:@io) and !c.instance_variable_get(:@watch_mode)
              io = c.instance_variable_get(:@io)
              begin
                io.close
              rescue Errno::EBADF, IOError
              end
            end
          rescue
            @wrapped_exception = $!
            stop
          end
        elsif c = @acceptors.delete( conn_binding )
          # no-op
        else
          if $! # Bubble user generated errors.
            @wrapped_exception = $!
            EM.stop
          else
            raise ConnectionNotBound, "received ConnectionUnbound for an unknown signature: #{conn_binding}"
          end
        end
      elsif opcode == ConnectionAccepted
        accep,args,blk = @acceptors[conn_binding]
        raise NoHandlerForAcceptedConnection unless accep
        c = accep.new data, *args
        @conns[data] = c
        blk and blk.call(c)
        c # (needed?)
        ##
        # The remaining code is a fallback for the pure ruby and java reactors.
        # In the C++ reactor, these events are handled in the C event_callback() in rubymain.cpp
      elsif opcode == ConnectionCompleted
        c = @conns[conn_binding] or raise ConnectionNotBound, "received ConnectionCompleted for unknown signature: #{conn_binding}"
        c.connection_completed
      elsif opcode == TimerFired
        t = @timers.delete( data )
        return if t == false # timer cancelled
        t or raise UnknownTimerFired, "timer data: #{data}"
        t.call
      elsif opcode == ConnectionData
        c = @conns[conn_binding] or raise ConnectionNotBound, "received data #{data} for unknown signature: #{conn_binding}"
        c.receive_data data
      elsif opcode == LoopbreakSignalled
        run_deferred_callbacks
      elsif opcode == ConnectionNotifyReadable
        c = @conns[conn_binding] or raise ConnectionNotBound
        c.notify_readable
      elsif opcode == ConnectionNotifyWritable
        c = @conns[conn_binding] or raise ConnectionNotBound
        c.notify_writable
      end
    end

fork_reactor(&block) click to toggle source

Forks a new process, properly stops the reactor and then calls {EventMachine.run} inside of it again, passing your block.

    # File lib/eventmachine.rb, line 255
    def self.fork_reactor &block
      # This implementation is subject to change, especially if we clean up the relationship
      # of EM#run to @reactor_running.
      # Original patch by Aman Gupta.
      #
      Kernel.fork do
        if self.reactor_running?
          self.stop_event_loop
          self.release_machine
          @reactor_running = false
        end
        self.run block
      end
    end

get_max_timers() click to toggle source

Gets the current maximum number of allowed timers

@return [Integer] Maximum number of timers that may be outstanding at any given time

    # File lib/eventmachine.rb, line 905
    def self.get_max_timers
      get_max_timer_count
    end

get_outbound_data_size(sig) click to toggle source

@private

    # File lib/em/pure_ruby.rb, line 206
    def get_outbound_data_size sig
      r = Reactor.instance.get_selectable( sig ) or raise "unknown get_outbound_data_size target"
      r.get_outbound_data_size
    end

get_peername(sig) click to toggle source

@private

    # File lib/em/pure_ruby.rb, line 129
    def get_peername sig
      selectable = Reactor.instance.get_selectable( sig ) or raise "unknown get_peername target"
      selectable.get_peername
    end

get_sock_opt(signature, level, optname) click to toggle source

@private

    # File lib/em/pure_ruby.rb, line 181
    def get_sock_opt signature, level, optname
      selectable = Reactor.instance.get_selectable( signature ) or raise "unknown get_peername target"
      selectable.getsockopt level, optname
    end

heartbeat_interval() click to toggle source

Retrieve the heartbeat interval. This is how often EventMachine will check for dead connections that have had an inactivity timeout set via {Connection#set_comm_inactivity_timeout}. Default is 2 seconds.

@return [Integer] Heartbeat interval, in seconds

    # File lib/eventmachine.rb, line 1405
    def self.heartbeat_interval
      EM::get_heartbeat_interval
    end

heartbeat_interval=(time) click to toggle source

Set the heartbeat interval. This is how often EventMachine will check for dead connections that have had an inactivity timeout set via {Connection#set_comm_inactivity_timeout}. Takes a Numeric number of seconds. Default is 2.

@param [Integer] time Heartbeat interval, in seconds

    # File lib/eventmachine.rb, line 1414
    def self.heartbeat_interval=(time)
      EM::set_heartbeat_interval time.to_f
    end

initialize_event_machine() click to toggle source

@private

    # File lib/em/pure_ruby.rb, line 49
    def initialize_event_machine
      Reactor.instance.initialize_for_run
    end

klass_from_handler(klass = Connection, handler = nil, *args) click to toggle source

@private

    # File lib/eventmachine.rb, line 1510
    def self.klass_from_handler(klass = Connection, handler = nil, *args)
      klass = if handler and handler.is_a?(Class)
        raise ArgumentError, "must provide module or subclass of #{klass.name}" unless klass >= handler
        handler
      elsif handler
        begin
          handler::EM_CONNECTION_CLASS
        rescue NameError
          handler::const_set(:EM_CONNECTION_CLASS, Class.new(klass) {include handler})
        end
      else
        klass
      end

      arity = klass.instance_method(:initialize).arity
      expected = arity >= 0 ? arity : -(arity + 1)
      if (arity >= 0 and args.size != expected) or (arity < 0 and args.size < expected)
        raise ArgumentError, "wrong number of arguments for #{klass}#initialize (#{args.size} for #{expected})"
      end

      klass
    end

library_type() click to toggle source

This is mostly useful for automated tests. Return a distinctive symbol so the caller knows whether he's dealing with an extension or with a pure-Ruby library. @private

    # File lib/em/pure_ruby.rb, line 44
    def library_type
      :pure_ruby
    end

next_tick(pr=nil, &block) click to toggle source

Schedules a proc for execution immediately after the next "turn" through the reactor core. An advanced technique, this can be useful for improving memory management and/or application responsiveness, especially when scheduling large amounts of data for writing to a network connection.

This method takes either a single argument (which must be a callable object) or a block.

@param [call] pr A callable object to run

    # File lib/eventmachine.rb, line 1077
    def self.next_tick pr=nil, &block
      # This works by adding to the @resultqueue that's used for #defer.
      # The general idea is that next_tick is used when we want to give the reactor a chance
      # to let other operations run, either to balance the load out more evenly, or to let
      # outbound network buffers drain, or both. So we probably do NOT want to block, and
      # we probably do NOT want to be spinning any threads. A program that uses next_tick
      # but not #defer shouldn't suffer the penalty of having Ruby threads running. They're
      # extremely expensive even if they're just sleeping.

      raise ArgumentError, "no proc or block given" unless ((pr && pr.respond_to?(:call)) or block)
      @next_tick_mutex.synchronize do
        @next_tick_queue << ( pr || block )
      end
      signal_loopbreak if reactor_running?
    end

open_datagram_socket(address, port, handler=nil, *args) click to toggle source

Used for UDP-based protocols. Its usage is similar to that of {EventMachine.start_server}.

This method will create a new UDP (datagram) socket and bind it to the address and port that you specify. The normal callbacks (see {EventMachine.start_server}) will be called as events of interest occur on the newly-created socket, but there are some differences in how they behave.

{Connection#receive_data} will be called when a datagram packet is received on the socket, but unlike TCP sockets, the message boundaries of the received data will be respected. In other words, if the remote peer sent you a datagram of a particular size, you may rely on {Connection#receive_data} to give you the exact data in the packet, with the original data length. Also observe that Connection#receive_data may be called with a zero-length data payload, since empty datagrams are permitted in UDP.

{Connection#send_data} is available with UDP packets as with TCP, but there is an important difference. Because UDP communications are connectionless, there is no implicit recipient for the packets you send. Ordinarily you must specify the recipient for each packet you send. However, EventMachine provides for the typical pattern of receiving a UDP datagram from a remote peer, performing some operation, and then sending one or more packets in response to the same remote peer. To support this model easily, just use {Connection#send_data} in the code that you supply for {Connection#receive_data}.

EventMachine will provide an implicit return address for any messages sent to {Connection#send_data} within the context of a {Connection#receive_data} callback, and your response will automatically go to the correct remote peer.

Observe that the port number that you supply to {EventMachine.open_datagram_socket} may be zero. In this case, EventMachine will create a UDP socket that is bound to an [ephemeral port](en.wikipedia.org/wiki/Ephemeral_port). This is not appropriate for servers that must publish a well-known port to which remote peers may send datagrams. But it can be useful for clients that send datagrams to other servers. If you do this, you will receive any responses from the remote servers through the normal {Connection#receive_data} callback. Observe that you will probably have issues with firewalls blocking the ephemeral port numbers, so this technique is most appropriate for LANs.

If you wish to send datagrams to arbitrary remote peers (not necessarily ones that have sent data to which you are responding), then see {Connection#send_datagram}.

DO NOT call send_data from a datagram socket outside of a {Connection#receive_data} method. Use {Connection#send_datagram}. If you do use {Connection#send_data} outside of a {Connection#receive_data} method, you'll get a confusing error because there is no "peer," as send_data requires (inside of {EventMachine::Connection#receive_data}, {EventMachine::Connection#send_data} "fakes" the peer as described above).

@param [String] address IP address @param [String] port Port @param [Class, Module] handler A class or a module that implements connection lifecycle callbacks.

    # File lib/eventmachine.rb, line 853
    def self.open_datagram_socket address, port, handler=nil, *args
      # Replaced the implementation on 01Oct06. Thanks to Tobias Gustafsson for pointing
      # out that this originally did not take a class but only a module.

      klass = klass_from_handler(Connection, handler, *args)
      s = open_udp_socket address, port.to_i
      c = klass.new s, *args
      @conns[s] = c
      block_given? and yield c
      c
    end

open_keyboard(handler=nil, *args) click to toggle source

(Experimental)

@private

    # File lib/eventmachine.rb, line 1191
    def self.open_keyboard handler=nil, *args
      klass = klass_from_handler(Connection, handler, *args)

      s = read_keyboard
      c = klass.new s, *args
      @conns[s] = c
      block_given? and yield c
      c
    end

open_udp_socket(host, port) click to toggle source

@private

    # File lib/em/pure_ruby.rb, line 135
    def open_udp_socket host, port
      EvmaUDPSocket.create(host, port).uuid
    end

popen(cmd, handler=nil, *args) click to toggle source

Runs an external process.

@example

    module RubyCounter
      def post_init
        # count up to 5
        send_data "5\n"
      end
      def receive_data data
        puts "ruby sent me: #{data}"
      end
      def unbind
        puts "ruby died with exit status: #{get_status.exitstatus}"
      end
    end

    EventMachine.run {
      EventMachine.popen("ruby -e' $stdout.sync = true; gets.to_i.times{ |i| puts i+1; sleep 1 } '", RubyCounter)
    }

@note This method is not supported on Microsoft Windows @see EventMachine::DeferrableChildProcess @see EventMachine.system

    # File lib/eventmachine.rb, line 1154
    def self.popen cmd, handler=nil, *args
      # At this moment, it's only available on Unix.
      # Perhaps misnamed since the underlying function uses socketpair and is full-duplex.

      klass = klass_from_handler(Connection, handler, *args)
      w = case cmd
          when Array
            cmd
          when String
            Shellwords::shellwords( cmd )
          end
      w.unshift( w.first ) if w.first
      s = invoke_popen( w )
      c = klass.new s, *args
      @conns[s] = c
      yield(c) if block_given?
      c
    end

reactor_running?() click to toggle source

Tells you whether the EventMachine reactor loop is currently running.

Useful when writing libraries that want to run event-driven code, but may be running in programs that are already event-driven. In such cases, if {EventMachine.reactor_running?} returns false, your code can invoke {EventMachine.run} and run your application code inside the block passed to that method. If this method returns true, just execute your event-aware code.

@return [Boolean] true if the EventMachine reactor loop is currently running

    # File lib/eventmachine.rb, line 1183
    def self.reactor_running?
      (@reactor_running || false)
    end

reactor_thread?() click to toggle source

@return [Boolean] true if the calling thread is the same thread as the reactor.

    # File lib/eventmachine.rb, line 239
    def self.reactor_thread?
      Thread.current == @reactor_thread
    end

read_keyboard() click to toggle source

@private

    # File lib/em/pure_ruby.rb, line 212
    def read_keyboard
      EvmaKeyboard.open.uuid
    end

reconnect(server, port, handler) click to toggle source

Connect to a given host/port and re-use the provided {EventMachine::Connection} instance. Consider also {EventMachine::Connection#reconnect}.

@see EventMachine::Connection#reconnect

    # File lib/eventmachine.rb, line 762
    def self.reconnect server, port, handler
      # Observe, the test for already-connected FAILS if we call a reconnect inside post_init,
      # because we haven't set up the connection in @conns by that point.
      # RESIST THE TEMPTATION to "fix" this problem by redefining the behavior of post_init.
      #
      # Changed 22Nov06: if called on an already-connected handler, just return the
      # handler and do nothing more. Originally this condition raised an exception.
      # We may want to change it yet again and call the block, if any.

      raise "invalid handler" unless handler.respond_to?(:connection_completed)
      #raise "still connected" if @conns.has_key?(handler.signature)
      return handler if @conns.has_key?(handler.signature)

      s = if port
            connect_server server, port
          else
            connect_unix_server server
          end
      handler.signature = s
      @conns[s] = handler
      block_given? and yield handler
      handler
    end

release_machine() click to toggle source

@private

    # File lib/em/pure_ruby.rb, line 66
    def release_machine
    end

run(blk=nil, tail=nil, &block) click to toggle source

Initializes and runs an event loop. This method only returns if code inside the block passed to this method calls {EventMachine.stop_event_loop}. The block is executed after initializing its internal event loop but before running the loop, therefore this block is the right place to call any code that needs event loop to run, for example, {EventMachine.start_server}, {EventMachine.connect} or similar methods of libraries that use EventMachine under the hood (like `EventMachine::HttpRequest.new` or `AMQP.start`).

Programs that are run for long periods of time (e.g. servers) usually start event loop by calling {EventMachine.run}, and let it run "forever". It's also possible to use {EventMachine.run} to make a single client-connection to a remote server, process the data flow from that single connection, and then call {EventMachine.stop_event_loop} to stop, in other words, to run event loop for a short period of time (necessary to complete some operation) and then shut it down.

Once event loop is running, it is perfectly possible to start multiple servers and clients simultaneously: content-aware proxies like [Proxymachine](github.com/mojombo/proxymachine) do just that.

## Using EventMachine with Ruby on Rails and other Web application frameworks ##

Standalone applications often run event loop on the main thread, thus blocking for their entire lifespan. In case of Web applications, if you are running an EventMachine-based app server such as [Thin](code.macournoyer.com/thin/) or [Goliath](github.com/postrank-labs/goliath/), they start event loop for you. Servers like Unicorn, Apache Passenger or Mongrel occupy main Ruby thread to serve HTTP(S) requests. This means that calling {EventMachine.run} on the same thread is not an option (it will result in Web server never binding to the socket). In that case, start event loop in a separate thread as demonstrated below.

@example Starting EventMachine event loop in the current thread to run the "Hello, world"-like Echo server example

    #!/usr/bin/env ruby

    require 'rubygems' # or use Bundler.setup
    require 'eventmachine'

    class EchoServer < EM::Connection
      def receive_data(data)
        send_data(data)
      end
    end

    EventMachine.run do
      EventMachine.start_server("0.0.0.0", 10000, EchoServer)
    end

@example Starting EventMachine event loop in a separate thread

    # doesn't block current thread, can be used with Ruby on Rails, Sinatra, Merb, Rack
    # and any other application server that occupies main Ruby thread.
    Thread.new { EventMachine.run }

@note This method blocks calling thread. If you need to start EventMachine event loop from a Web app

    running on a non event-driven server (Unicorn, Apache Passenger, Mongrel), do it in a separate thread like demonstrated
    in one of the examples.

@see file:docs/GettingStarted.md Getting started with EventMachine @see EventMachine.stop_event_loop

    # File lib/eventmachine.rb, line 149
    def self.run blk=nil, tail=nil, &block
      # Obsoleted the use_threads mechanism.
      # 25Nov06: Added the begin/ensure block. We need to be sure that release_machine
      # gets called even if an exception gets thrown within any of the user code
      # that the event loop runs. The best way to see this is to run a unit
      # test with two functions, each of which calls {EventMachine.run} and each of
      # which throws something inside of #run. Without the ensure, the second test
      # will start without release_machine being called and will immediately throw

      #
      if reactor_running? and @reactor_pid != Process.pid
        # Reactor was started in a different parent, meaning we have forked.
        # Clean up reactor state so a new reactor boots up in this child.
        stop_event_loop
        release_machine
        @reactor_running = false
      end

      tail and @tails.unshift(tail)

      if reactor_running?
        (b = blk || block) and b.call # next_tick(b)
      else
        @conns = {}
        @acceptors = {}
        @timers = {}
        @wrapped_exception = nil
        @next_tick_queue ||= []
        @tails ||= []
        begin
          @reactor_pid = Process.pid
          @reactor_running = true
          initialize_event_machine
          (b = blk || block) and add_timer(0, b)
          if @next_tick_queue && !@next_tick_queue.empty?
            add_timer(0) { signal_loopbreak }
          end
          @reactor_thread = Thread.current
          run_machine
        ensure
          until @tails.empty?
            @tails.pop.call
          end

          begin
            release_machine
          ensure
            if @threadpool
              @threadpool.each { |t| t.exit }
              @threadpool.each do |t|
                next unless t.alive?
                begin
                  # Thread#kill! does not exist on 1.9 or rbx, and raises
                  # NotImplemented on jruby
                  t.kill!
                rescue NoMethodError, NotImplementedError
                  t.kill
                  # XXX t.join here?
                end
              end
              @threadqueue = nil
              @resultqueue = nil
              @threadpool = nil
              @all_threads_spawned = false
            end

            @next_tick_queue = []
          end
          @reactor_running = false
          @reactor_thread = nil
        end

        raise @wrapped_exception if @wrapped_exception
      end
    end

run_block(&block) click to toggle source

Sugars a common use case. Will pass the given block to run, but will terminate the reactor loop and exit the function as soon as the code in the block completes. (Normally, {EventMachine.run} keeps running indefinitely, even after the block supplied to it finishes running, until user code calls {EventMachine.stop})

    # File lib/eventmachine.rb, line 230
    def self.run_block &block
      pr = proc {
        block.call
        EventMachine::stop
      }
      run(&pr)
    end

run_deferred_callbacks() click to toggle source

The is the responder for the loopback-signalled event. It can be fired either by code running on a separate thread ({EventMachine.defer}) or on the main thread ({EventMachine.next_tick}). It will often happen that a next_tick handler will reschedule itself. We consume a copy of the tick queue so that tick events scheduled by tick events have to wait for the next pass through the reactor core.

@private

    # File lib/eventmachine.rb, line 948
    def self.run_deferred_callbacks
      until (@resultqueue ||= []).empty?
        result,cback = @resultqueue.pop
        cback.call result if cback
      end

      # Capture the size at the start of this tick...
      size = @next_tick_mutex.synchronize { @next_tick_queue.size }
      size.times do |i|
        callback = @next_tick_mutex.synchronize { @next_tick_queue.shift }
        begin
          callback.call
        ensure
          # This is a little nasty. The problem is, if an exception occurs during
          # the callback, then we need to send a signal to the reactor to actually
          # do some work during the next_tick. The only mechanism we have from the
          # ruby side is next_tick itself, although ideally, we'd just drop a byte
          # on the loopback descriptor.
          EM.next_tick {} if $!
        end
      end
    end

run_machine() click to toggle source

@private

    # File lib/em/pure_ruby.rb, line 61
    def run_machine
      Reactor.instance.run
    end

schedule(*a, &b) click to toggle source

Runs the given callback on the reactor thread, or immediately if called from the reactor thread. Accepts the same arguments as {EventMachine::Callback}

    # File lib/eventmachine.rb, line 245
    def self.schedule(*a, &b)
      cb = Callback(*a, &b)
      if reactor_running? && reactor_thread?
        cb.call
      else
        next_tick { cb.call }
      end
    end

send_data(target, data, datalength) click to toggle source

@private

    # File lib/em/pure_ruby.rb, line 85
    def send_data target, data, datalength
      selectable = Reactor.instance.get_selectable( target ) or raise "unknown send_data target"
      selectable.send_data data
    end

send_datagram(target, data, datalength, host, port) click to toggle source

This is currently only for UDP! We need to make it work with unix-domain sockets as well. @private

    # File lib/em/pure_ruby.rb, line 142
    def send_datagram target, data, datalength, host, port
      selectable = Reactor.instance.get_selectable( target ) or raise "unknown send_data target"
      selectable.send_datagram data, Socket::pack_sockaddr_in(port, host)
    end

send_file_data(sig, filename) click to toggle source

@private

    # File lib/em/pure_ruby.rb, line 193
    def send_file_data sig, filename
      sz = File.size(filename)
      raise "file too large" if sz > 32*1024
      data =
        begin
          File.read filename
        rescue
          ""
        end
      send_data sig, data, data.length
    end

set_comm_inactivity_timeout(sig, tm) click to toggle source

@private

    # File lib/em/pure_ruby.rb, line 217
    def set_comm_inactivity_timeout sig, tm
      r = Reactor.instance.get_selectable( sig ) or raise "unknown set_comm_inactivity_timeout target"
      r.set_inactivity_timeout tm
    end

set_descriptor_table_size(n_descriptors=nil) click to toggle source

Sets the maximum number of file or socket descriptors that your process may open. If you call this method with no arguments, it will simply return the current size of the descriptor table without attempting to change it.

The new limit on open descriptors *only* applies to sockets and other descriptors that belong to EventMachine. It has **no effect** on the number of descriptors you can create in ordinary Ruby code.

Not available on all platforms. Increasing the number of descriptors beyond its default limit usually requires superuser privileges. (See {.set_effective_user} for a way to drop superuser privileges while your program is running.)

@param [Integer] n_descriptors The maximum number of file or socket descriptors that your process may open @return [Integer] The new descriptor table size.

    # File lib/eventmachine.rb, line 1124
    def self.set_descriptor_table_size n_descriptors=nil
      EventMachine::set_rlimit_nofile n_descriptors
    end

set_effective_user(username) click to toggle source

A wrapper over the setuid system call. Particularly useful when opening a network server on a privileged port because you can use this call to drop privileges after opening the port. Also very useful after a call to {.set_descriptor_table_size}, which generally requires that you start your process with root privileges.

This method is intended for use in enforcing security requirements, consequently it will throw a fatal error and end your program if it fails.

@param [String] username The effective name of the user whose privilege-level your process should attain.

@note This method has no effective implementation on Windows or in the pure-Ruby

    implementation of EventMachine

    # File lib/eventmachine.rb, line 1105
    def self.set_effective_user username
      EventMachine::setuid_string username
    end

set_max_timer_count(n) click to toggle source

This method is a harmless no-op in pure Ruby, which doesn't have a built-in limit on the number of available timers. @private

    # File lib/em/pure_ruby.rb, line 177
    def set_max_timer_count n
    end

set_max_timers(ct) click to toggle source

Sets the maximum number of timers and periodic timers that may be outstanding at any given time. You only need to call {.set_max_timers} if you need more than the default number of timers, which on most platforms is 1000.

@note This method has to be used before event loop is started.

@param [Integer] ct Maximum number of timers that may be outstanding at any given time

@see EventMachine.add_timer @see EventMachine.add_periodic_timer @see EventMachine::Timer

    # File lib/eventmachine.rb, line 898
    def self.set_max_timers ct
      set_max_timer_count ct
    end

set_quantum(mills) click to toggle source

For advanced users. This function sets the default timer granularity, which by default is slightly smaller than 100 milliseconds. Call this function to set a higher or lower granularity. The function affects the behavior of {EventMachine.add_timer} and {EventMachine.add_periodic_timer}. Most applications will not need to call this function.

Avoid setting the quantum to very low values because that may reduce performance under some extreme conditions. We recommend that you not use values lower than 10.

This method only can be used if event loop is running.

@param [Integer] mills New timer granularity, in milliseconds

@see EventMachine.add_timer @see EventMachine.add_periodic_timer @see EventMachine::Timer @see EventMachine.run

    # File lib/eventmachine.rb, line 883
    def self.set_quantum mills
      set_timer_quantum mills.to_i
    end

set_rlimit_nofile(n) click to toggle source

This method is a no-op in the pure-Ruby implementation. We simply return Ruby's built-in per-process file-descriptor limit. @private

    # File lib/em/pure_ruby.rb, line 170
    def set_rlimit_nofile n
      1024
    end

set_sock_opt(signature, level, optname, optval) click to toggle source

@private

    # File lib/em/pure_ruby.rb, line 187
    def set_sock_opt signature, level, optname, optval
      selectable = Reactor.instance.get_selectable( signature ) or raise "unknown get_peername target"
      selectable.setsockopt level, optname, optval
    end

set_timer_quantum(interval) click to toggle source

Sets reactor quantum in milliseconds. The underlying Reactor function wants a (possibly fractional) number of seconds. @private

    # File lib/em/pure_ruby.rb, line 151
    def set_timer_quantum interval
      Reactor.instance.set_timer_quantum(( 1.0 * interval) / 1000.0)
    end

signal_loopbreak() click to toggle source

@private

    # File lib/em/pure_ruby.rb, line 124
    def signal_loopbreak
      Reactor.instance.signal_loopbreak
    end

spawn(&block) click to toggle source

Spawn an erlang-style process

    # File lib/em/spawnable.rb, line 69
    def self.spawn &block
      s = SpawnedProcess.new
      s.set_receiver block
      s
    end

spawn_threadpool() click to toggle source

@private

    # File lib/eventmachine.rb, line 1031
    def self.spawn_threadpool
      until @threadpool.size == @threadpool_size.to_i
        thread = Thread.new do
          Thread.current.abort_on_exception = true
          while true
            op, cback = *@threadqueue.pop
            result = op.call
            @resultqueue << [result, cback]
            EventMachine.signal_loopbreak
          end
        end
        @threadpool << thread
      end
      @all_threads_spawned = true
    end

ssl?() click to toggle source

This method is not implemented for pure-Ruby implementation @private

    # File lib/em/pure_ruby.rb, line 163
    def ssl?
      false
    end

start_server(server, port=nil, handler=nil, *args, &block) click to toggle source

Initiates a TCP server (socket acceptor) on the specified IP address and port.

The IP address must be valid on the machine where the program runs, and the process must be privileged enough to listen on the specified port (on Unix-like systems, superuser privileges are usually required to listen on any port lower than 1024). Only one listener may be running on any given address/port combination. start_server will fail if the given address and port are already listening on the machine, either because of a prior call to {.start_server} or some unrelated process running on the machine. If {.start_server} succeeds, the new network listener becomes active immediately and starts accepting connections from remote peers, and these connections generate callback events that are processed by the code specified in the handler parameter to {.start_server}.

The optional handler which is passed to this method is the key to EventMachine's ability to handle particular network protocols. The handler parameter passed to start_server must be a Ruby Module that you must define. When the network server that is started by start_server accepts a new connection, it instantiates a new object of an anonymous class that is inherited from {EventMachine::Connection}, *into which your handler module have been included*. Arguments passed into start_server after the class name are passed into the constructor during the instantiation.

Your handler module may override any of the methods in {EventMachine::Connection}, such as {EventMachine::Connection#receive_data}, in order to implement the specific behavior of the network protocol.

Callbacks invoked in response to network events always take place within the execution context of the object derived from {EventMachine::Connection} extended by your handler module. There is one object per connection, and all of the callbacks invoked for a particular connection take the form of instance methods called against the corresponding {EventMachine::Connection} object. Therefore, you are free to define whatever instance variables you wish, in order to contain the per-connection state required by the network protocol you are implementing.

{EventMachine.start_server} is usually called inside the block passed to {EventMachine.run}, but it can be called from any EventMachine callback. {EventMachine.start_server} will fail unless the EventMachine event loop is currently running (which is why it's often called in the block suppled to {EventMachine.run}).

You may call start_server any number of times to start up network listeners on different address/port combinations. The servers will all run simultaneously. More interestingly, each individual call to start_server can specify a different handler module and thus implement a different network protocol from all the others.

@example

    require 'rubygems'
    require 'eventmachine'

    # Here is an example of a server that counts lines of input from the remote
    # peer and sends back the total number of lines received, after each line.
    # Try the example with more than one client connection opened via telnet,
    # and you will see that the line count increments independently on each
    # of the client connections. Also very important to note, is that the
    # handler for the receive_data function, which our handler redefines, may
    # not assume that the data it receives observes any kind of message boundaries.
    # Also, to use this example, be sure to change the server and port parameters
    # to the start_server call to values appropriate for your environment.
    module LineCounter
      MaxLinesPerConnection = 10

      def post_init
        puts "Received a new connection"
        @data_received = ""
        @line_count = 0
      end

      def receive_data data
        @data_received << data
        while @data_received.slice!( /^[^\n]*[\n]/m )
          @line_count += 1
          send_data "received #{@line_count} lines so far\r\n"
          @line_count == MaxLinesPerConnection and close_connection_after_writing
        end
      end
    end

    EventMachine.run {
      host, port = "192.168.0.100", 8090
      EventMachine.start_server host, port, LineCounter
      puts "Now accepting connections on address #{host}, port #{port}..."
      EventMachine.add_periodic_timer(10) { $stderr.write "*" }
    }

@param [String] server Host to bind to. @param [Integer] port Port to bind to. @param [Module, Class] handler A module or class that implements connection callbacks

@note Don't forget that in order to bind to ports < 1024 on Linux, *BSD and Mac OS X your process must have superuser privileges.

@see file:docs/GettingStarted.md EventMachine tutorial @see EventMachine.stop_server

    # File lib/eventmachine.rb, line 512
    def self.start_server server, port=nil, handler=nil, *args, &block
      begin
        port = Integer(port)
      rescue ArgumentError, TypeError
        # there was no port, so server must be a unix domain socket
        # the port argument is actually the handler, and the handler is one of the args
        args.unshift handler if handler
        handler = port
        port = nil
      end if port

      klass = klass_from_handler(Connection, handler, *args)

      s = if port
            start_tcp_server server, port
          else
            start_unix_server server
          end
      @acceptors[s] = [klass,args,block]
      s
    end

start_tcp_server(host, port) click to toggle source

@private

    # File lib/em/pure_ruby.rb, line 101
    def start_tcp_server host, port
      (s = EvmaTCPServer.start_server host, port) or raise "no acceptor"
      s.uuid
    end

start_unix_domain_server(filename, *args, &block) click to toggle source

Start a Unix-domain server.

Note that this is an alias for {EventMachine.start_server}, which can be used to start both TCP and Unix-domain servers.

@see EventMachine.start_server

    # File lib/eventmachine.rb, line 547
    def self.start_unix_domain_server filename, *args, &block
      start_server filename, *args, &block
    end

start_unix_server(chain) click to toggle source

@private

    # File lib/em/pure_ruby.rb, line 113
    def start_unix_server chain
      (s = EvmaUNIXServer.start_server chain) or raise "no acceptor"
      s.uuid
    end

stop() click to toggle source

@private

    # File lib/em/pure_ruby.rb, line 70
    def stop
      Reactor.instance.stop
    end

stop_event_loop() click to toggle source

Causes the processing loop to stop executing, which will cause all open connections and accepting servers to be run down and closed. Connection termination callbacks added using {EventMachine.add_shutdown_hook} will be called as part of running this method.

When all of this processing is complete, the call to {EventMachine.run} which started the processing loop will return and program flow will resume from the statement following {EventMachine.run} call.

@example Stopping a running EventMachine event loop

    require 'rubygems'
    require 'eventmachine'

    module Redmond
      def post_init
        puts "We're sending a dumb HTTP request to the remote peer."
        send_data "GET / HTTP/1.1\r\nHost: www.microsoft.com\r\n\r\n"
      end

      def receive_data data
        puts "We received #{data.length} bytes from the remote peer."
        puts "We're going to stop the event loop now."
        EventMachine::stop_event_loop
      end

      def unbind
        puts "A connection has terminated."
      end
    end

    puts "We're starting the event loop now."
    EventMachine.run {
      EventMachine.connect "www.microsoft.com", 80, Redmond
    }
    puts "The event loop has stopped."

    # This program will produce approximately the following output:
    #
    # We're starting the event loop now.
    # We're sending a dumb HTTP request to the remote peer.
    # We received 1440 bytes from the remote peer.
    # We're going to stop the event loop now.
    # A connection has terminated.
    # The event loop has stopped.

    # File lib/eventmachine.rb, line 412
    def self.stop_event_loop
      EventMachine::stop
    end

stop_server(signature) click to toggle source

Stop a TCP server socket that was started with {EventMachine.start_server}. @see EventMachine.start_server

    # File lib/eventmachine.rb, line 537
    def self.stop_server signature
      EventMachine::stop_tcp_server signature
    end

stop_tcp_server(sig) click to toggle source

@private

    # File lib/em/pure_ruby.rb, line 107
    def stop_tcp_server sig
      s = Reactor.instance.get_selectable(sig)
      s.schedule_close
    end

system(cmd, *args, &cb) click to toggle source

EM::system is a simple wrapper for EM::popen. It is similar to Kernel::system, but requires a single string argument for the command and performs no shell expansion.

The block or proc passed to EM::system is called with two arguments: the output generated by the command, and a Process::Status that contains information about the command's execution.

    EM.run{
      EM.system('ls'){ |output,status| puts output if status.exitstatus == 0 }
    }

You can also supply an additional proc to send some data to the process:

    EM.run{
      EM.system('sh', proc{ |process|
        process.send_data("echo hello\n")
        process.send_data("exit\n")
      }, proc{ |out,status|
        puts(out)
      })
    }

Like EventMachine.popen, EventMachine.system currently does not work on windows. It returns the pid of the spawned process.

    # File lib/em/processes.rb, line 112
    def EventMachine::system cmd, *args, &cb
      cb ||= args.pop if args.last.is_a? Proc
      init = args.pop if args.last.is_a? Proc

      # merge remaining arguments into the command
      cmd = [cmd, *args] if args.any?

      EM.get_subprocess_pid(EM.popen(cmd, SystemCmd, cb) do |c|
        init[c] if init
      end.signature)
    end

tick_loop(*a, &b) click to toggle source

Creates and immediately starts an EventMachine::TickLoop

    # File lib/em/tick_loop.rb, line 3
    def self.tick_loop(*a, &b)
      TickLoop.new(*a, &b).start
    end

watch(io, handler=nil, *args, &blk) click to toggle source

{EventMachine.watch} registers a given file descriptor or IO object with the eventloop. The file descriptor will not be modified (it will remain blocking or non-blocking).

The eventloop can be used to process readable and writable events on the file descriptor, using {EventMachine::Connection#notify_readable=} and {EventMachine::Connection#notify_writable=}

{EventMachine::Connection#notify_readable?} and {EventMachine::Connection#notify_writable?} can be used to check what events are enabled on the connection.

To detach the file descriptor, use {EventMachine::Connection#detach}

@example

    module SimpleHttpClient
      def notify_readable
        header = @io.readline

        if header == "\r\n"
          # detach returns the file descriptor number (fd == @io.fileno)
          fd = detach
        end
      rescue EOFError
        detach
      end

      def unbind
        EM.next_tick do
          # socket is detached from the eventloop, but still open
          data = @io.read
        end
      end
    end

    EventMachine.run {
      sock = TCPSocket.new('site.com', 80)
      sock.write("GET / HTTP/1.0\r\n\r\n")
      conn = EventMachine.watch(sock, SimpleHttpClient)
      conn.notify_readable = true
    }

@author Riham Aldakkak (eSpace Technologies)

    # File lib/eventmachine.rb, line 717
    def EventMachine::watch io, handler=nil, *args, &blk
      attach_io io, true, handler, *args, &blk
    end

watch_file(filename, handler=nil, *args) click to toggle source

EventMachine's file monitoring API. Currently supported are the following events on individual files, using inotify on Linux systems, and kqueue for *BSD and Mac OS X:

- File modified (written to)

- File moved/renamed

- File deleted

EventMachine::watch_file takes a filename and a handler Module containing your custom callback methods. This will setup the low level monitoring on the specified file, and create a new EventMachine::FileWatch object with your Module mixed in. FileWatch is a subclass of {EventMachine::Connection}, so callbacks on this object work in the familiar way. The callbacks that will be fired by EventMachine are:

- file_modified

- file_moved

- file_deleted

You can access the filename being monitored from within this object using {FileWatch#path}.

When a file is deleted, {FileWatch#stop_watching} will be called after your file_deleted callback, to clean up the underlying monitoring and remove EventMachine's reference to the now-useless {FileWatch} instance. This will in turn call unbind, if you wish to use it.

The corresponding system-level Errno will be raised when attempting to monitor non-existent files, files with wrong permissions, or if an error occurs dealing with inotify/kqueue.

@example

    # Before running this example, make sure we have a file to monitor:
    # $ echo "bar" > /tmp/foo

    module Handler
      def file_modified
        puts "#{path} modified"
      end

      def file_moved
        puts "#{path} moved"
      end

      def file_deleted
        puts "#{path} deleted"
      end

      def unbind
        puts "#{path} monitoring ceased"
      end
    end

    # for efficient file watching, use kqueue on Mac OS X
    EventMachine.kqueue = true if EventMachine.kqueue?

    EventMachine.run {
      EventMachine.watch_file("/tmp/foo", Handler)
    }

    # $ echo "baz" >> /tmp/foo    =>    "/tmp/foo modified"
    # $ mv /tmp/foo /tmp/oof      =>    "/tmp/foo moved"
    # $ rm /tmp/oof               =>    "/tmp/foo deleted"

@note The ability to pick up on the new filename after a rename is not yet supported.

    Calling #path will always return the filename you originally used.

@param [String] filename Local path to the file to watch. @param [Class, Module] handler A class or module that implements event handlers associated with the file.

    # File lib/eventmachine.rb, line 1265
    def self.watch_file(filename, handler=nil, *args)
      klass = klass_from_handler(FileWatch, handler, *args)

      s = EM::watch_filename(filename)
      c = klass.new s, *args
      # we have to set the path like this because of how Connection.new works
      c.instance_variable_set("@path", filename)
      @conns[s] = c
      block_given? and yield c
      c
    end

watch_process(pid, handler=nil, *args) click to toggle source

EventMachine's process monitoring API. On Mac OS X and *BSD this method is implemented using kqueue.

@example

    module ProcessWatcher
      def process_exited
        put 'the forked child died!'
      end
    end

    pid = fork{ sleep }

    EventMachine.run {
      EventMachine.watch_process(pid, ProcessWatcher)
      EventMachine.add_timer(1){ Process.kill('TERM', pid) }
    }

@param [Integer] pid PID of the process to watch. @param [Class, Module] handler A class or module that implements event handlers associated with the file.

    # File lib/eventmachine.rb, line 1296
    def self.watch_process(pid, handler=nil, *args)
      pid = pid.to_i

      klass = klass_from_handler(ProcessWatch, handler, *args)

      s = EM::watch_pid(pid)
      c = klass.new s, *args
      # we have to set the path like this because of how Connection.new works
      c.instance_variable_set("@pid", pid)
      @conns[s] = c
      block_given? and yield c
      c
    end

yield(&block) click to toggle source

@private

    # File lib/em/spawnable.rb, line 76
    def self.yield &block
      return YieldBlockFromSpawnedProcess.new( block, false )
    end

yield_and_notify(&block) click to toggle source

@private

    # File lib/em/spawnable.rb, line 81
    def self.yield_and_notify &block
      return YieldBlockFromSpawnedProcess.new( block, true )
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.