Incorporating ruby into the master grpc repository.
Change on 2014/12/01 by nnoble <nnoble@google.com>
-------------
Created by MOE: http://code.google.com/p/moe-java
MOE_MIGRATED_REVID=81111468
diff --git a/src/ruby/lib/grpc/errors.rb b/src/ruby/lib/grpc/errors.rb
new file mode 100644
index 0000000..d14e69c
--- /dev/null
+++ b/src/ruby/lib/grpc/errors.rb
@@ -0,0 +1,68 @@
+# Copyright 2014, Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+# * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+require 'grpc'
+
+module Google
+
+ module RPC
+
+ # OutOfTime is an exception class that indicates that an RPC exceeded its
+ # deadline.
+ OutOfTime = Class.new(StandardError)
+
+ # BadStatus is an exception class that indicates that an error occurred at
+ # either end of a GRPC connection. When raised, it indicates that a status
+ # error should be returned to the other end of a GRPC connection; when
+ # caught it means that this end received a status error.
+ class BadStatus < StandardError
+
+ attr_reader :code, :details
+
+ # @param code [Numeric] the status code
+ # @param details [String] the details of the exception
+ def initialize(code, details='unknown cause')
+ super("#{code}:#{details}")
+ @code = code
+ @details = details
+ end
+
+ # Converts the exception to a GRPC::Status for use in the networking
+ # wrapper layer.
+ #
+ # @return [Status] with the same code and details
+ def to_status
+ Status.new(code, details)
+ end
+
+ end
+
+ end
+
+end
diff --git a/src/ruby/lib/grpc/event.rb b/src/ruby/lib/grpc/event.rb
new file mode 100644
index 0000000..c108cd4
--- /dev/null
+++ b/src/ruby/lib/grpc/event.rb
@@ -0,0 +1,38 @@
+# Copyright 2014, Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+# * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+module Google
+ module RPC
+ class Event # Add an inspect method to C-defined Event class.
+ def inspect
+ '<%s: type:%s, tag:%s result:%s>' % [self.class, type, tag, result]
+ end
+ end
+ end
+end
diff --git a/src/ruby/lib/grpc/generic/active_call.rb b/src/ruby/lib/grpc/generic/active_call.rb
new file mode 100644
index 0000000..d987b39
--- /dev/null
+++ b/src/ruby/lib/grpc/generic/active_call.rb
@@ -0,0 +1,485 @@
+# Copyright 2014, Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+# * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+require 'forwardable'
+require 'grpc'
+require 'grpc/generic/bidi_call'
+
+def assert_event_type(got, want)
+ raise 'Unexpected rpc event: got %s, want %s' % [got, want] unless got == want
+end
+
+module GRPC
+
+ # The ActiveCall class provides simple methods for sending marshallable
+ # data to a call
+ class ActiveCall
+ include CompletionType
+ include StatusCodes
+ attr_reader(:deadline)
+
+ # client_start_invoke begins a client invocation.
+ #
+ # Flow Control note: this blocks until flow control accepts that client
+ # request can go ahead.
+ #
+ # deadline is the absolute deadline for the call.
+ #
+ # @param call [Call] a call on which to start and invocation
+ # @param q [CompletionQueue] used to wait for INVOKE_ACCEPTED
+ # @param deadline [Fixnum,TimeSpec] the deadline for INVOKE_ACCEPTED
+ def self.client_start_invoke(call, q, deadline)
+ raise ArgumentError.new('not a call') unless call.is_a?Call
+ if !q.is_a?CompletionQueue
+ raise ArgumentError.new('not a CompletionQueue')
+ end
+ invoke_accepted, client_metadata_read = Object.new, Object.new
+ finished_tag = Object.new
+ call.start_invoke(q, invoke_accepted, client_metadata_read, finished_tag)
+ # wait for the invocation to be accepted
+ ev = q.pluck(invoke_accepted, TimeConsts::INFINITE_FUTURE)
+ raise OutOfTime if ev.nil?
+ finished_tag
+ end
+
+ # Creates an ActiveCall.
+ #
+ # ActiveCall should only be created after a call is accepted. That means
+ # different things on a client and a server. On the client, the call is
+ # accepted after call.start_invoke followed by receipt of the
+ # corresponding INVOKE_ACCEPTED. on the server, this is after
+ # call.accept.
+ #
+ # #initialize cannot determine if the call is accepted or not; so if a
+ # call that's not accepted is used here, the error won't be visible until
+ # the ActiveCall methods are called.
+ #
+ # deadline is the absolute deadline for the call.
+ #
+ # @param call [Call] the call used by the ActiveCall
+ # @param q [CompletionQueue] the completion queue used to accept
+ # the call
+ # @param marshal [Function] f(obj)->string that marshal requests
+ # @param unmarshal [Function] f(string)->obj that unmarshals responses
+ # @param deadline [Fixnum] the deadline for the call to complete
+ # @param finished_tag [Object] the object used as the call's finish tag,
+ # if the call has begun
+ # @param started [true|false] (default true) indicates if the call has begun
+ def initialize(call, q, marshal, unmarshal, deadline, finished_tag: nil,
+ started: true)
+ raise ArgumentError.new('not a call') unless call.is_a?Call
+ if !q.is_a?CompletionQueue
+ raise ArgumentError.new('not a CompletionQueue')
+ end
+ @call = call
+ @cq = q
+ @deadline = deadline
+ @finished_tag = finished_tag
+ @marshal = marshal
+ @started = started
+ @unmarshal = unmarshal
+ end
+
+ # Obtains the status of the call.
+ #
+ # this value is nil until the call completes
+ # @return this call's status
+ def status
+ @call.status
+ end
+
+ # Obtains the metadata of the call.
+ #
+ # At the start of the call this will be nil. During the call this gets
+ # some values as soon as the other end of the connection acknowledges the
+ # request.
+ #
+ # @return this calls's metadata
+ def metadata
+ @call.metadata
+ end
+
+ # Cancels the call.
+ #
+ # Cancels the call. The call does not return any result, but once this it
+ # has been called, the call should eventually terminate. Due to potential
+ # races between the execution of the cancel and the in-flight request, the
+ # result of the call after calling #cancel is indeterminate:
+ #
+ # - the call may terminate with a BadStatus exception, with code=CANCELLED
+ # - the call may terminate with OK Status, and return a response
+ # - the call may terminate with a different BadStatus exception if that was
+ # happening
+ def cancel
+ @call.cancel
+ end
+
+ # indicates if the call is shutdown
+ def shutdown
+ @shutdown ||= false
+ end
+
+ # indicates if the call is cancelled.
+ def cancelled
+ @cancelled ||= false
+ end
+
+ # multi_req_view provides a restricted view of this ActiveCall for use
+ # in a server client-streaming handler.
+ def multi_req_view
+ MultiReqView.new(self)
+ end
+
+ # single_req_view provides a restricted view of this ActiveCall for use in
+ # a server request-response handler.
+ def single_req_view
+ SingleReqView.new(self)
+ end
+
+ # operation provides a restricted view of this ActiveCall for use as
+ # a Operation.
+ def operation
+ Operation.new(self)
+ end
+
+ # writes_done indicates that all writes are completed.
+ #
+ # It blocks until the remote endpoint acknowledges by sending a FINISHED
+ # event, unless assert_finished is set to false. Any calls to
+ # #remote_send after this call will fail.
+ #
+ # @param assert_finished [true, false] when true(default), waits for
+ # FINISHED.
+ def writes_done(assert_finished=true)
+ @call.writes_done(self)
+ ev = @cq.pluck(self, TimeConsts::INFINITE_FUTURE)
+ assert_event_type(ev.type, FINISH_ACCEPTED)
+ logger.debug("Writes done: waiting for finish? #{assert_finished}")
+ if assert_finished
+ ev = @cq.pluck(@finished_tag, TimeConsts::INFINITE_FUTURE)
+ raise "unexpected event: #{ev.inspect}" if ev.nil?
+ return @call.status
+ end
+ end
+
+ # finished waits until the call is completed.
+ #
+ # It blocks until the remote endpoint acknowledges by sending a FINISHED
+ # event.
+ def finished
+ ev = @cq.pluck(@finished_tag, TimeConsts::INFINITE_FUTURE)
+ raise "unexpected event: #{ev.inspect}" unless ev.type == FINISHED
+ if ev.result.code != StatusCodes::OK
+ raise BadStatus.new(ev.result.code, ev.result.details)
+ end
+ res = ev.result
+
+ # NOTE(temiola): This is necessary to allow the C call struct wrapped
+ # within the active_call to be GCed; this is necessary so that other
+ # C-level destructors get called in the required order.
+ ev = nil # allow the event to be GCed
+ res
+ end
+
+ # remote_send sends a request to the remote endpoint.
+ #
+ # It blocks until the remote endpoint acknowledges by sending a
+ # WRITE_ACCEPTED. req can be marshalled already.
+ #
+ # @param req [Object, String] the object to send or it's marshal form.
+ # @param marshalled [false, true] indicates if the object is already
+ # marshalled.
+ def remote_send(req, marshalled=false)
+ assert_queue_is_ready
+ logger.debug("sending payload #{req.inspect}, marshalled? #{marshalled}")
+ if marshalled
+ payload = req
+ else
+ payload = @marshal.call(req)
+ end
+ @call.start_write(ByteBuffer.new(payload), self)
+
+ # call queue#pluck, and wait for WRITE_ACCEPTED, so as not to return
+ # until the flow control allows another send on this call.
+ ev = @cq.pluck(self, TimeConsts::INFINITE_FUTURE)
+ assert_event_type(ev.type, WRITE_ACCEPTED)
+ ev = nil
+ end
+
+ # send_status sends a status to the remote endpoint
+ #
+ # @param code [int] the status code to send
+ # @param details [String] details
+ # @param assert_finished [true, false] when true(default), waits for
+ # FINISHED.
+ def send_status(code=OK, details='', assert_finished=false)
+ assert_queue_is_ready
+ @call.start_write_status(Status.new(code, details), self)
+ ev = @cq.pluck(self, TimeConsts::INFINITE_FUTURE)
+ assert_event_type(ev.type, FINISH_ACCEPTED)
+ logger.debug("Status sent: #{code}:'#{details}'")
+ if assert_finished
+ return finished
+ end
+ nil
+ end
+
+ # remote_read reads a response from the remote endpoint.
+ #
+ # It blocks until the remote endpoint sends a READ or FINISHED event. On
+ # a READ, it returns the response after unmarshalling it. On
+ # FINISHED, it returns nil if the status is OK, otherwise raising BadStatus
+ def remote_read
+ @call.start_read(self)
+ ev = @cq.pluck(self, TimeConsts::INFINITE_FUTURE)
+ assert_event_type(ev.type, READ)
+ logger.debug("received req: #{ev.result.inspect}")
+ if !ev.result.nil?
+ logger.debug("received req.to_s: #{ev.result.to_s}")
+ res = @unmarshal.call(ev.result.to_s)
+ logger.debug("received_req (unmarshalled): #{res.inspect}")
+ return res
+ end
+ logger.debug('found nil; the final response has been sent')
+ nil
+ end
+
+ # each_remote_read passes each response to the given block or returns an
+ # enumerator the responses if no block is given.
+ #
+ # == Enumerator ==
+ #
+ # * #next blocks until the remote endpoint sends a READ or FINISHED
+ # * for each read, enumerator#next yields the response
+ # * on status
+ # * if it's is OK, enumerator#next raises StopException
+ # * if is not OK, enumerator#next raises RuntimeException
+ #
+ # == Block ==
+ #
+ # * if provided it is executed for each response
+ # * the call blocks until no more responses are provided
+ #
+ # @return [Enumerator] if no block was given
+ def each_remote_read
+ return enum_for(:each_remote_read) if !block_given?
+ loop do
+ resp = remote_read()
+ break if resp.is_a?Status # this will be an OK status, bad statii raise
+ break if resp.nil? # the last response was received
+ yield resp
+ end
+ end
+
+ # each_remote_read_then_finish passes each response to the given block or
+ # returns an enumerator of the responses if no block is given.
+ #
+ # It is like each_remote_read, but it blocks on finishing on detecting
+ # the final message.
+ #
+ # == Enumerator ==
+ #
+ # * #next blocks until the remote endpoint sends a READ or FINISHED
+ # * for each read, enumerator#next yields the response
+ # * on status
+ # * if it's is OK, enumerator#next raises StopException
+ # * if is not OK, enumerator#next raises RuntimeException
+ #
+ # == Block ==
+ #
+ # * if provided it is executed for each response
+ # * the call blocks until no more responses are provided
+ #
+ # @return [Enumerator] if no block was given
+ def each_remote_read_then_finish
+ return enum_for(:each_remote_read_then_finish) if !block_given?
+ loop do
+ resp = remote_read
+ break if resp.is_a?Status # this will be an OK status, bad statii raise
+ if resp.nil? # the last response was received, but not finished yet
+ finished
+ break
+ end
+ yield resp
+ end
+ end
+
+ # request_response sends a request to a GRPC server, and returns the
+ # response.
+ # @param req [Object] the request sent to the server
+ # @return [Object] the response received from the server
+ def request_response(req)
+ start_call unless @started
+ remote_send(req)
+ writes_done(false)
+ response = remote_read
+ if !response.is_a?(Status) # finish if status not yet received
+ finished
+ end
+ response
+ end
+
+ # client_streamer sends a stream of requests to a GRPC server, and
+ # returns a single response.
+ #
+ # requests provides an 'iterable' of Requests. I.e. it follows Ruby's
+ # #each enumeration protocol. In the simplest case, requests will be an
+ # array of marshallable objects; in typical case it will be an Enumerable
+ # that allows dynamic construction of the marshallable objects.
+ #
+ # @param requests [Object] an Enumerable of requests to send
+ # @return [Object] the response received from the server
+ def client_streamer(requests)
+ start_call unless @started
+ requests.each { |r| remote_send(r) }
+ writes_done(false)
+ response = remote_read
+ if !response.is_a?(Status) # finish if status not yet received
+ finished
+ end
+ response
+ end
+
+ # server_streamer sends one request to the GRPC server, which yields a
+ # stream of responses.
+ #
+ # responses provides an enumerator over the streamed responses, i.e. it
+ # follows Ruby's #each iteration protocol. The enumerator blocks while
+ # waiting for each response, stops when the server signals that no
+ # further responses will be supplied. If the implicit block is provided,
+ # it is executed with each response as the argument and no result is
+ # returned.
+ #
+ # @param req [Object] the request sent to the server
+ # @return [Enumerator|nil] a response Enumerator
+ def server_streamer(req)
+ start_call unless @started
+ remote_send(req)
+ writes_done(false)
+ replies = enum_for(:each_remote_read_then_finish)
+ return replies if !block_given?
+ replies.each { |r| yield r }
+ end
+
+ # bidi_streamer sends a stream of requests to the GRPC server, and yields
+ # a stream of responses.
+ #
+ # This method takes an Enumerable of requests, and returns and enumerable
+ # of responses.
+ #
+ # == requests ==
+ #
+ # requests provides an 'iterable' of Requests. I.e. it follows Ruby's #each
+ # enumeration protocol. In the simplest case, requests will be an array of
+ # marshallable objects; in typical case it will be an Enumerable that
+ # allows dynamic construction of the marshallable objects.
+ #
+ # == responses ==
+ #
+ # This is an enumerator of responses. I.e, its #next method blocks
+ # waiting for the next response. Also, if at any point the block needs
+ # to consume all the remaining responses, this can be done using #each or
+ # #collect. Calling #each or #collect should only be done if
+ # the_call#writes_done has been called, otherwise the block will loop
+ # forever.
+ #
+ # @param requests [Object] an Enumerable of requests to send
+ # @return [Enumerator, nil] a response Enumerator
+ def bidi_streamer(requests, &blk)
+ start_call unless @started
+ bd = BidiCall.new(@call, @cq, @marshal, @unmarshal, @deadline,
+ @finished_tag)
+ bd.run_on_client(requests, &blk)
+ end
+
+ # run_server_bidi orchestrates a BiDi stream processing on a server.
+ #
+ # N.B. gen_each_reply is a func(Enumerable<Requests>)
+ #
+ # It takes an enumerable of requests as an arg, in case there is a
+ # relationship between the stream of requests and the stream of replies.
+ #
+ # This does not mean that must necessarily be one. E.g, the replies
+ # produced by gen_each_reply could ignore the received_msgs
+ #
+ # @param gen_each_reply [Proc] generates the BiDi stream replies
+ def run_server_bidi(gen_each_reply)
+ bd = BidiCall.new(@call, @cq, @marshal, @unmarshal, @deadline,
+ @finished_tag)
+ bd.run_on_server(gen_each_reply)
+ end
+
+ private
+
+ def start_call
+ @finished_tag = ActiveCall.client_start_invoke(@call, @cq, @deadline)
+ @started = true
+ end
+
+ def self.view_class(*visible_methods)
+ Class.new do
+ extend ::Forwardable
+ def_delegators :@wrapped, *visible_methods
+
+ # @param wrapped [ActiveCall] the call whose methods are shielded
+ def initialize(wrapped)
+ @wrapped = wrapped
+ end
+ end
+ end
+
+ # SingleReqView limits access to an ActiveCall's methods for use in server
+ # handlers that receive just one request.
+ SingleReqView = view_class(:cancelled, :deadline)
+
+ # MultiReqView limits access to an ActiveCall's methods for use in
+ # server client_streamer handlers.
+ MultiReqView = view_class(:cancelled, :deadline, :each_queued_msg,
+ :each_remote_read)
+
+ # Operation limits access to an ActiveCall's methods for use as
+ # a Operation on the client.
+ Operation = view_class(:cancel, :cancelled, :deadline, :execute, :metadata,
+ :status)
+
+ # confirms that no events are enqueued, and that the queue is not
+ # shutdown.
+ def assert_queue_is_ready
+ begin
+ ev = @cq.pluck(self, TimeConsts::ZERO)
+ raise "unexpected event #{ev.inspect}" unless ev.nil?
+ rescue OutOfTime
+ # expected, nothing should be on the queue and the deadline was ZERO,
+ # except things using another tag
+ end
+ end
+
+ end
+
+end
diff --git a/src/ruby/lib/grpc/generic/bidi_call.rb b/src/ruby/lib/grpc/generic/bidi_call.rb
new file mode 100644
index 0000000..a3566e1
--- /dev/null
+++ b/src/ruby/lib/grpc/generic/bidi_call.rb
@@ -0,0 +1,320 @@
+# Copyright 2014, Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+# * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+require 'forwardable'
+require 'grpc'
+
+module GRPC
+
+ # The BiDiCall class orchestrates exection of a BiDi stream on a client or
+ # server.
+ class BidiCall
+ include CompletionType
+ include StatusCodes
+
+ # Creates a BidiCall.
+ #
+ # BidiCall should only be created after a call is accepted. That means
+ # different things on a client and a server. On the client, the call is
+ # accepted after call.start_invoke followed by receipt of the corresponding
+ # INVOKE_ACCEPTED. On the server, this is after call.accept.
+ #
+ # #initialize cannot determine if the call is accepted or not; so if a
+ # call that's not accepted is used here, the error won't be visible until
+ # the BidiCall#run is called.
+ #
+ # deadline is the absolute deadline for the call.
+ #
+ # @param call [Call] the call used by the ActiveCall
+ # @param q [CompletionQueue] the completion queue used to accept
+ # the call
+ # @param marshal [Function] f(obj)->string that marshal requests
+ # @param unmarshal [Function] f(string)->obj that unmarshals responses
+ # @param deadline [Fixnum] the deadline for the call to complete
+ # @param finished_tag [Object] the object used as the call's finish tag,
+ def initialize(call, q, marshal, unmarshal, deadline, finished_tag)
+ raise ArgumentError.new('not a call') unless call.is_a?Call
+ if !q.is_a?CompletionQueue
+ raise ArgumentError.new('not a CompletionQueue')
+ end
+ @call = call
+ @cq = q
+ @deadline = deadline
+ @finished_tag = finished_tag
+ @marshal = marshal
+ @readq = Queue.new
+ @unmarshal = unmarshal
+ @writeq = Queue.new
+ end
+
+ # Begins orchestration of the Bidi stream for a client sending requests.
+ #
+ # The method either returns an Enumerator of the responses, or accepts a
+ # block that can be invoked with each response.
+ #
+ # @param requests the Enumerable of requests to send
+ # @return an Enumerator of requests to yield
+ def run_on_client(requests, &blk)
+ enq_th = enqueue_for_sending(requests)
+ loop_th = start_read_write_loop
+ replies = each_queued_msg
+ return replies if blk.nil?
+ replies.each { |r| blk.call(r) }
+ end
+
+ # Begins orchestration of the Bidi stream for a server generating replies.
+ #
+ # N.B. gen_each_reply is a func(Enumerable<Requests>)
+ #
+ # It takes an enumerable of requests as an arg, in case there is a
+ # relationship between the stream of requests and the stream of replies.
+ #
+ # This does not mean that must necessarily be one. E.g, the replies
+ # produced by gen_each_reply could ignore the received_msgs
+ #
+ # @param gen_each_reply [Proc] generates the BiDi stream replies.
+ def run_on_server(gen_each_reply)
+ replys = gen_each_reply.call(each_queued_msg)
+ enq_th = enqueue_for_sending(replys)
+ loop_th = start_read_write_loop(is_client:false)
+ loop_th.join
+ enq_th.join
+ end
+
+ private
+
+ END_OF_READS = :end_of_reads
+ END_OF_WRITES = :end_of_writes
+
+ # each_queued_msg yields each message on this instances readq
+ #
+ # - messages are added to the readq by #read_write_loop
+ # - iteration ends when the instance itself is added
+ def each_queued_msg
+ return enum_for(:each_queued_msg) if !block_given?
+ count = 0
+ loop do
+ logger.debug("each_queued_msg: msg##{count}")
+ count += 1
+ req = @readq.pop
+ throw req if req.is_a?StandardError
+ break if req.equal?(END_OF_READS)
+ yield req
+ end
+ end
+
+ # during bidi-streaming, read the requests to send from a separate thread
+ # read so that read_write_loop does not block waiting for requests to read.
+ def enqueue_for_sending(requests)
+ Thread.new do # TODO(temiola) run on a thread pool
+ begin
+ requests.each { |req| @writeq.push(req)}
+ @writeq.push(END_OF_WRITES)
+ rescue StandardError => e
+ logger.warn('enqueue_for_sending failed')
+ logger.warn(e)
+ @writeq.push(e)
+ end
+ end
+ end
+
+ # starts the read_write loop
+ def start_read_write_loop(is_client: true)
+ t = Thread.new do
+ begin
+ read_write_loop(is_client: is_client)
+ rescue StandardError => e
+ logger.warn('start_read_write_loop failed')
+ logger.warn(e)
+ @readq.push(e) # let each_queued_msg terminate with the error
+ end
+ end
+ t.priority = 3 # hint that read_write_loop threads should be favoured
+ t
+ end
+
+ # drain_writeq removes any outstanding message on the writeq
+ def drain_writeq
+ while @writeq.size != 0 do
+ discarded = @writeq.pop
+ logger.warn("discarding: queued write: #{discarded}")
+ end
+ end
+
+ # sends the next queued write
+ #
+ # The return value is an array with three values
+ # - the first indicates if a writes was started
+ # - the second that all writes are done
+ # - the third indicates that are still writes to perform but they are lates
+ #
+ # If value pulled from writeq is a StandardError, the producer hit an error
+ # that should be raised.
+ #
+ # @param is_client [Boolean] when true, writes_done will be called when the
+ # last entry is read from the writeq
+ #
+ # @return [in_write, done_writing]
+ def next_queued_write(is_client: true)
+ in_write, done_writing = false, false
+
+ # send the next item on the queue if there is any
+ return [in_write, done_writing] if @writeq.size == 0
+
+ # TODO(temiola): provide a queue class that returns nil after a timeout
+ req = @writeq.pop
+ if req.equal?(END_OF_WRITES)
+ logger.debug('done writing after last req')
+ if is_client
+ logger.debug('sent writes_done after last req')
+ @call.writes_done(self)
+ end
+ done_writing = true
+ return [in_write, done_writing]
+ elsif req.is_a?(StandardError) # used to signal an error in the producer
+ logger.debug('done writing due to a failure')
+ if is_client
+ logger.debug('sent writes_done after a failure')
+ @call.writes_done(self)
+ end
+ logger.warn(req)
+ done_writing = true
+ return [in_write, done_writing]
+ end
+
+ # send the payload
+ payload = @marshal.call(req)
+ @call.start_write(ByteBuffer.new(payload), self)
+ logger.debug("rwloop: sent payload #{req.inspect}")
+ in_write = true
+ return [in_write, done_writing]
+ end
+
+ # read_write_loop takes items off the write_queue and sends them, reads
+ # msgs and adds them to the read queue.
+ def read_write_loop(is_client: true)
+ done_reading, done_writing = false, false
+ finished, pre_finished = false, false
+ in_write, writes_late = false, false
+ count = 0
+
+ # queue the initial read before beginning the loop
+ @call.start_read(self)
+
+ loop do
+ # whether or not there are outstanding writes is independent of the
+ # next event from the completion queue. The producer may queue the
+ # first msg at any time, e.g, after the loop is started running. So,
+ # it's essential for the loop to check for possible writes here, in
+ # order to correctly begin writing.
+ if !in_write and !done_writing
+ in_write, done_writing = next_queued_write(is_client: is_client)
+ end
+ logger.debug("rwloop is_client? #{is_client}")
+ logger.debug("rwloop count: #{count}")
+ count += 1
+
+ # Loop control:
+ #
+ # - Break when no further events need to read. On clients, this means
+ # waiting for a FINISHED, servers just need to wait for all reads and
+ # writes to be done.
+ #
+ # - Also, don't read an event unless there's one expected. This can
+ # happen, e.g, when all the reads are done, there are no writes
+ # available, but writing is not complete.
+ logger.debug("done_reading? #{done_reading}")
+ logger.debug("done_writing? #{done_writing}")
+ logger.debug("finish accepted? #{pre_finished}")
+ logger.debug("finished? #{finished}")
+ logger.debug("in write? #{in_write}")
+ if is_client
+ break if done_writing and done_reading and pre_finished and finished
+ logger.debug('waiting for another event')
+ if in_write or !done_reading or !pre_finished
+ logger.debug('waiting for another event')
+ ev = @cq.pluck(self, TimeConsts::INFINITE_FUTURE)
+ elsif !finished
+ logger.debug('waiting for another event')
+ ev = @cq.pluck(@finish_tag, TimeConsts::INFINITE_FUTURE)
+ else
+ next # no events to wait on, but not done writing
+ end
+ else
+ break if done_writing and done_reading
+ if in_write or !done_reading
+ logger.debug('waiting for another event')
+ ev = @cq.pluck(self, TimeConsts::INFINITE_FUTURE)
+ else
+ next # no events to wait on, but not done writing
+ end
+ end
+
+ # handle the next event.
+ if ev.nil?
+ drain_writeq
+ raise OutOfTime
+ elsif ev.type == WRITE_ACCEPTED
+ logger.debug('write accepted!')
+ in_write = false
+ next
+ elsif ev.type == FINISH_ACCEPTED
+ logger.debug('finish accepted!')
+ pre_finished = true
+ next
+ elsif ev.type == READ
+ logger.debug("received req: #{ev.result.inspect}")
+ if ev.result.nil?
+ logger.debug('done reading!')
+ done_reading = true
+ @readq.push(END_OF_READS)
+ else
+ # push the latest read onto the queue and continue reading
+ logger.debug("received req.to_s: #{ev.result.to_s}")
+ res = @unmarshal.call(ev.result.to_s)
+ logger.debug("req (unmarshalled): #{res.inspect}")
+ @readq.push(res)
+ if !done_reading
+ @call.start_read(self)
+ end
+ end
+ elsif ev.type == FINISHED
+ logger.debug("finished! with status:#{ev.result.inspect}")
+ finished = true
+ ev.call.status = ev.result
+ if ev.result.code != OK
+ raise BadStatus.new(ev.result.code, ev.result.details)
+ end
+ end
+ end
+ end
+
+ end
+
+end
diff --git a/src/ruby/lib/grpc/generic/client_stub.rb b/src/ruby/lib/grpc/generic/client_stub.rb
new file mode 100644
index 0000000..fee31e3
--- /dev/null
+++ b/src/ruby/lib/grpc/generic/client_stub.rb
@@ -0,0 +1,358 @@
+# Copyright 2014, Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+# * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+require 'grpc'
+require 'grpc/generic/active_call'
+require 'xray/thread_dump_signal_handler'
+
+module GRPC
+
+ # ClientStub represents an endpoint used to send requests to GRPC servers.
+ class ClientStub
+ include StatusCodes
+
+ # Default deadline is 5 seconds.
+ DEFAULT_DEADLINE = 5
+
+ # Creates a new ClientStub.
+ #
+ # Minimally, a stub is created with the just the host of the gRPC service
+ # it wishes to access, e.g.,
+ #
+ # my_stub = ClientStub.new(example.host.com:50505)
+ #
+ # Any arbitrary keyword arguments are treated as channel arguments used to
+ # configure the RPC connection to the host.
+ #
+ # There are two specific keywords are that not used to configure the
+ # channel:
+ #
+ # - :channel_override
+ # when present, this must be a pre-created GRPC::Channel. If it's present
+ # the host and arbitrary keyword arg areignored, and the RPC connection uses
+ # this channel.
+ #
+ # - :deadline
+ # when present, this is the default deadline used for calls
+ #
+ # @param host [String] the host the stub connects to
+ # @param q [TaggedCompletionQueue] used to wait for events
+ # @param channel_override [Channel] a pre-created channel
+ # @param deadline [Number] the default deadline to use in requests
+ # @param kw [KeywordArgs] the channel arguments
+ def initialize(host, q,
+ channel_override:nil,
+ deadline:DEFAULT_DEADLINE,
+ **kw)
+ if !q.is_a?CompletionQueue
+ raise ArgumentError.new('not a CompletionQueue')
+ end
+ @host = host
+ if !channel_override.nil?
+ ch = channel_override
+ raise ArgumentError.new('not a Channel') unless ch.is_a?(Channel)
+ else
+ ch = Channel.new(host, **kw)
+ end
+
+ @deadline = deadline
+ @ch = ch
+ @queue = q
+ end
+
+ # request_response sends a request to a GRPC server, and returns the
+ # response.
+ #
+ # == Flow Control ==
+ # This is a blocking call.
+ #
+ # * it does not return until a response is received.
+ #
+ # * the requests is sent only when GRPC core's flow control allows it to
+ # be sent.
+ #
+ # == Errors ==
+ # An RuntimeError is raised if
+ #
+ # * the server responds with a non-OK status
+ #
+ # * the deadline is exceeded
+ #
+ # == Return Value ==
+ #
+ # If return_op is false, the call returns the response
+ #
+ # If return_op is true, the call returns an Operation, calling execute
+ # on the Operation returns the response.
+ #
+ # @param method [String] the RPC method to call on the GRPC server
+ # @param req [Object] the request sent to the server
+ # @param marshal [Function] f(obj)->string that marshals requests
+ # @param unmarshal [Function] f(string)->obj that unmarshals responses
+ # @param deadline [Numeric] (optional) the max completion time in seconds
+ # @param return_op [true|false] (default false) return an Operation if true
+ # @return [Object] the response received from the server
+ def request_response(method, req, marshal, unmarshal, deadline=nil,
+ return_op:false)
+ c = new_active_call(method, marshal, unmarshal, deadline || @deadline)
+ return c.request_response(req) unless return_op
+
+ # return the operation view of the active_call; define #execute as a
+ # new method for this instance that invokes #request_response.
+ op = c.operation
+ op.define_singleton_method(:execute) do
+ c.request_response(req)
+ end
+ op
+ end
+
+ # client_streamer sends a stream of requests to a GRPC server, and
+ # returns a single response.
+ #
+ # requests provides an 'iterable' of Requests. I.e. it follows Ruby's
+ # #each enumeration protocol. In the simplest case, requests will be an
+ # array of marshallable objects; in typical case it will be an Enumerable
+ # that allows dynamic construction of the marshallable objects.
+ #
+ # == Flow Control ==
+ # This is a blocking call.
+ #
+ # * it does not return until a response is received.
+ #
+ # * each requests is sent only when GRPC core's flow control allows it to
+ # be sent.
+ #
+ # == Errors ==
+ # An RuntimeError is raised if
+ #
+ # * the server responds with a non-OK status
+ #
+ # * the deadline is exceeded
+ #
+ # == Return Value ==
+ #
+ # If return_op is false, the call consumes the requests and returns
+ # the response.
+ #
+ # If return_op is true, the call returns the response.
+ #
+ # @param method [String] the RPC method to call on the GRPC server
+ # @param requests [Object] an Enumerable of requests to send
+ # @param marshal [Function] f(obj)->string that marshals requests
+ # @param unmarshal [Function] f(string)->obj that unmarshals responses
+ # @param deadline [Numeric] the max completion time in seconds
+ # @param return_op [true|false] (default false) return an Operation if true
+ # @return [Object|Operation] the response received from the server
+ def client_streamer(method, requests, marshal, unmarshal, deadline=nil,
+ return_op:false)
+ c = new_active_call(method, marshal, unmarshal, deadline || @deadline)
+ return c.client_streamer(requests) unless return_op
+
+ # return the operation view of the active_call; define #execute as a
+ # new method for this instance that invokes #client_streamer.
+ op = c.operation
+ op.define_singleton_method(:execute) do
+ c.client_streamer(requests)
+ end
+ op
+ end
+
+ # server_streamer sends one request to the GRPC server, which yields a
+ # stream of responses.
+ #
+ # responses provides an enumerator over the streamed responses, i.e. it
+ # follows Ruby's #each iteration protocol. The enumerator blocks while
+ # waiting for each response, stops when the server signals that no
+ # further responses will be supplied. If the implicit block is provided,
+ # it is executed with each response as the argument and no result is
+ # returned.
+ #
+ # == Flow Control ==
+ # This is a blocking call.
+ #
+ # * the request is sent only when GRPC core's flow control allows it to
+ # be sent.
+ #
+ # * the request will not complete until the server sends the final response
+ # followed by a status message.
+ #
+ # == Errors ==
+ # An RuntimeError is raised if
+ #
+ # * the server responds with a non-OK status when any response is
+ # * retrieved
+ #
+ # * the deadline is exceeded
+ #
+ # == Return Value ==
+ #
+ # if the return_op is false, the return value is an Enumerator of the
+ # results, unless a block is provided, in which case the block is
+ # executed with each response.
+ #
+ # if return_op is true, the function returns an Operation whose #execute
+ # method runs server streamer call. Again, Operation#execute either
+ # calls the given block with each response or returns an Enumerator of the
+ # responses.
+ #
+ # @param method [String] the RPC method to call on the GRPC server
+ # @param req [Object] the request sent to the server
+ # @param marshal [Function] f(obj)->string that marshals requests
+ # @param unmarshal [Function] f(string)->obj that unmarshals responses
+ # @param deadline [Numeric] the max completion time in seconds
+ # @param return_op [true|false] (default false) return an Operation if true
+ # @param blk [Block] when provided, is executed for each response
+ # @return [Enumerator|Operation|nil] as discussed above
+ def server_streamer(method, req, marshal, unmarshal, deadline=nil,
+ return_op:false, &blk)
+ c = new_active_call(method, marshal, unmarshal, deadline || @deadline)
+ return c.server_streamer(req, &blk) unless return_op
+
+ # return the operation view of the active_call; define #execute
+ # as a new method for this instance that invokes #server_streamer
+ op = c.operation
+ op.define_singleton_method(:execute) do
+ c.server_streamer(req, &blk)
+ end
+ op
+ end
+
+ # bidi_streamer sends a stream of requests to the GRPC server, and yields
+ # a stream of responses.
+ #
+ # This method takes an Enumerable of requests, and returns and enumerable
+ # of responses.
+ #
+ # == requests ==
+ #
+ # requests provides an 'iterable' of Requests. I.e. it follows Ruby's #each
+ # enumeration protocol. In the simplest case, requests will be an array of
+ # marshallable objects; in typical case it will be an Enumerable that
+ # allows dynamic construction of the marshallable objects.
+ #
+ # == responses ==
+ #
+ # This is an enumerator of responses. I.e, its #next method blocks
+ # waiting for the next response. Also, if at any point the block needs
+ # to consume all the remaining responses, this can be done using #each or
+ # #collect. Calling #each or #collect should only be done if
+ # the_call#writes_done has been called, otherwise the block will loop
+ # forever.
+ #
+ # == Flow Control ==
+ # This is a blocking call.
+ #
+ # * the call completes when the next call to provided block returns
+ # * [False]
+ #
+ # * the execution block parameters are two objects for sending and
+ # receiving responses, each of which blocks waiting for flow control.
+ # E.g, calles to bidi_call#remote_send will wait until flow control
+ # allows another write before returning; and obviously calls to
+ # responses#next block until the next response is available.
+ #
+ # == Termination ==
+ #
+ # As well as sending and receiving messages, the block passed to the
+ # function is also responsible for:
+ #
+ # * calling bidi_call#writes_done to indicate no further reqs will be
+ # sent.
+ #
+ # * returning false if once the bidi stream is functionally completed.
+ #
+ # Note that response#next will indicate that there are no further
+ # responses by throwing StopIteration, but can only happen either
+ # if bidi_call#writes_done is called.
+ #
+ # To terminate the RPC correctly the block:
+ #
+ # * must call bidi#writes_done and then
+ #
+ # * either return false as soon as there is no need for other responses
+ #
+ # * loop on responses#next until no further responses are available
+ #
+ # == Errors ==
+ # An RuntimeError is raised if
+ #
+ # * the server responds with a non-OK status when any response is
+ # * retrieved
+ #
+ # * the deadline is exceeded
+ #
+ # == Return Value ==
+ #
+ # if the return_op is false, the return value is an Enumerator of the
+ # results, unless a block is provided, in which case the block is
+ # executed with each response.
+ #
+ # if return_op is true, the function returns an Operation whose #execute
+ # method runs the Bidi call. Again, Operation#execute either calls a
+ # given block with each response or returns an Enumerator of the responses.
+ #
+ # @param method [String] the RPC method to call on the GRPC server
+ # @param requests [Object] an Enumerable of requests to send
+ # @param marshal [Function] f(obj)->string that marshals requests
+ # @param unmarshal [Function] f(string)->obj that unmarshals responses
+ # @param deadline [Numeric] (optional) the max completion time in seconds
+ # @param blk [Block] when provided, is executed for each response
+ # @param return_op [true|false] (default false) return an Operation if true
+ # @return [Enumerator|nil|Operation] as discussed above
+ def bidi_streamer(method, requests, marshal, unmarshal, deadline=nil,
+ return_op:false, &blk)
+ c = new_active_call(method, marshal, unmarshal, deadline || @deadline)
+ return c.bidi_streamer(requests, &blk) unless return_op
+
+ # return the operation view of the active_call; define #execute
+ # as a new method for this instance that invokes #bidi_streamer
+ op = c.operation
+ op.define_singleton_method(:execute) do
+ c.bidi_streamer(requests, &blk)
+ end
+ op
+ end
+
+ private
+ # Creates a new active stub
+ #
+ # @param ch [GRPC::Channel] the channel used to create the stub.
+ # @param marshal [Function] f(obj)->string that marshals requests
+ # @param unmarshal [Function] f(string)->obj that unmarshals responses
+ # @param deadline [TimeConst]
+ def new_active_call(ch, marshal, unmarshal, deadline=nil)
+ absolute_deadline = TimeConsts.from_relative_time(deadline)
+ call = @ch.create_call(ch, @host, absolute_deadline)
+ ActiveCall.new(call, @queue, marshal, unmarshal, absolute_deadline,
+ started:false)
+ end
+
+ end
+
+end
diff --git a/src/ruby/lib/grpc/generic/rpc_desc.rb b/src/ruby/lib/grpc/generic/rpc_desc.rb
new file mode 100644
index 0000000..43b4d4f
--- /dev/null
+++ b/src/ruby/lib/grpc/generic/rpc_desc.rb
@@ -0,0 +1,157 @@
+# Copyright 2014, Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+# * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+require 'grpc'
+
+module GRPC
+
+ # RpcDesc is a Descriptor of an RPC method.
+ class RpcDesc < Struct.new(:name, :input, :output, :marshal_method,
+ :unmarshal_method)
+
+ # Used to wrap a message class to indicate that it needs to be streamed.
+ class Stream
+ attr_accessor :type
+
+ def initialize(type)
+ @type = type
+ end
+ end
+
+ # @return [Proc] { |instance| marshalled(instance) }
+ def marshal_proc
+ Proc.new { |o| o.method(marshal_method).call.to_s }
+ end
+
+ # @param [:input, :output] target determines whether to produce the an
+ # unmarshal Proc for the rpc input parameter or
+ # its output parameter
+ #
+ # @return [Proc] An unmarshal proc { |marshalled(instance)| instance }
+ def unmarshal_proc(target)
+ raise ArgumentError if not [:input, :output].include?(target)
+ unmarshal_class = method(target).call
+ if unmarshal_class.is_a?Stream
+ unmarshal_class = unmarshal_class.type
+ end
+ Proc.new { |o| unmarshal_class.method(unmarshal_method).call(o) }
+ end
+
+ def run_server_method(active_call, mth)
+ # While a server method is running, it might be cancelled, its deadline
+ # might be reached, the handler could throw an unknown error, or a
+ # well-behaved handler could throw a StatusError.
+ begin
+ if is_request_response?
+ req = active_call.remote_read
+ resp = mth.call(req, active_call.single_req_view)
+ active_call.remote_send(resp)
+ elsif is_client_streamer?
+ resp = mth.call(active_call.multi_req_view)
+ active_call.remote_send(resp)
+ elsif is_server_streamer?
+ req = active_call.remote_read
+ replys = mth.call(req, active_call.single_req_view)
+ replys.each { |r| active_call.remote_send(r) }
+ else # is a bidi_stream
+ active_call.run_server_bidi(mth)
+ end
+ send_status(active_call, StatusCodes::OK, 'OK')
+ active_call.finished
+ rescue BadStatus => e
+ # this is raised by handlers that want GRPC to send an application
+ # error code and detail message.
+ logger.debug("app error: #{active_call}, status:#{e.code}:#{e.details}")
+ send_status(active_call, e.code, e.details)
+ rescue CallError => e
+ # This is raised by GRPC internals but should rarely, if ever happen.
+ # Log it, but don't notify the other endpoint..
+ logger.warn("failed call: #{active_call}\n#{e}")
+ rescue OutOfTime
+ # This is raised when active_call#method.call exceeeds the deadline
+ # event. Send a status of deadline exceeded
+ logger.warn("late call: #{active_call}")
+ send_status(active_call, StatusCodes::DEADLINE_EXCEEDED, 'late')
+ rescue EventError => e
+ # This is raised by GRPC internals but should rarely, if ever happen.
+ # Log it, but don't notify the other endpoint..
+ logger.warn("failed call: #{active_call}\n#{e}")
+ rescue StandardError => e
+ # This will usuaally be an unhandled error in the handling code.
+ # Send back a UNKNOWN status to the client
+ logger.warn("failed handler: #{active_call}; sending status:UNKNOWN")
+ logger.warn(e)
+ send_status(active_call, StatusCodes::UNKNOWN, 'no reason given')
+ end
+ end
+
+ def assert_arity_matches(mth)
+ if (is_request_response? || is_server_streamer?)
+ if mth.arity != 2
+ raise arity_error(mth, 2, "should be #{mth.name}(req, call)")
+ end
+ else
+ if mth.arity != 1
+ raise arity_error(mth, 1, "should be #{mth.name}(call)")
+ end
+ end
+ end
+
+ def is_request_response?
+ !input.is_a?(Stream) && !output.is_a?(Stream)
+ end
+
+ def is_client_streamer?
+ input.is_a?(Stream) && !output.is_a?(Stream)
+ end
+
+ def is_server_streamer?
+ !input.is_a?(Stream) && output.is_a?(Stream)
+ end
+
+ def is_bidi_streamer?
+ input.is_a?(Stream) && output.is_a?(Stream)
+ end
+
+ def arity_error(mth, want, msg)
+ "##{mth.name}: bad arg count; got:#{mth.arity}, want:#{want}, #{msg}"
+ end
+
+ def send_status(active_client, code, details)
+ begin
+ active_client.send_status(code, details)
+ rescue StandardError => e
+ logger.warn('Could not send status %d:%s' % [code, details])
+ logger.warn(e)
+ end
+ end
+
+ end
+
+end
diff --git a/src/ruby/lib/grpc/generic/rpc_server.rb b/src/ruby/lib/grpc/generic/rpc_server.rb
new file mode 100644
index 0000000..e6efdc3
--- /dev/null
+++ b/src/ruby/lib/grpc/generic/rpc_server.rb
@@ -0,0 +1,408 @@
+# Copyright 2014, Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+# * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+require 'grpc'
+require 'grpc/generic/active_call'
+require 'grpc/generic/service'
+require 'thread'
+require 'xray/thread_dump_signal_handler'
+
+module GRPC
+
+ # RpcServer hosts a number of services and makes them available on the
+ # network.
+ class RpcServer
+ include CompletionType
+ extend ::Forwardable
+
+ def_delegators :@server, :add_http2_port
+
+ # Default thread pool size is 3
+ DEFAULT_POOL_SIZE = 3
+
+ # Default max_waiting_requests size is 20
+ DEFAULT_MAX_WAITING_REQUESTS = 20
+
+ # Creates a new RpcServer.
+ #
+ # The RPC server is configured using keyword arguments.
+ #
+ # There are some specific keyword args used to configure the RpcServer
+ # instance, however other arbitrary are allowed and when present are used
+ # to configure the listeninng connection set up by the RpcServer.
+ #
+ # * server_override: which if passed must be a [GRPC::Server]. When
+ # present.
+ #
+ # * poll_period: when present, the server polls for new events with this
+ # period
+ #
+ # * pool_size: the size of the thread pool the server uses to run its
+ # threads
+ #
+ # * completion_queue_override: when supplied, this will be used as the
+ # completion_queue that the server uses to receive network events,
+ # otherwise its creates a new instance itself
+ #
+ # * max_waiting_requests: the maximum number of requests that are not
+ # being handled to allow. When this limit is exceeded, the server responds
+ # with not available to new requests
+ def initialize(pool_size:DEFAULT_POOL_SIZE,
+ max_waiting_requests:DEFAULT_MAX_WAITING_REQUESTS,
+ poll_period:TimeConsts::INFINITE_FUTURE,
+ completion_queue_override:nil,
+ server_override:nil,
+ **kw)
+ if !completion_queue_override.nil?
+ cq = completion_queue_override
+ if !cq.is_a?(CompletionQueue)
+ raise ArgumentError.new('not a CompletionQueue')
+ end
+ else
+ cq = CompletionQueue.new
+ end
+ @cq = cq
+
+ if !server_override.nil?
+ srv = server_override
+ raise ArgumentError.new('not a Server') unless srv.is_a?(Server)
+ else
+ srv = Server.new(@cq, **kw)
+ end
+ @server = srv
+
+ @pool_size = pool_size
+ @max_waiting_requests = max_waiting_requests
+ @poll_period = poll_period
+ @run_mutex = Mutex.new
+ @run_cond = ConditionVariable.new
+ @pool = Pool.new(@pool_size)
+ end
+
+ # stops a running server
+ #
+ # the call has no impact if the server is already stopped, otherwise
+ # server's current call loop is it's last.
+ def stop
+ if @running
+ @stopped = true
+ @pool.stop
+ end
+ end
+
+ # determines if the server is currently running
+ def running?
+ @running ||= false
+ end
+
+ # Is called from other threads to wait for #run to start up the server.
+ #
+ # If run has not been called, this returns immediately.
+ #
+ # @param timeout [Numeric] number of seconds to wait
+ # @result [true, false] true if the server is running, false otherwise
+ def wait_till_running(timeout=0.1)
+ end_time, sleep_period = Time.now + timeout, (1.0 * timeout)/100
+ while Time.now < end_time
+ if !running?
+ @run_mutex.synchronize { @run_cond.wait(@run_mutex) }
+ end
+ sleep(sleep_period)
+ end
+ return running?
+ end
+
+ # determines if the server is currently stopped
+ def stopped?
+ @stopped ||= false
+ end
+
+ # handle registration of classes
+ #
+ # service is either a class that includes GRPC::GenericService and whose
+ # #new function can be called without argument or any instance of such a
+ # class.
+ #
+ # E.g, after
+ #
+ # class Divider
+ # include GRPC::GenericService
+ # rpc :div DivArgs, DivReply # single request, single response
+ # def initialize(optional_arg='default option') # no args
+ # ...
+ # end
+ #
+ # srv = GRPC::RpcServer.new(...)
+ #
+ # # Either of these works
+ #
+ # srv.handle(Divider)
+ #
+ # # or
+ #
+ # srv.handle(Divider.new('replace optional arg'))
+ #
+ # It raises RuntimeError:
+ # - if service is not valid service class or object
+ # - if it is a valid service, but the handler methods are already registered
+ # - if the server is already running
+ #
+ # @param service [Object|Class] a service class or object as described
+ # above
+ def handle(service)
+ raise 'cannot add services if the server is running' if running?
+ raise 'cannot add services if the server is stopped' if stopped?
+ cls = service.is_a?(Class) ? service : service.class
+ assert_valid_service_class(cls)
+ add_rpc_descs_for(service)
+ end
+
+ # runs the server
+ #
+ # - if no rpc_descs are registered, this exits immediately, otherwise it
+ # continues running permanently and does not return until program exit.
+ #
+ # - #running? returns true after this is called, until #stop cause the
+ # the server to stop.
+ def run
+ if rpc_descs.size == 0
+ logger.warn('did not run as no services were present')
+ return
+ end
+ @run_mutex.synchronize do
+ @running = true
+ @run_cond.signal
+ end
+ @pool.start
+ @server.start
+ server_tag = Object.new
+ while !stopped?
+ @server.request_call(server_tag)
+ ev = @cq.pluck(server_tag, @poll_period)
+ next if ev.nil?
+ if ev.type != SERVER_RPC_NEW
+ logger.warn("bad evt: got:#{ev.type}, want:#{SERVER_RPC_NEW}")
+ next
+ end
+ c = new_active_server_call(ev.call, ev.result)
+ if !c.nil?
+ mth = ev.result.method.to_sym
+
+ # NOTE(temiola): This is necessary to allow the C call struct wrapped
+ # within the active_call created by the event to be GCed; this is
+ # necessary so that other C-level destructors get called in the
+ # required order.
+ ev = nil
+
+ @pool.schedule(c) do |call|
+ rpc_descs[mth].run_server_method(call, rpc_handlers[mth])
+ end
+ end
+ end
+ @running = false
+ end
+
+ def new_active_server_call(call, new_server_rpc)
+ # TODO(temiola): perhaps reuse the main server completion queue here, but
+ # for now, create a new completion queue per call, pending best practice
+ # usage advice from the c core.
+
+ # Accept the call. This is necessary even if a status is to be sent back
+ # immediately
+ finished_tag = Object.new
+ call_queue = CompletionQueue.new
+ call.accept(call_queue, finished_tag)
+
+ # Send UNAVAILABLE if there are too many unprocessed jobs
+ jobs_count, max = @pool.jobs_waiting, @max_waiting_requests
+ logger.info("waiting: #{jobs_count}, max: #{max}")
+ if @pool.jobs_waiting > @max_waiting_requests
+ logger.warn("NOT AVAILABLE: too many jobs_waiting: #{new_server_rpc}")
+ noop = Proc.new { |x| x }
+ c = ActiveCall.new(call, call_queue, noop, noop,
+ new_server_rpc.deadline, finished_tag: finished_tag)
+ c.send_status(StatusCodes::UNAVAILABLE, '')
+ return nil
+ end
+
+ # Send NOT_FOUND if the method does not exist
+ mth = new_server_rpc.method.to_sym
+ if !rpc_descs.has_key?(mth)
+ logger.warn("NOT_FOUND: #{new_server_rpc}")
+ noop = Proc.new { |x| x }
+ c = ActiveCall.new(call, call_queue, noop, noop,
+ new_server_rpc.deadline, finished_tag: finished_tag)
+ c.send_status(StatusCodes::NOT_FOUND, '')
+ return nil
+ end
+
+ # Create the ActiveCall
+ rpc_desc = rpc_descs[mth]
+ logger.info("deadline is #{new_server_rpc.deadline}; (now=#{Time.now})")
+ ActiveCall.new(call, call_queue,
+ rpc_desc.marshal_proc, rpc_desc.unmarshal_proc(:input),
+ new_server_rpc.deadline, finished_tag: finished_tag)
+ end
+
+ # Pool is a simple thread pool for running server requests.
+ class Pool
+
+ def initialize(size)
+ raise 'pool size must be positive' unless size > 0
+ @jobs = Queue.new
+ @size = size
+ @stopped = false
+ @stop_mutex = Mutex.new
+ @stop_cond = ConditionVariable.new
+ @workers = []
+ end
+
+ # Returns the number of jobs waiting
+ def jobs_waiting
+ @jobs.size
+ end
+
+ # Runs the given block on the queue with the provided args.
+ #
+ # @param args the args passed blk when it is called
+ # @param blk the block to call
+ def schedule(*args, &blk)
+ raise 'already stopped' if @stopped
+ return if blk.nil?
+ logger.info('schedule another job')
+ @jobs << [blk, args]
+ end
+
+ # Starts running the jobs in the thread pool.
+ def start
+ raise 'already stopped' if @stopped
+ until @workers.size == @size.to_i
+ next_thread = Thread.new do
+ catch(:exit) do # allows { throw :exit } to kill a thread
+ loop do
+ begin
+ blk, args = @jobs.pop
+ blk.call(*args)
+ rescue StandardError => e
+ logger.warn('Error in worker thread')
+ logger.warn(e)
+ end
+ end
+ end
+
+ # removes the threads from workers, and signal when all the threads
+ # are complete.
+ @stop_mutex.synchronize do
+ @workers.delete(Thread.current)
+ if @workers.size == 0
+ @stop_cond.signal
+ end
+ end
+ end
+ @workers << next_thread
+ end
+ end
+
+ # Stops the jobs in the pool
+ def stop
+ logger.info('stopping, will wait for all the workers to exit')
+ @workers.size.times { schedule { throw :exit } }
+ @stopped = true
+
+ # TODO(temiola): allow configuration of the keepalive period
+ keep_alive = 5
+ @stop_mutex.synchronize do
+ if @workers.size > 0
+ @stop_cond.wait(@stop_mutex, keep_alive)
+ end
+ end
+
+ # Forcibly shutdown any threads that are still alive.
+ if @workers.size > 0
+ logger.warn("forcibly terminating #{@workers.size} worker(s)")
+ @workers.each do |t|
+ next unless t.alive?
+ begin
+ t.exit
+ rescue StandardError => e
+ logger.warn('error while terminating a worker')
+ logger.warn(e)
+ end
+ end
+ end
+
+ logger.info('stopped, all workers are shutdown')
+ end
+
+ end
+
+ protected
+
+ def rpc_descs
+ @rpc_descs ||= {}
+ end
+
+ def rpc_handlers
+ @rpc_handlers ||= {}
+ end
+
+ private
+
+ def assert_valid_service_class(cls)
+ if !cls.include?(GenericService)
+ raise "#{cls} should 'include GenericService'"
+ end
+ if cls.rpc_descs.size == 0
+ raise "#{cls} should specify some rpc descriptions"
+ end
+ cls.assert_rpc_descs_have_methods
+ end
+
+ def add_rpc_descs_for(service)
+ cls = service.is_a?(Class) ? service : service.class
+ specs = rpc_descs
+ handlers = rpc_handlers
+ cls.rpc_descs.each_pair do |name,spec|
+ route = "/#{cls.service_name}/#{name}".to_sym
+ if specs.has_key?(route)
+ raise "Cannot add rpc #{route} from #{spec}, already registered"
+ else
+ specs[route] = spec
+ if service.is_a?(Class)
+ handlers[route] = cls.new.method(name.to_s.underscore.to_sym)
+ else
+ handlers[route] = service.method(name.to_s.underscore.to_sym)
+ end
+ logger.info("handling #{route} with #{handlers[route]}")
+ end
+ end
+ end
+ end
+
+end
diff --git a/src/ruby/lib/grpc/generic/service.rb b/src/ruby/lib/grpc/generic/service.rb
new file mode 100644
index 0000000..1a3d0dc
--- /dev/null
+++ b/src/ruby/lib/grpc/generic/service.rb
@@ -0,0 +1,247 @@
+# Copyright 2014, Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+# * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+require 'grpc'
+require 'grpc/generic/client_stub'
+require 'grpc/generic/rpc_desc'
+
+# Extend String to add a method underscore
+class String
+
+ # creates a new string that is the underscore separate version of this one.
+ #
+ # E.g,
+ # PrintHTML -> print_html
+ # AMethod -> a_method
+ # AnRpc -> an_rpc
+ def underscore
+ word = self.dup
+ word.gsub!(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+ word.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+ word.tr!('-', '_')
+ word.downcase!
+ word
+ end
+
+end
+
+module GRPC
+
+ # Provides behaviour used to implement schema-derived service classes.
+ #
+ # Is intended to be used to support both client and server IDL-schema-derived
+ # servers.
+ module GenericService
+
+ # Used to indicate that a name has already been specified
+ class DuplicateRpcName < StandardError
+ def initialize(name)
+ super("rpc (#{name}) is already defined")
+ end
+ end
+
+ # Provides a simple DSL to describe RPC services.
+ #
+ # E.g, a Maths service that uses the serializable messages DivArgs,
+ # DivReply and Num might define its endpoint uses the following way:
+ #
+ # rpc :div DivArgs, DivReply # single request, single response
+ # rpc :sum stream(Num), Num # streamed input, single response
+ # rpc :fib FibArgs, stream(Num) # single request, streamed response
+ # rpc :div_many stream(DivArgs), stream(DivReply)
+ # # streamed req and resp
+ #
+ # Each 'rpc' adds an RpcDesc to classes including this module, and
+ # #assert_rpc_descs_have_methods is used to ensure the including class
+ # provides methods with signatures that support all the descriptors.
+ module Dsl
+
+ # This configures the method names that the serializable message
+ # implementation uses to marshal and unmarshal messages.
+ #
+ # - unmarshal_class method must be a class method on the serializable
+ # message type that takes a string (byte stream) and produces and object
+ #
+ # - marshal_instance_method is called on a serializable message instance
+ # and produces a serialized string.
+ #
+ # The Dsl verifies that the types in the descriptor have both the
+ # unmarshal and marshal methods.
+ attr_writer(:marshal_instance_method, :unmarshal_class_method)
+ attr_accessor(:service_name)
+
+ # Adds an RPC spec.
+ #
+ # Takes the RPC name and the classes representing the types to be
+ # serialized, and adds them to the including classes rpc_desc hash.
+ #
+ # input and output should both have the methods #marshal and #unmarshal
+ # that are responsible for writing and reading an object instance from a
+ # byte buffer respectively.
+ #
+ # @param name [String] the name of the rpc
+ # @param input [Object] the input parameter's class
+ # @param output [Object] the output parameter's class
+ def rpc(name, input, output)
+ raise DuplicateRpcName, name if rpc_descs.has_key?(name)
+ assert_can_marshal(input)
+ assert_can_marshal(output)
+ rpc_descs[name] = RpcDesc.new(name, input, output,
+ marshal_instance_method,
+ unmarshal_class_method)
+ end
+
+ def inherited(subclass)
+ # Each subclass should have distinct class variable with its own
+ # rpc_descs.
+ subclass.rpc_descs.merge!(rpc_descs)
+ subclass.service_name = service_name
+ end
+
+ # the name of the instance method used to marshal events to a byte stream.
+ def marshal_instance_method
+ @marshal_instance_method ||= :marshal
+ end
+
+ # the name of the class method used to unmarshal from a byte stream.
+ def unmarshal_class_method
+ @unmarshal_class_method ||= :unmarshal
+ end
+
+ def assert_can_marshal(cls)
+ if cls.is_a?RpcDesc::Stream
+ cls = cls.type
+ end
+
+ mth = unmarshal_class_method
+ if !cls.methods.include?(mth)
+ raise ArgumentError, "#{cls} needs #{cls}.#{mth}"
+ end
+
+ mth = marshal_instance_method
+ if !cls.instance_methods.include?(mth)
+ raise ArgumentError, "#{cls} needs #{cls}.new.#{mth}"
+ end
+ end
+
+ # @param cls [Class] the class of a serializable type
+ # @return cls wrapped in a RpcDesc::Stream
+ def stream(cls)
+ assert_can_marshal(cls)
+ RpcDesc::Stream.new(cls)
+ end
+
+ # the RpcDescs defined for this GenericService, keyed by name.
+ def rpc_descs
+ @rpc_descs ||= {}
+ end
+
+ # Creates a rpc client class with methods for accessing the methods
+ # currently in rpc_descs.
+ def rpc_stub_class
+ descs = rpc_descs
+ route_prefix = service_name
+ Class.new(ClientStub) do
+
+ # @param host [String] the host the stub connects to
+ # @param kw [KeywordArgs] the channel arguments, plus any optional
+ # args for configuring the client's channel
+ def initialize(host, **kw)
+ super(host, CompletionQueue.new, **kw)
+ end
+
+ # Used define_method to add a method for each rpc_desc. Each method
+ # calls the base class method for the given descriptor.
+ descs.each_pair do |name,desc|
+ mth_name = name.to_s.underscore.to_sym
+ marshal = desc.marshal_proc
+ unmarshal = desc.unmarshal_proc(:output)
+ route = "/#{route_prefix}/#{name}"
+ if desc.is_request_response?
+ define_method(mth_name) do |req,deadline=nil|
+ logger.debug("calling #{@host}:#{route}")
+ request_response(route, req, marshal, unmarshal, deadline)
+ end
+ elsif desc.is_client_streamer?
+ define_method(mth_name) do |reqs,deadline=nil|
+ logger.debug("calling #{@host}:#{route}")
+ client_streamer(route, reqs, marshal, unmarshal, deadline)
+ end
+ elsif desc.is_server_streamer?
+ define_method(mth_name) do |req,deadline=nil,&blk|
+ logger.debug("calling #{@host}:#{route}")
+ server_streamer(route, req, marshal, unmarshal, deadline, &blk)
+ end
+ else # is a bidi_stream
+ define_method(mth_name) do |reqs, deadline=nil,&blk|
+ logger.debug("calling #{@host}:#{route}")
+ bidi_streamer(route, reqs, marshal, unmarshal, deadline, &blk)
+ end
+ end
+ end
+
+ end
+
+ end
+
+ # Asserts that the appropriate methods are defined for each added rpc
+ # spec. Is intended to aid verifying that server classes are correctly
+ # implemented.
+ def assert_rpc_descs_have_methods
+ rpc_descs.each_pair do |m,spec|
+ mth_name = m.to_s.underscore.to_sym
+ if !self.instance_methods.include?(mth_name)
+ raise "#{self} does not provide instance method '#{mth_name}'"
+ end
+ spec.assert_arity_matches(self.instance_method(mth_name))
+ end
+ end
+
+ end
+
+ def self.included(o)
+ o.extend(Dsl)
+
+ # Update to the use the name including module. This can be nil e,g. when
+ # modules are declared dynamically.
+ if o.name.nil?
+ o.service_name = 'GenericService'
+ else
+ modules = o.name.split('::')
+ if modules.length > 2
+ o.service_name = modules[modules.length - 2]
+ else
+ o.service_name = modules.first
+ end
+ end
+ end
+
+ end
+
+end
diff --git a/src/ruby/lib/grpc/logconfig.rb b/src/ruby/lib/grpc/logconfig.rb
new file mode 100644
index 0000000..6d8e189
--- /dev/null
+++ b/src/ruby/lib/grpc/logconfig.rb
@@ -0,0 +1,40 @@
+# Copyright 2014, Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+# * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+require 'logging'
+
+include Logging.globally # logger is accessible everywhere
+
+Logging.logger.root.appenders = Logging.appenders.stdout
+Logging.logger.root.level = :info
+
+# TODO(temiola): provide command-line configuration for logging
+Logging.logger['Google::RPC'].level = :debug
+Logging.logger['Google::RPC::ActiveCall'].level = :info
+Logging.logger['Google::RPC::BidiCall'].level = :info
diff --git a/src/ruby/lib/grpc/time_consts.rb b/src/ruby/lib/grpc/time_consts.rb
new file mode 100644
index 0000000..2cbab5d
--- /dev/null
+++ b/src/ruby/lib/grpc/time_consts.rb
@@ -0,0 +1,69 @@
+# Copyright 2014, Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+# * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+require 'grpc'
+
+module Google
+ module RPC
+ module TimeConsts # re-opens a module in the C extension.
+
+ # Converts a time delta to an absolute deadline.
+ #
+ # Assumes timeish is a relative time, and converts its to an absolute,
+ # with following exceptions:
+ #
+ # * if timish is one of the TimeConsts.TimeSpec constants the value is
+ # preserved.
+ # * timish < 0 => TimeConsts.INFINITE_FUTURE
+ # * timish == 0 => TimeConsts.ZERO
+ #
+ # @param timeish [Number|TimeSpec]
+ # @return timeish [Number|TimeSpec]
+ def from_relative_time(timeish)
+ if timeish.is_a?TimeSpec
+ timeish
+ elsif timeish.nil?
+ TimeConsts::ZERO
+ elsif !timeish.is_a?Numeric
+ raise TypeError('Cannot make an absolute deadline from %s',
+ timeish.inspect)
+ elsif timeish < 0
+ TimeConsts::INFINITE_FUTURE
+ elsif timeish == 0
+ TimeConsts::ZERO
+ else !timeish.nil?
+ Time.now + timeish
+ end
+ end
+
+ module_function :from_relative_time
+
+ end
+ end
+end
diff --git a/src/ruby/lib/grpc/version.rb b/src/ruby/lib/grpc/version.rb
new file mode 100644
index 0000000..0a84f4c
--- /dev/null
+++ b/src/ruby/lib/grpc/version.rb
@@ -0,0 +1,34 @@
+# Copyright 2014, Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+# * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+module Google
+ module RPC
+ VERSION = '0.0.1'
+ end
+end