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.

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'
  
  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'
  
  client = MessagePack::RPC::Client.new('127.0.0.1', 18800)
  
  # 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 the handler class becomes callbale.

  require 'msgpack/rpc'

  class MyHandler
    def methodName(arg1, arg2, arg3)
      puts "received"
      return "return result."
    end
  end

  server = MessagePack::RPC::Server.new
  server.listen('0.0.0.0', 18800, MyHandler.new)
  server.run

Advance return

You can use yield to send the result without returning.

  class MyHandler
    def method1(arg1)
      yield("return result.")
      puts "you can do something after returning the result"
    end
  end

Delayed return

You can use AsyncResult to return results later.

  class MyHandler
    def method2(arg1)
      as = MessagePack::RPC::AsyncResult.new
      Thread.new do
        sleep 10   # return result 10 seconds later.
        as.result("return result.")
      end
      return as
    end
  end

You can receive and send any objects that can be serialized by MessagePack. This means that the objects required to implement *to_msgpack(out = ’’)* method.

Transports

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'
  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'
  require 'msgpack/rpc/transport/udp'
  
  class MyHandler
    def methodName(arg1, arg2, arg3)
      puts "received"
      return "return result."
    end
  end
  
  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