elrpc 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b19cb4f1857c727202dfee06bce97cad08cf54ad
-  data.tar.gz: 1038805533721cde69d0a9e1a9b9a7991cd3c61d
+  metadata.gz: 1ff7cff0814489d4e855848dd5f6c59ebbcffcf0
+  data.tar.gz: 246d1edd90a7f3ecf6f039b23a8b9c13f7fc053b
 SHA512:
-  metadata.gz: 53444d2a46a9fc54d3eed9004b6e23df4553d6b57aa39c42e46f9c8088ac5a523bce1e2f7b54e40e51bc9f50a35f24ead175c042dec6aa7329da8f2febe5c63a
-  data.tar.gz: 01a5342c11b311b802d895d88e694e3b5fb848c0d5b1200d1be4f265ff6fefaba4ab1d7c94f4f26f33be0bc5f869c521ce55df44c92cb4f2e64b51630d0b1d56
+  metadata.gz: cf75699c742ea27c6c49073a45e5c01c50f4b6411946738236906459dcaf54263e6c6d765681b34d3ad62d884691f38b2ac5d031da070601276b836078e38d88
+  data.tar.gz: 502a9ac563cc7886a70dd4c66b0f0a5b99448478d3faa5656f872bbe104ccad86c269b70ad4022f2f533eedd1f975fa0e0e3613715f84b5393872d5fc7821e65

data/README.md

@@ -3,14 +3,15 @@
 EPC is an RPC stack for Emacs Lisp and Elrpc is an implementation of EPC in Ruby.
 Using elrpc, you can develop an emacs extension with Ruby code.
 
-- https://github.com/kiwanami/emacs-epc
+- [EPC at github](https://github.com/kiwanami/emacs-epc)
 
 ## Sample Code
 
-### Ruby code (child process)
+### Ruby code (server process)
 
-This code will be started by the parent process.
+This code is started by the client process, such as Emacs Lisp.
 
+`echo.rb`
 ```ruby
 require 'elrpc'
 
@@ -27,16 +28,17 @@ end
 server.wait
 ```
 
-### Emacs Lisp code (parent process)
+### Emacs Lisp code (client process)
 
-This elisp code calls the child process.
+This elisp code calls the server process.
 The package `epc` is required.
 
+`echo-client.el`
 ```el
 (require 'epc)
 
 (let (epc)
-  ;; start a child process (using bundle exec)
+  ;; start a server process (using bundle exec)
   (setq epc (epc:start-epc "bundle" '("exec" "ruby" "echo.rb")))
 
   (deferred:$
@@ -49,14 +51,15 @@ The package `epc` is required.
   (epc:stop-epc epc)) ; just `eval-last-sexp' here
 ```
 
-### Ruby code (parent process)
+### Ruby code (client process)
 
-You can also write the parent process code in Ruby.
+You can also write the client process code in Ruby.
 
+`echo-client.rb`
 ```ruby
 require 'elrpc'
 
- # start a child process
+ # start a server process
 cl = Elrpc.start_process(["ruby","echo.rb"])
 
  # synchronous calling
@@ -71,7 +74,7 @@ puts "2 wait"
 sleep 0.2
 
 puts "4 ok"
- # kill the child process
+ # kill the server process
 cl.stop
 ```
 
@@ -103,6 +106,16 @@ Or install it yourself as:
 
 ## API Document
 
+### EPC Overview
+
+The EPC uses a peer-to-peer-architecture. After the connection is established, both peers can define remote methods and call the methods at the other side.
+
+Let we define the words *server* and *client*. *Server* is a process which opens a TCP port and waiting for the connection. *Client* is a process which connects to the *server*. In most cases, a *client* process starts a *server* process. Then, the *server* process provides some services to the *client* process.
+
+This diagram shows the API usage and the relation of processes.
+
+![EPC Overview](https://cacoo.com/diagrams/cFQgb5d5W9MphN8z-B5059.png)
+
 Please see the EPC document for the overview of EPC stack and protocol details.
 
 - [EPC Readme](https://github.com/kiwanami/emacs-epc)
@@ -111,21 +124,181 @@ Please see the `elparser` document for object serialization.
 
 - [elparser Readme](https://github.com/kiwanami/ruby-elparser)
 
-### Start EPC
+### Building Server-Process
+
+- Module method : `Elrpc::start_server(methods = [], port = 0)`
+    - Arguments
+        - `methods` : Array of `Elrpc::Method` instances.
+        - `port` : TCP Port number. 0 means that the number is decided by OS.
+    - Return
+        - A `Elrpc::RPCService` instance
+
+
+*Sample Code*
+```ruby
+server = Elrpc::start_server
+```
+
+
+### Defining Remote Method
+
+- `Elrpc::RPCService#def_method(name, argdoc=nil, docstring=nil, &block)`
+    - Arguments
+        - `name` : String. Method name which is referred by the peer process.
+        - `argdoc` : String[optional]. Argument information for human.
+        - `docstring` : String[optional]. Method information for human.
+        - `&block` : Block. Code block which is called by the peer process. The return value is serialized and sent to the peer.
+
+The return value of the code block is serialized and sent to the peer process. So, if the return value includes wrong values which can't be serialized by `elparser`, the runtime exception `EPCStackError` is thrown to the method calling of the peer process.
+
+*Sample Code*
+```ruby
+server.def_method("echo") do |arg|
+    arg
+end
+
+server.def_method("add") do |a, b|
+    a + b
+end
 
-### Stop EPC
+server.def_method("inject", 
+    "init(initial value), op(operator symbol), list", 
+    "Apply Enumerable#inject method.") do |init, op, list|
+    list.inject(init, op)
+end
+```
 
-### Define Remote Method
+### Calling Remote Method
+
+If the peer process defines some methods, the instance of `Elrpc::RPCService` can call the peer's method, regardless of the server process or the client one. (See the EPC document.)
+
+- `Elrpc::RPCService#call_method(name, *args)`
+    - Synchronous method calling. The current thread is blocked until the calling result is returned.
+    - Arguments
+        - `name` : String. Method name to call.
+        - `args` : Array(Variable length arguments) Argument values.
+    - Return
+        - The return value which is returned by the peer process.
+    - Exception
+        - `EPCRuntimeError` : An exception which is thrown by the peer's method.
+        - `EPCStackError` : An exception which is thrown by the EPC protocol stack.
+
+- `Elrpc::RPCService#call_method_async(name, *args, &block)`
+    - Asynchronous method calling. The current thread is not blocked. The calling result is passed to the code block.
+    - Arguments
+        - `name` : String. Method name to call.
+        - `args` : Array(Variable length arguments) Argument values.
+        - `block` : Block. 
+    - Block Arguments
+        - `err` : If `nil`, the method calling succeed and the return value is bounded by `value`. If not `nil`, an exception is thrown within the method calling.
+            - `EPCRuntimeError` : An exception which is thrown by the peer's method.
+            - `EPCStackError` : An exception which is thrown by the EPC protocol stack.
+        - `value` : The return value which is returned by the peer process.
+
+*Sample Code*
+```ruby
+puts server.call_method("echo", "hello")
 
-### Call Remote Method
+server.call_method_async("echo", "hello") do |err, value|
+    puts value
+end
 
-### Error Handling
+puts server.call_method("add", 1, 2)
+
+server.call_method("add", 1, 2) do |err, value|
+    puts value
+end
+
+puts server.call_method("inject", 0, :+, [1,2,3,4])
+puts server.call_method("inject", 1, :*, [1,2,3,4])
+```
 
 ### Utilities
 
-### Define Server
+- `Elrpc::RPCService#query_methods`
+- `Elrpc::RPCService#query_methods_async`
+    - Return
+        - Array of method specs of the peer process.
+
+*Sample Code*
+```ruby
+server.query_methods
+ # => [[:echo, nil, nil], [:add, nil, nil], [:inject, "init, op, list", "Enumerable#inject"]]
+```
+
+### EPC Process
+
+Elrpc can implement the client process which starts a server process. The server process can be implemented in Ruby and the other language, such as Perl, Python and Emacs Lisp.
+
+- Module method `Elrpc::start_process(cmd)`
+    - Argument
+        - `cmd` : Array. Command line elements for the server process.
+    - Return
+        - An instance of `Elrpc::Service`.
+
+*Sample Code*
+```ruby
+cl = Elrpc.start_process(["ruby","echo.rb"])
+
+puts cl.call_method("echo", "1 hello")
+
+cl.stop
+```
+
+## Development
+
+In most cases, the client process is Emacs and the server one is implemented by Elrpc to extend Emacs functions in Ruby.
+However, it may be difficult to develop the programs which belong to the different environment.
+So, at first, it is better to implement both sides in Ruby and write tests.
+
+If you want to watch the STDOUT and STDERR of the server process, start the process from command line and connect to the process with `irb` or `pry`, like following:
+
+*Starting the server process*
+```
+$ bundle exec ruby echo.rb
+12345
+```
+
+`12345` is port number to connect from the client process. The number changes each time.
+Then, start `irb` in the another terminal.
+
+*Connecting to the process from irb*
+```
+$ bundle exec irb
+> require 'elrpc'
+> cl = Elrpc.start_client(12345)
+> cl.call_method("echo", "hello")
+```
+
+When you invoke `call_method`, the first terminal in which the server process runs, may show some output.
+
+## Performance
+
+EPC is designed for fast communication between Emacs and other processes.
+Employing S-exp serialization and keeping TCP connection, EPC is faster than HTTP-based RPC, such as JSON-RPC.
+
+Executing the benchmark program `test/echo-bench.rb`, You can check the performance in your environment. The program measures following aspects:
+
+- round trip time of method invocation
+    - synchronous/asynchronous calling
+- string transportation
+- array/list serialization and transportation
+- hash/alist serialization and transportation
+
+Here is the result on Lenovo X240 with Intel Core i7-4600U CPU 2.10GHz, 8GB RAM, ruby 2.1.4p265  x86_64-linux.
+
+```
+$ bundle exec ruby test/echo-bench.rb
+                 user     system      total        real
+int          0.180000   0.040000   0.220000 (  0.402582)
+int_a        0.180000   0.010000   0.190000 (  0.205672)
+string       0.390000   0.040000   0.430000 (  0.753418)
+array        1.410000   0.070000   1.480000 (  2.687667)
+hash         3.930000   0.070000   4.000000 (  7.632865)
+(call/sec) int: 9090.9  int_async: 10526.3  string: 4651.2  array: 1351.4  hash: 500.0
+```
 
-### Debug
+In the condition Ruby to Ruby, `elrpc` can perform around 10000 call/sec.
 
 ## License
 

data/elrpc.gemspec

@@ -20,6 +20,6 @@ Gem::Specification.new do |spec|
 
   spec.add_runtime_dependency "elparser", "~> 0.0"
   spec.add_development_dependency "bundler", "~> 1.7"
-  spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "test-unit", "~> 3.0"
+  spec.add_development_dependency "rake", "~> 10"
+  spec.add_development_dependency "test-unit", "~> 3"
 end

data/lib/elrpc/version.rb

@@ -1,3 +1,3 @@
 module Elrpc
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/lib/elrpc.rb

@@ -5,6 +5,7 @@ require "socket"
 require "thread"
 require "monitor"
 require "logger"
+require "open3"
 
 require "elparser"
 
@@ -72,17 +73,24 @@ module Elrpc
 
     def _start_logger
       return Thread.start do
+        stdout = @io3[1]
+        stderr = @io3[2]
         loop do
-          ret = @io.readline
-          break if ret.nil?
-          @logger.puts(ret) if @logger
+          IO.select([stdout, stderr]).flatten.compact.each do |io|
+            io.each do |line|
+              next if line.nil? || line.empty?
+              @logger.puts(line) if @logger
+            end
+          end
+          break if stdout.eof? && stderr.eof?
         end
       end
     end
 
     def start
-      @io = IO.popen(@cmd)
-      @port = @io.readline.to_i
+      @io3 = Open3.popen3(@cmd) # stdin, stdout, stderr, wait_thr
+      @port = @io3[2].readline.to_i
+      @io3[0].close
       @output = nil
       @thread = _start_logger
       @client = Elrpc.start_client(@port)
@@ -115,6 +123,8 @@ module Elrpc
 
     def stop
       @client.stop
+      @io3[1].close
+      @io3[2].close
     end
     
   end
@@ -149,6 +159,9 @@ module Elrpc
     def message
       "#{@_classname} : #{@_message}"
     end
+    def to_s
+      message
+    end
 
     def remote_classname
       @_classname
@@ -159,6 +172,7 @@ module Elrpc
     def remote_backtrace
       @_backtrace
     end
+
   end
 
   class EPCStackError < StandardError
@@ -171,6 +185,9 @@ module Elrpc
     def message
       "#{@_classname} : #{@_message}"
     end
+    def to_s
+      message
+    end
 
     def remote_classname
       @_classname

data/sample/echo-client.el

@@ -1,7 +1,7 @@
 (require 'epc)
 
 (let (epc)
-  ;; start a child process
+  ;; start a server process
   ;; bundle exec
   (setq epc (epc:start-epc "bundle" '("exec" "ruby" "echo.rb")))
 
@@ -21,7 +21,7 @@
   ;; synchronous calling (debug purpose)
   (message "%S" (epc:call-sync epc 'echo '(world)))
 
-  ;; 
+  ;; kill the server process
   (epc:stop-epc epc)
   )
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: elrpc
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - SAKURAI Masashi
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-17 00:00:00.000000000 Z
+date: 2015-12-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: elparser
@@ -44,28 +44,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '10'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '10'
 - !ruby/object:Gem::Dependency
   name: test-unit
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3'
 description: EPC (RPC stack for the Emacs Lisp) for Ruby.
 email:
 - m.sakurai@kiwanami.net
@@ -112,7 +112,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.3
+rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
 summary: EPC (RPC stack for the Emacs Lisp) for Ruby.