msgpack-rpc-stack 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd76cc71b043173ef94c8f7d21041a9ac2490c03f2cfc936ad3dddb3e0cb40b8
-  data.tar.gz: b0d2e72657bf2e3bca72870f9f1ca7388178cf33d708080a3f0ec32531aa2a47
+  metadata.gz: cf8e71b65201dd61e5b8259ee20d5f628c5a5a3bc3684b3d190ef94908ef5eec
+  data.tar.gz: '0289f60792cca6e01901e73e6a3b7cc68571cc7b07f839c533abc9ef2de97a13'
 SHA512:
-  metadata.gz: f8ae673b9d04a9ea9ff4baaad08b4d4c1af92df50f93f8f72fcc4941171c1c05eea8a8ff7438a43b92c804f79a3f1a64824ff8225e4a4e22fafc03896a864dc4
-  data.tar.gz: 74142d315c72fe443f8fcf5aaf952a453ffae01a19208d332a73ad93a662bb7690429f07aa8d73a543962cdf68b532cf3e31b1b13d969f171cfbc2948aa5cdaf
+  metadata.gz: d96dac975cdfd57084a1cd95810161f07555154b041cb81c938b7f6231c7463d147fcf2ad02deebc3ea7a4d595e09c162406854eef35fb7bc721a0a6b243d014
+  data.tar.gz: e7e52fac2bc255732ce7efe290bab9720482a17efe593c8bd61cc10399d029ece0e8f0205ce77af867aa79b7fd37031b4800a5c4fd0ae3575e2b86503421bce3

data/lib/msgpack/rpc/client.rb

@@ -12,6 +12,13 @@ require 'msgpack/rpc'
 
 module MessagePack
   module Rpc
+    #
+    # Module that implemented client protocol of MessagePack-RPC.
+    # 
+    # @abstract
+    #   Include from the class that implements the rpc client. 
+    #   If you receive a protocol level error, override the on_error method.
+    #
     module Client
       class << self
         def included(klass)
@@ -67,6 +74,27 @@ module MessagePack
       end
       private :error_occured
 
+      #
+      # call the procedure of peer rpc server
+      #
+      # @param [Symbol] meth
+      #   target procedure name.
+      #
+      # @param [Array] args
+      #   arguments for procedure.
+      #
+      # @return [Integer]
+      #   assigned mesaage id
+      #
+      # @yield [res, err]
+      #   callback that is when the procedure call completes.
+      #
+      # @yieldparam [Object] res
+      #   responce of procedure when procedure successed.
+      #
+      # @yieldparam [Object] err
+      #   error data of procedure when procedure failed.
+      #
       def call(meth, *args, &blk)
         raise ArgumentError.new("handler is not spcified") if not blk
 
@@ -78,14 +106,34 @@ module MessagePack
         return id
       end
 
-      def notify(meth, *args)
-        send_data([2, meth, args].to_msgpack)
-      end
-
+      #
+      # cacel the call message
+      #
+      # @param [Integer] id
+      #   message id of calling message (return value of
+      #   MessagePack::Rpc::Client#call())
+      #
+      # @note
+      #    When this method is called, the procedure call corresponding to
+      #   the ID specified in the argument is cancelled.
+      #
       def cancel(id)
         session_map.delete(id)
       end
 
+      #
+      # send the notification to peer rpc server
+      #
+      # @param [Symbol] meth
+      #   notify name
+      #
+      # @param [Array] args
+      #   argument for notification
+      #
+      def notify(meth, *args)
+        send_data([2, meth, args].to_msgpack)
+      end
+
       def eval_response(resp)
         if not resp.kind_of?(Array)
           error_occured("responce is not array")
@@ -128,10 +176,27 @@ module MessagePack
       end
       private :eval_response
 
+      #
+      # emqueu the received datagram to communication buffer
+      #
+      # @param [Blob] data
+      #   recevied data from rpc server.
+      #
+      # @note
+      #   Use this method for datagram communication. \
+      #   Use it when it is guaranteed that data is exchanged \
+      #   in packets (it works a bit faster).
+      #
       def receive_dgram(data)
         eval_response(MessagePack.unpack(data, self.class.msgpack_options))
       end
 
+      #
+      # emqueu the received data to communication buffer
+      #
+      # @param [Blob] data
+      #   recevied data from rpc server.
+      #
       def receive_stream(data)
         begin
           unpacker.feed_each(data) {|resp| eval_response(resp)}
@@ -145,6 +210,16 @@ module MessagePack
         end
       end
 
+      #
+      # define the notify method
+      #
+      # @param [Symbol] name
+      #   notification name
+      #
+      # @yield [*args]
+      #    callback that is when received the notification
+      #   from peer rpc server.
+      #
       def on(name, &blk)
         raise ArgumentError.new("handler is not spcified") if not blk
         notify_handler[name] = blk

data/lib/msgpack/rpc/server.rb

@@ -12,8 +12,82 @@ require 'msgpack/rpc'
 
 module MessagePack
   module Rpc
+
+    #
+    # Module that implemented server protocol of MessagePack-RPC.
+    # 
+    # @abstract
+    #   Include from the class that implements the rpc server. You can expose
+    #   If you receive a protocol level error, override the on_error method.
+    #   the methods defined in that class as RPC procedures.
+    #
     module Server
       class << self
+        #
+        # @!method msgpack_options(**opts)
+        #   set MessagePack::Unpacker option.
+        #
+        #   @example set :symbolize_keys option
+        #     class Server
+        #       include MessagePack::Rpc::Server
+        #
+        #       msgpack_options = {:symbolize_keys => true}
+        #
+        #       def test(data)
+        #         # data's key are symbolized.
+        #         return data[:data]
+        #       end
+        #       remote_public :test
+        #     end
+
+        #
+        # @!method remote_public(name)
+        #   expose syncronous procedure.
+        #   The return value of the method exposed by this method is the 
+        #   return value of the procedure. If an exception occurs, the
+        #   exception is returned as an error value.
+        #
+        #   @param [Symbol] name
+        #     target method name.
+        #
+        #   @example expose syncronous procedure
+        #     class Server
+        #       include MessagePack::Rpc::Server
+        #
+        #       def test(id)
+        #         raise("id isnot defined") if id.nil?
+        #         return "hello #{id}"
+        #       end
+        #       remote_public :test
+        #     end
+        #
+
+        #
+        # @!method remote_async(name)
+        #   expose asynchronous procedure.
+        #   The method exposed by this method takes a deferred object as its
+        #   first argument. Returns the processing result asynchronously
+        #   through this object.
+        #
+        #   @param [Symbol] name
+        #     target method name.
+        #
+        #   @example expose asyncronous procedure
+        #     class Server
+        #       include MessagePack::Rpc::Server
+        #
+        #       def test(df, id)
+        #         if id.nil?
+        #           df.reject("id isnot defined")
+        #         else
+        #           df.resolve("hello #{id}")
+        #         end
+        #       end
+        #       remote_async :test
+        #     end
+        #
+
+        # @!visibility protected
         def included(klass)
           m = Module.new {
             @@error = Class.new(StandardError) {
@@ -197,10 +271,30 @@ module MessagePack
       end
       private :eval_message
 
+      #
+      # send the notification to peer rpc client
+      #
+      # @param [Symbol] meth
+      #   notify name
+      #
+      # @param [Array] args
+      #   argument for notification
+      #
       def notify(meth, *args)
         send_data([2, meth, args].to_msgpack)
       end
 
+      #
+      # emqueu the received datagram to communication buffer
+      #
+      # @param [Blob] data
+      #   recevied data from peer rpc client.
+      #
+      # @note
+      #   Use this method for datagram communication. \
+      #   Use it when it is guaranteed that data is exchanged \
+      #   in packets (it works a bit faster).
+      #
       def receive_dgram(data)
         msg = MessagePack.unpack(data, self.class.msgpack_options)
 
@@ -211,6 +305,12 @@ module MessagePack
         eval_message(msg)
       end
 
+      #
+      # emqueu the received data to communication buffer
+      #
+      # @param [Blob] data
+      #   recevied data from peer rpc client.
+      #
       def receive_stream(data)
         begin
           unpacker.feed_each(data) {|msg| eval_message(msg)}

data/lib/msgpack/rpc/version.rb

@@ -1,5 +1,5 @@
 module MessagePack
   module Rpc
-    VERSION = "0.7.0"
+    VERSION = "0.7.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: msgpack-rpc-stack
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Hiroshi Kuwagata