romp-rpc 0.2.0

data/lib/romp-rpc.rb

@@ -0,0 +1,548 @@
+require 'socket'
+require 'thread'
+require 'fcntl'
+require 'romp_helper'
+
+##
+# ROMP - The Ruby Object Message Proxy
+# @author Paul Brannan
+# @version 0.1
+# (C) Copyright 2001 Paul Brannan (cout at rm-f.net)
+# 
+# <pre>
+# ROMP is a set of classes for providing distributed object support to a
+# Ruby program.  You may distribute and/or modify it under the same terms as
+# Ruby (see http://www.ruby-lang.org/en/LICENSE.txt).  Example:
+# 
+# Client 
+# ------
+# client = ROMP::Client.new('localhost', 4242)
+# obj = client.resolve("foo")
+# puts obj.foo("foo")
+# obj.oneway(:foo, "foo")
+# 
+# Server
+# ------
+# class Foo
+#     def foo(x); return x; end
+# end
+# obj = Foo.new
+# server = ROMP::Server.new('localhost', 4242)
+# server.bind(obj, "foo")
+# server.thread.join
+# 
+# You can do all sorts of cool things with ROMP, including passing blocks to
+# the functions, throwing exceptions and propogating them from server to
+# client, and more.  Unlike CORBA, where you must create an interface
+# definition and strictly adhere to it, ROMP uses marshalling, so you can
+# use almost any object with it.  But, alas, it is not as powerful as CORBA.
+# 
+# On a fast machine, you should expect around 7000 messages per second with
+# normal method calls, up to 10000 messages per second with oneway calls with
+# sync, and up to 40000 messages per second for oneway calls without sync.
+# These numbers can vary depending on various factors, so YMMV.
+# 
+# The ROMP message format is broken into 3 components:
+#     [ msg_type, obj_id, message ]
+# For each msg_type, there is a specific format to the message.  Additionally,
+# certain msg_types are only valid when being sent to the server, and others
+# are valid only when being sent back to the client.  Here is a summary:
+# 
+# msg_type         send to     meaning of obj_id       msg format
+# ----------------------------------------------------------------------------
+# REQUEST          server      obj to talk to          [:method, *args]
+# REQUEST_BLOCK    server      obj to talk to          [:method, *args]
+# ONEWAY           server      obj to talk to          [:method, *args]
+# ONEWAY_SYNC      server      obj to talk to          [:method, *args] 
+# RETVAL           client      always 0                retval
+# EXCEPTION        client      always 0                $!
+# YIELD            client      always 0                [value, value, ...]
+# SYNC             either      0=request, 1=response   nil
+# NULL_MSG         either      always 0                n/a
+# 
+# BUGS:
+# - On a 2.2 kernel, oneway calls without sync is very slow.
+# - UDP support does not currently work.
+# </pre>
+
+module ROMP
+
+public
+
+    ##
+    # The ROMP server class.  Like its drb equivalent, this class spawns off
+    # a new thread which processes requests, allowing the server to do other
+    # things while it is doing processing for a distributed object.  This
+    # means, though, that all objects used with ROMP must be thread-safe.
+    # 
+    class Server
+
+    public
+        attr_reader :obj, :thread
+
+        ##
+        # Start a ROMP server.
+        #
+        # @param endpoint An endpoint for the server to listen on; should be specified in URI notation.
+        # @param acceptor A proc object that can accept or reject connections; it should take a Socket as an argument and returns true or false.
+        # @param debug Turns on debugging messages if enabled.
+        # 
+        def initialize(endpoint, acceptor=nil, debug=false)
+            @mutex = Mutex.new
+            @debug = debug
+            @resolve_server = Resolve_Server.new
+            @resolve_obj = Resolve_Obj.new(@resolve_server)
+            @resolve_server.register(@resolve_obj)
+
+            @thread = Thread.new do
+                server = Generic_Server.new(endpoint)
+                while(socket = server.accept)
+                    puts "Got a connection" if @debug
+                    if acceptor then
+                        if !acceptor.call(socket) then
+                            socket.close
+                            next
+                        end
+                    end
+                    puts "Accepted the connection" if @debug
+                    session = Session.new(socket)
+                    session.set_nonblock(true)
+                    Thread.new(socket) do |socket|
+                        Thread.current.abort_on_exception = true
+                        begin
+                            # TODO: Send a sync message to the client so it
+                            # knows we are ready to receive data.
+                            server_loop(session)
+                        rescue Exception
+                            ROMP::print_exception($!) if @debug
+                        end
+                        puts "Connection closed" if @debug
+                    end
+                end
+            end
+        end
+
+        ##
+        # Register an object with the server.  The object will be given an
+        # id of @next_id, and @next_id will be incremented.  We could use the
+        # object's real id, but this is insecure.  The supplied object must
+        # be thread-safe.
+        #
+        # @param obj The object to register.
+        #
+        # @return A new Object_Reference that should be returned to the client.
+        #
+        def create_reference(obj)
+            @mutex.synchronize do
+                id = @resolve_server.register(obj)
+                Object_Reference.new(id) #return
+            end
+        end
+
+        ##
+        # Find an object in linear time and unregister it. Be careful with
+        # this function, because the client may not know the object has
+        # gone away.
+        #
+        # @param obj The object to unregister.
+        #
+        def delete_reference(obj)
+            @mutex.synchronize do
+                @resolve_server.unregister(obj)
+            end
+            nil #return
+        end
+
+        ##
+        # Register an object with the server and bind it to name.
+        #
+        # @param obj The object to bind.
+        # @param name The name of to bind the object to.
+        #
+        def bind(obj, name)
+            id = @resolve_server.register(obj)
+            @resolve_server.bind(name, id)
+            nil #return
+        end
+
+        ##
+        # This keeps the client from seeing our objects when they call inspect
+        #
+        alias_method :__inspect__, :inspect
+        def inspect()
+            return ""
+        end
+
+    private
+        if false then # the following functions are implemented in C:
+
+        ##
+        # The server_loop function is the guts of the server.  It takes in
+        # requests from the client and forwards them to already-registered
+        # objects.
+        #
+        # @param session The session to run the loop with.
+        #
+        def server_loop(session)
+        end
+
+        end # if false
+    end
+
+    ##
+    # The ROMP client class.  A ROMP server must be started on the given
+    # host and port before instantiating a ROMP client.
+    #
+    class Client
+
+        ##
+        # Connect to a ROMP server
+        #
+        # @param endpoint The endpoint the server is listening on.
+        # @param sync Specifies whether to synchronize between threads; turn this off to get a 20% performance boost.
+        #
+        def initialize(endpoint, sync=true)
+            @server = Generic_Client.new(endpoint)
+            @session = Session.new(@server)
+            @session.set_nonblock(true)
+            @mutex = sync ? Mutex.new : Null_Mutex.new
+            @resolve_obj = Proxy_Object.new(@session, @mutex, 0)
+        end
+
+        ##
+        # Given a string, return a proxy object that will forward requests
+        # for an object on the server with that name.
+        #
+        # @param object_name The name of the object to resolve.
+        #
+        # @return A Proxy_Object that can be used to make method calls on the object in the server.
+        #
+        def resolve(object_name)
+            @mutex.synchronize do
+                object_id = @resolve_obj.resolve(object_name)
+                return Proxy_Object.new(@session, @mutex, object_id)
+            end
+        end
+    end
+
+private
+
+    ##
+    # In case the user does not want synchronization.
+    #
+    class Null_Mutex
+        def synchronize
+            yield
+        end
+
+        def lock
+        end
+
+        def unlock
+        end
+    end
+
+    ##
+    # All the special functions we have to keep track of
+    #
+    class Functions
+        GOOD = [
+            :inspect, :class_variables, :instance_eval, :instance_variables,
+            :to_a, :to_s
+        ]
+
+        BAD = [
+            :clone, :dup, :display
+        ]
+
+        METHOD = [
+            :methods, :private_methods, :protected_methods, :public_methods,
+            :singleton_methods
+        ]
+
+        RESPOND = [
+            [ :method,      "raise NameError" ],
+            [ :respond_to?, "false" ]
+        ]
+    end
+
+    ##
+    # A ROMP::Object_Reference is created on the server side to represent an
+    # object in the system.  It can be returned from a server object to a
+    # client object, at which point it is converted into a ROMP::Proxy_Object.
+    #
+    class Object_Reference
+        attr_reader :object_id
+
+        def initialize(object_id)
+            @object_id = object_id
+        end
+    end
+
+    ##
+    # A ROMP::Object acts as a proxy; it forwards most methods to the server
+    # for execution.  When you make calls to a ROMP server, you will be
+    # making the calls through a Proxy_Object.
+    #
+    class Proxy_Object
+
+        if false then # the following functions are implemented in C:
+
+        ##
+        # The method_missing function is called for any method that is not
+        # defined on the client side.  It will forward requests to the server
+        # for processing, and can iterate through a block, raise an exception,
+        # or return a value.
+        #
+        def method_missing(function, *args)
+        end
+
+        ##
+        # The oneway function is called to make a oneway call to the server
+        # without synchronization.
+        #
+        def onweway(function, *args)
+        end
+
+        ##
+        # The oneway_sync function is called to make a oneway call to the
+        # server with synchronization (the server will return a null message
+        # to the client before it begins processing).  This is slightly safer
+        # than a normal oneway call, but it is slower (except on a linux 2.2
+        # kernel; see the bug list above).
+        #
+        def oneway_sync(function, *args)
+        end
+        
+        ##
+        # The sync function will synchronize with the server.  It sends a sync
+        # request and waits for a response.
+        #
+        def sync()
+        end
+
+        end # if false
+
+        # Make sure certain methods get passed down the wire.
+        Functions::GOOD.each do |method|
+            eval %{
+                def #{method}(*args)
+                      method_missing(:#{method}, *args) #return
+                end
+            }
+        end
+
+        # And make sure others never get called.
+        Functions::BAD.each do |method|
+            eval %{
+                def #{method}(*args)
+                    raise(NameError,
+                        "undefined method `#{method}' for " +
+                        "\#<#{self.class}:#{self.id}>")
+                end
+            }
+        end
+
+        # And remove these function names from any method lists that get
+        # returned; there's nothing we can do about people who decide to
+        # return them from other functions.
+        Functions::METHOD.each do |method|
+            eval %{
+                def #{method}(*args)
+                    retval = method_missing(:#{method}, *args)
+                    retval.each do |item|
+                        Functions::BAD.each do |bad|
+                            retval.delete(bad.to_s)
+                        end
+                    end
+                    retval #return
+                end
+            }
+        end
+
+        # Same here, except don't let the call go through in the first place.
+        Functions::RESPOND.each do |method, action|
+            eval %{
+                def #{method}(arg, *args)
+                    Functions::BAD.each do |bad|
+                        if arg === bad.to_s then
+                            return eval("#{action}")
+                        end
+                    end
+                    method_missing(:#{method}, arg, *args) #return
+                end
+            }
+        end
+
+    end
+
+    ##
+    # The Resolve_Server class registers objects for the server.  You will
+    # never have to use this class directly.
+    #
+    class Resolve_Server
+        def initialize
+            @next_id = 0
+            @unused_ids = Array.new
+            @id_to_object = Hash.new
+            @name_to_id = Hash.new
+        end
+
+        def register(obj)
+            if @next_id >= Session::MAX_ID then
+                if @unused_ids.size == 0 then
+                    raise "Object limit exceeded"
+                else
+                    id = @unused_ids.pop
+                end
+            end
+            @id_to_object[@next_id] = obj
+            old_id = @next_id
+            @next_id = @next_id.succ()
+            old_id #return
+        end
+
+        def get_object(object_id)
+            @id_to_object[object_id] #return
+        end
+
+        def unregister(obj)
+            delete_obj_from_array_private(@id_to_object, obj)
+        end
+
+        def bind(name, id)
+            @name_to_id[name] = id
+        end
+
+        def resolve(name)
+            @name_to_id[name] #return
+        end
+
+        def delete_obj_from_array_private(array, obj)
+            index = array.index(obj)
+            array[index] = nil unless index == nil
+        end
+    end
+
+    ##
+    # The Resolve_Obj class handles resolve requests for the client.  It is
+    # a special ROMP object with an object id of 0.  You will never have to
+    # make calls on it directly, but will instead make calls on it through
+    # the Client object.
+    #
+    class Resolve_Obj
+        def initialize(resolve_server)
+            @resolve_server = resolve_server
+        end
+
+        def resolve(name)
+            @resolve_server.resolve(name) #return
+        end
+    end
+
+    ##
+    # A Generic_Server creates an endpoint to listen on, waits for connections,
+    # and accepts them when requested.  It can operate on different kinds of
+    # connections.  You will never have to use this object directly.
+    #
+    class Generic_Server
+        def initialize(endpoint)
+            case endpoint
+                when %r{^(tcp)?romp://(.*?):(.*)}
+                    @type = "tcp"
+                    @host = $2 == "" ? nil : $2
+                    @port = $3
+                    @server = TCPServer.new(@host, @port)
+                when %r{^(udp)romp://(.*?):(.*)}
+                    @type = "udp"
+                    @host = $2 == "" ? nil : $2
+                    @port = $3
+                    @server = UDPSocket.open()
+                    @server.bind(@host, @port)
+                    @mutex = Mutex.new
+                when %r{^(unix)romp://(.*)}
+                    @type = "unix"
+                    @path = $2
+                    @server = UNIXServer.open(@path)
+                else
+                    raise ArgumentError, "Invalid endpoint"
+            end
+        end
+        def accept
+            case @type
+                when "tcp"
+                    socket = @server.accept
+                    socket.setsockopt(Socket::SOL_TCP, Socket::TCP_NODELAY, 1)
+                    socket.fcntl(Fcntl::F_SETFL, Fcntl::O_NONBLOCK)
+                    socket.sync = true
+                    socket #return
+                when "udp"
+                    @mutex.lock
+                    socket = @server
+                    socket.fcntl(Fcntl::F_SETFL, Fcntl::O_NONBLOCK)
+                    socket #return
+                when "unix"
+                    socket = @server.accept
+                    socket.fcntl(Fcntl::F_SETFL, Fcntl::O_NONBLOCK)
+                    socket.sync = true
+                    socket #return
+            end
+        end
+    end
+
+    ##
+    # A Generic_Client connects to a Generic_Server on a given endpoint.
+    # You will never have to use this object directly.
+    #
+    class Generic_Client
+        def self.new(endpoint)
+            case endpoint
+                when %r{^(tcp)?romp://(.*?):(.*)}
+                    socket = TCPSocket.open($2, $3)
+                    socket.sync = true
+                    socket.setsockopt(Socket::SOL_TCP, Socket::TCP_NODELAY, 1)
+                    socket.fcntl(Fcntl::F_SETFL, Fcntl::O_NONBLOCK)
+                    socket #return
+                when %r{^(udp)romp://(.*?):(.*)}
+                    socket = UDPSocket.open
+                    socket.connect($2, $3)
+                    socket #return
+                when %r{^(unix)romp://(.*)}
+                    socket = UNIXSocket.open($2)
+                else
+                    raise ArgumentError, "Invalid endpoint"
+            end
+        end
+    end
+
+
+    ##
+    # Print an exception to the screen.  This is necessary, because Ruby does
+    # not give us access to its error_print function from within Ruby.
+    #
+    # @param exc The exception object to print.
+    #
+    def self.print_exception(exc)
+        first = true
+        $!.backtrace.each do |bt|
+            if first then
+                puts "#{bt}: #{$!} (#{$!.message})"
+            else
+                puts "\tfrom #{bt}"
+            end
+            first = false
+        end
+    end
+
+    if false then # the following classes are implemented in C:
+
+    ##
+    # The Sesssion class is defined in romp_helper.so.  You should never have
+    # to use it directly.
+    #
+    class Session
+    end
+
+    end # if false
+
+end