msgpack-rpc 0.4.0 → 0.4.1

data/ChangeLog

@@ -0,0 +1,17 @@
+
+2010-08-27 version 0.4.1
+
+  * Adds MultiFuture class
+  * New exception mechanism
+  * Rescues all errors on_readable not to stop event loop
+  * Future: doesn't wrap callback_handler but check on calling for backward compatibility
+  * Responder: adds a guard not to send results twice
+  * Session: adds call_apply and notify_apply
+  * Uses jeweler and Rakefile for packaging
+
+2010-05-28 version 0.4.0
+
+  * updates dispatch mechanism
+  * adds Session#call_apply and notify_apply
+  * Responder prevents sending results twice
+

data/lib/msgpack/rpc.rb

@@ -1,5 +1,5 @@
 #
-# MessagePack-RPC for Ruby TCP transport
+# MessagePack-RPC for Ruby
 #
 # Copyright (C) 2010 FURUHASHI Sadayuki
 #
@@ -18,50 +18,114 @@
 module MessagePack  #:nodoc:
 
 # MessagePack-RPC is an inter-process messaging library that uses
-# MessagePack for object serialization. The goal of the project is
-# providing fast and scalable messaging system for server, client
-# and cluster applications.
+# MessagePack[http://msgpack.sourceforge.net/] for object serialization.
+# The goal of the project is providing fast and scalable messaging system
+# for server, client and cluster applications.
+#
+# You can install MessagePack-RPC for Ruby using RubyGems.
+#
+#   gem install msgpack-rpc
+#
 #
 # == Client API
 #
 # MessagePack::RPC::Client and MessagePack::RPC::SessionPool are for RPC clients.
 #
+#
 # === Simple usage
+#
 # Client is subclass of Session. Use Session#call method to call remote methods.
 #
-#   require 'msgpack/rpc'  # gem install msgpack-rpc
+#   require 'msgpack/rpc'
 #   
 #   client = MessagePack::RPC::Client.new('127.0.0.1', 18800)
 #   
 #   result = client.call(:methodName, arg1, arg2, arg3)
 #
+#   #     ---------- server
+#   #    ^         |
+#   #    |         |
+#   # ---+         +----- client
+#   #    call      join
+#
+#
 # === Asynchronous call
+#
 # Use Session#call_async method to call remote methods asynchronously. It returns a Future. Use Future#get or Future#attach_callback to get actual result.
 #
-#   require 'msgpack/rpc'  # gem install msgpack-rpc
+#   require 'msgpack/rpc'
 #   
 #   client = MessagePack::RPC::Client.new('127.0.0.1', 18800)
 #   
-#   future1 = client.call(:method1, arg1)  # call two methods concurrently
-#   future2 = client.call(:method2, arg1)
+#   # call two methods concurrently
+#   future1 = client.call_async(:method1, arg1)
+#   future2 = client.call_async(:method2, arg1)
+#   
+#   # join the results
+#   result1 = future1.get
+#   result2 = future2.get
+#
+#   #     ------------------ server
+#   #    ^                 |
+#   #    |        ---------|-------- server
+#   #    |       ^         |       |
+#   #    |       |         |       |
+#   # ---+-------+-----    +-------+----- client
+#   #    call    call      join    join
+#
+# === Asynchronous call with multiple servers
+#
+# Loop enables you to invoke multiple asynchronous calls for multiple servers concurrently.
+# This is good for advanced network applications.
+#
+#   require 'msgpack/rpc'
+#   
+#   # create a event loop
+#   loop = MessagePack::RPC::Loop.new
+#
+#   # connect to multiple servers
+#   client1 = MessagePack::RPC::Client.new('127.0.0.1', 18801, loop)
+#   client2 = MessagePack::RPC::Client.new('127.0.0.1', 18802, loop)
+#   
+#   # call two methods concurrently
+#   future1 = client1.call_async(:method1, arg1)
+#   future2 = client2.call_async(:method2, arg1)
 #   
+#   # join the results
 #   result1 = future1.get
 #   result2 = future2.get
 #
+#   #     ------------------ server-1  --- different servers
+#   #    ^                 |             /
+#   #    |        ---------|-------- server-2
+#   #    |       ^         |       |
+#   #    |       |         |       |
+#   # ---+-------+-----    +-------+----- client
+#   #    call    call      join    join
+#
 # === Connection pooling
 #
 # SessionPool#get_session returns a Session. It pools created session and enables you to reuse established connections.
 #
+#   require 'msgpack/rpc'
+#   
+#   sp = MessagePack::RPC::SessionPool.new
+#   
+#   client = sp.get_session('127.0.0.1', 18800)
+#   
+#   result = client.call(:methodName, arg1, arg2, arg3)
+#
 #
 # == Server API
 #
 # MessagePack::RPC::Server is for RPC servers.
 #
+#
 # === Simple usage
 #
-# The public methods of handler class becomes callbale.
+# The public methods of the handler class becomes callbale.
 #
-#   require 'msgpack/rpc'  # gem install msgpack-rpc
+#   require 'msgpack/rpc'
 #
 #   class MyHandler
 #     def methodName(arg1, arg2, arg3)
@@ -74,9 +138,10 @@ module MessagePack  #:nodoc:
 #   server.listen('0.0.0.0', 18800, MyHandler.new)
 #   server.run
 #
+#
 # === Advance return
 #
-# In the handler method, you can use *yield* to send the result without returning.
+# You can use *yield* to send the result without returning.
 #
 #   class MyHandler
 #     def method1(arg1)
@@ -85,6 +150,7 @@ module MessagePack  #:nodoc:
 #     end
 #   end
 #
+#
 # === Delayed return
 #
 # You can use AsyncResult to return results later.
@@ -109,24 +175,39 @@ module MessagePack  #:nodoc:
 #
 # You can use UDP and UNIX domain sockets instead of TCP.
 #
+#
 # === For clients
 #
 # For clients, use MessagePack::RPC::UDPTransport or MessagePack::RPC::UNIXTransport.
 #
-#   require 'msgpack/rpc'  # gem install msgpack-rpc
+#   require 'msgpack/rpc'
 #   require 'msgpack/rpc/transport/udp'
 #   
 #   transport = MessagePack::RPC::UDPTransport.new
 #   address = MessagePack::RPC::Address.new('127.0.0.1', 18800)
+#   
 #   client = MessagePack::RPC::Client.new(transport, address)
 #   
 #   result = client.call(:methodName, arg1, arg2, arg3)
 #
+# You can use transports for SessionPool.
+#
+#   require 'msgpack/rpc'
+#   require 'msgpack/rpc/transport/udp'
+#   
+#   transport = MessagePack::RPC::UDPTransport.new
+#   
+#   sp = MessagePack::RPC::SessionPool.new(transport)
+#   
+#   client = sp.get_session('127.0.0.1', 18800)
+#   
+#   result = client.call(:methodName, arg1, arg2, arg3)
+#
 # === For servers
 #
 # For servers, use MessagePack::RPC::UDPServerTransport or MessagePack::RPC::UNIXServerTransport.
 #
-#   require 'msgpack/rpc'  # gem install msgpack-rpc
+#   require 'msgpack/rpc'
 #   require 'msgpack/rpc/transport/udp'
 #   
 #   class MyHandler
@@ -138,6 +219,7 @@ module MessagePack  #:nodoc:
 #   
 #   address = MessagePack::RPC::Address.new('0.0.0.0', 18800)
 #   listener = MessagePack::RPC::UDPServerTransport.new(address)
+#
 #   server = MessagePack::RPC::Server.new
 #   server.listen(listener, MyHandler.new)
 #   server.run
@@ -152,11 +234,13 @@ end  # module MessagePack
 require 'msgpack'
 require 'socket'
 require 'rev'
+require 'msgpack/rpc/version'
 require 'msgpack/rpc/address'
 require 'msgpack/rpc/message'
 require 'msgpack/rpc/exception'
 require 'msgpack/rpc/loop'
 require 'msgpack/rpc/future'
+require 'msgpack/rpc/multi_future'
 require 'msgpack/rpc/session'
 require 'msgpack/rpc/session_pool'
 require 'msgpack/rpc/dispatcher'
@@ -164,3 +248,4 @@ require 'msgpack/rpc/client'
 require 'msgpack/rpc/server'
 require 'msgpack/rpc/transport/base'
 require 'msgpack/rpc/transport/tcp'
+

data/lib/msgpack/rpc/client.rb

@@ -20,15 +20,15 @@ module RPC
 
 
 # Client is usable for RPC client.
-# Note that SessionPool includes LoopUtil.
+# Note that Client includes LoopUtil.
 class Client < Session
 	# 1. initialize(builder, address, loop = Loop.new)
 	# 2. initialize(host, port, loop = Loop.new)
 	#
 	# Creates a client.
 	def initialize(arg1, arg2, arg3=nil)
-			# 1.
 		if arg1.respond_to?(:build_transport)
+			# 1.
 			builder = arg1
 			address = arg2
 			loop    = arg3 || Loop.new

data/lib/msgpack/rpc/dispatcher.rb

@@ -19,86 +19,19 @@ module MessagePack
 module RPC
 
 
-class AsyncResult
-	def initialize
-		@responder = nil
-		@sent = false
-	end
-
-	def result(retval, err = nil)
-		unless @sent
-			if @responder
-				@responder.result(retval, err)
-			else
-				@result = [retval, err]
-			end
-			@sent = true
-		end
-		nil
-	end
-
-	def error(err)
-		result(nil, err)
-		nil
-	end
-
-	def set_responder(res)  #:nodoc:
-		@responder = res
-		if @sent && @result
-			@responder.result(*@result)
-			@result = nil
-		end
-	end
+module Dispatcher
 end
 
 
 class ObjectDispatcher
+	include Dispatcher
+
 	def initialize(obj, accept = obj.public_methods)
 		@obj = obj
 		@accept = accept.map {|m| m.is_a?(Integer) ? m : m.to_s }
 	end
 
-	def dispatch_request(session, method, param, responder)
-		begin
-			sent = false
-			early_result = nil
-			result = forward_method(session, method, param) do |result_|
-				unless result_.is_a?(AsyncResult)
-					responder.result(result_)
-					sent = true
-				end
-				early_result = result_
-			end
-
-		# FIXME on NoMethodError
-		# res.error(NO_METHOD_ERROR); return
-
-		# FIXME on ArgumentError
-		# res.error(ArgumentError); return
-
-		rescue
-			responder.error($!.to_s)
-			return
-		end
-
-		if early_result.is_a?(AsyncResult)
-			early_result.set_responder(responder)
-		elsif sent
-			return
-		elsif result.is_a?(AsyncResult)
-			result.set_responder(responder)
-		else
-			responder.result(result)
-		end
-	end
-
-	def dispatch_notify(session, method, param)
-		forward_method(session, method, param)
-	rescue
-	end
-
-	private
-	def forward_method(session, method, param, &block)
+	def dispatch(method, param, &block)
 		unless @accept.include?(method)
 			raise NoMethodError, "method `#{method}' is not accepted"
 		end
@@ -107,5 +40,10 @@ class ObjectDispatcher
 end
 
 
+#:nodoc:
+class MethodForwarder
+end
+
+
 end
 end

data/lib/msgpack/rpc/exception.rb

@@ -22,30 +22,188 @@ module RPC
 class Error < StandardError
 end
 
+
+##
+## MessagePack-RPC Exception
+##
+#
+#  RPCError
+#  |
+#  +-- TimeoutError
+#  |
+#  +-- TransportError
+#  |   |
+#  |   +-- NetworkUnreachableError
+#  |   |
+#  |   +-- ConnectionRefusedError
+#  |   |
+#  |   +-- ConnectionTimeoutError
+#  |   |
+#  |   +-- MalformedMessageError
+#  |   |
+#  |   +-- StreamClosedError
+#  |
+#  +-- CallError
+#  |   |
+#  |   +-- NoMethodError
+#  |   |
+#  |   +-- ArgumentError
+#  |
+#  +-- ServerError
+#  |   |
+#  |   +-- ServerBusyError
+#  |
+#  +-- RemoteError
+#      |
+#      +-- RuntimeError
+#      |
+#      +-- (user-defined errors)
+
 class RPCError < Error
+	def initialize(code, *data)
+		@code = code.to_s
+		@data = data
+		super(@data.shift || @code)
+	end
+	attr_reader :code
+	attr_reader :data
+
+	def is?(code)
+		if code.is_a?(Class) && code < RPCError
+			code = code::CODE
+		end
+		@code == code || @code[0,code.length+1] == "#{code}." ||
+			(code == ".RemoteError" && @code[0] != ?.)
+	end
+end
+
+
+##
+# Top Level Errors
+#
+class TimeoutError < RPCError
+	CODE = ".TimeoutError"
+	def initialize(msg)
+		super(self.class::CODE, msg)
+	end
+end
+
+class TransportError < RPCError
+	CODE = ".TransportError"
+	def initialize(msg)
+		super(self.class::CODE, msg)
+	end
+end
+
+class CallError < RPCError
+	CODE = ".CallError"
 	def initialize(msg)
-		super(msg)
+		super(self.class::CODE, msg)
+	end
+end
+
+class ServerError < RPCError
+	CODE = ".ServerError"
+	def initialize(msg)
+		super(self.class::CODE, msg)
 	end
 end
 
 class RemoteError < RPCError
-	def initialize(msg, result = nil)
-		super(msg)
-		@result = result
+	def initialize(code, *data)
+		super(code, *data)
 	end
-	attr_reader :result
 end
 
-class TimeoutError < Error
-	def initialize(msg = "request timed out")
-		super
+
+##
+# TransportError
+#
+class NetworkUnreachableError < TransportError
+	CODE = ".TransportError.NetworkUnreachableError"
+end
+
+class ConnectionRefusedError < TransportError
+	CODE = ".TransportError.ConnectionRefusedError"
+end
+
+class ConnectionTimeoutError < TransportError
+	CODE = ".TransportError.ConnectionTimeoutError"
+end
+
+class MalformedMessageError < TransportError
+	CODE = ".TransportError.ConnectionRefusedError"
+end
+
+class StreamClosedError < TransportError
+	CODE = ".TransportError.StreamClosedError"
+end
+
+##
+# CallError
+#
+class NoMethodError < CallError
+	CODE = ".CallError.NoMethodError"
+end
+
+class ArgumentError < CallError
+	CODE = ".CallError.ArgumentError"
+end
+
+##
+# ServerError
+#
+class ServerBusyError < ServerError
+	CODE = ".ServerError.ServerBusyError"
+end
+
+##
+# RuntimeError
+#
+class RuntimeError < RemoteError
+	def initialize(msg, *data)
+		super("RuntimeError", msg, *data)
 	end
 end
 
-class ConnectError < TimeoutError
-	def initialize(msg = "connect failed")
-		super
+
+class RPCError
+	def self.create(code, data)
+		if code[0] == ?.
+			code = code.dup
+			while true
+				if klass = SYSTEM_ERROR_TABLE[code]
+					return klass.new(*data)
+				end
+				if code.slice!(/\.[^\.]*$/) == nil || code.empty?
+					return RPCError.new(code, *data)
+				end
+			end
+
+		elsif code == RuntimeError::CODE
+			RuntimeError.new(*data)
+
+		else
+			RemoteError.new(code, *data)
+		end
 	end
+
+	private
+	SYSTEM_ERROR_TABLE = {
+		TimeoutError::CODE            => TimeoutError,
+		TransportError::CODE          => TransportError,
+		CallError::CODE               => CallError,
+		ServerError::CODE             => ServerError,
+		RemoteError::CODE             => RemoteError,
+		NetworkUnreachableError::CODE => NetworkUnreachableError,
+		ConnectionRefusedError::CODE  => ConnectionRefusedError,
+		ConnectionTimeoutError::CODE  => ConnectionTimeoutError,
+		MalformedMessageError::CODE   => MalformedMessageError,
+		StreamClosedError::CODE       => StreamClosedError,
+		NoMethodError::CODE           => NoMethodError,
+		ArgumentError::CODE           => ArgumentError,
+		ServerBusyError::CODE         => ServerBusyError,
+	}
 end