grpc 1.30.2

data/src/ruby/lib/grpc/generic/interceptor_registry.rb

@@ -0,0 +1,53 @@
+# Copyright 2017 gRPC authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# GRPC contains the General RPC module.
+module GRPC
+  ##
+  # Represents a registry of added interceptors available for enumeration.
+  # The registry can be used for both server and client interceptors.
+  # This class is internal to gRPC and not meant for public usage.
+  #
+  class InterceptorRegistry
+    ##
+    # An error raised when an interceptor is attempted to be added
+    # that does not extend GRPC::Interceptor
+    #
+    class DescendantError < StandardError; end
+
+    ##
+    # Initialize the registry with an empty interceptor list
+    # This is an EXPERIMENTAL API.
+    #
+    def initialize(interceptors = [])
+      @interceptors = []
+      interceptors.each do |i|
+        base = GRPC::Interceptor
+        unless i.class.ancestors.include?(base)
+          fail DescendantError, "Interceptors must descend from #{base}"
+        end
+        @interceptors << i
+      end
+    end
+
+    ##
+    # Builds an interception context from this registry
+    #
+    # @return [InterceptionContext]
+    #
+    def build_context
+      InterceptionContext.new(@interceptors)
+    end
+  end
+end

data/src/ruby/lib/grpc/generic/interceptors.rb

@@ -0,0 +1,186 @@
+# Copyright 2017 gRPC authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+require_relative 'interceptor_registry'
+
+# GRPC contains the General RPC module.
+module GRPC
+  ##
+  # Base class for interception in GRPC
+  #
+  class Interceptor
+    ##
+    # @param [Hash] options A hash of options that will be used
+    #   by the interceptor. This is an EXPERIMENTAL API.
+    #
+    def initialize(options = {})
+      @options = options || {}
+    end
+  end
+
+  ##
+  # ClientInterceptor allows for wrapping outbound gRPC client stub requests.
+  # This is an EXPERIMENTAL API.
+  #
+  class ClientInterceptor < Interceptor
+    ##
+    # Intercept a unary request response call
+    #
+    # @param [Object] request
+    # @param [GRPC::ActiveCall] call
+    # @param [String] method
+    # @param [Hash] metadata
+    #
+    def request_response(request: nil, call: nil, method: nil, metadata: nil)
+      GRPC.logger.debug "Intercepting request response method #{method}" \
+        " for request #{request} with call #{call} and metadata: #{metadata}"
+      yield
+    end
+
+    ##
+    # Intercept a client streaming call
+    #
+    # @param [Enumerable] requests
+    # @param [GRPC::ActiveCall] call
+    # @param [String] method
+    # @param [Hash] metadata
+    #
+    def client_streamer(requests: nil, call: nil, method: nil, metadata: nil)
+      GRPC.logger.debug "Intercepting client streamer method #{method}" \
+       " for requests #{requests} with call #{call} and metadata: #{metadata}"
+      yield
+    end
+
+    ##
+    # Intercept a server streaming call
+    #
+    # @param [Object] request
+    # @param [GRPC::ActiveCall] call
+    # @param [String] method
+    # @param [Hash] metadata
+    #
+    def server_streamer(request: nil, call: nil, method: nil, metadata: nil)
+      GRPC.logger.debug "Intercepting server streamer method #{method}" \
+        " for request #{request} with call #{call} and metadata: #{metadata}"
+      yield
+    end
+
+    ##
+    # Intercept a BiDi streaming call
+    #
+    # @param [Enumerable] requests
+    # @param [GRPC::ActiveCall] call
+    # @param [String] method
+    # @param [Hash] metadata
+    #
+    def bidi_streamer(requests: nil, call: nil, method: nil, metadata: nil)
+      GRPC.logger.debug "Intercepting bidi streamer method #{method}" \
+        " for requests #{requests} with call #{call} and metadata: #{metadata}"
+      yield
+    end
+  end
+
+  ##
+  # ServerInterceptor allows for wrapping gRPC server execution handling.
+  # This is an EXPERIMENTAL API.
+  #
+  class ServerInterceptor < Interceptor
+    ##
+    # Intercept a unary request response call.
+    #
+    # @param [Object] request
+    # @param [GRPC::ActiveCall::SingleReqView] call
+    # @param [Method] method
+    #
+    def request_response(request: nil, call: nil, method: nil)
+      GRPC.logger.debug "Intercepting request response method #{method}" \
+        " for request #{request} with call #{call}"
+      yield
+    end
+
+    ##
+    # Intercept a client streaming call
+    #
+    # @param [GRPC::ActiveCall::MultiReqView] call
+    # @param [Method] method
+    #
+    def client_streamer(call: nil, method: nil)
+      GRPC.logger.debug "Intercepting client streamer method #{method}" \
+        " with call #{call}"
+      yield
+    end
+
+    ##
+    # Intercept a server streaming call
+    #
+    # @param [Object] request
+    # @param [GRPC::ActiveCall::SingleReqView] call
+    # @param [Method] method
+    #
+    def server_streamer(request: nil, call: nil, method: nil)
+      GRPC.logger.debug "Intercepting server streamer method #{method}" \
+        " for request #{request} with call #{call}"
+      yield
+    end
+
+    ##
+    # Intercept a BiDi streaming call
+    #
+    # @param [Enumerable<Object>] requests
+    # @param [GRPC::ActiveCall::MultiReqView] call
+    # @param [Method] method
+    #
+    def bidi_streamer(requests: nil, call: nil, method: nil)
+      GRPC.logger.debug "Intercepting bidi streamer method #{method}" \
+        " for requests #{requests} with call #{call}"
+      yield
+    end
+  end
+
+  ##
+  # Represents the context in which an interceptor runs. Used to provide an
+  # injectable mechanism for handling interception. This is an EXPERIMENTAL API.
+  #
+  class InterceptionContext
+    ##
+    # @param interceptors [Array<GRPC::Interceptor>]
+    #
+    def initialize(interceptors = [])
+      @interceptors = interceptors.dup
+    end
+
+    ##
+    # Intercept the call and fire out to interceptors in a FIFO execution.
+    # This is an EXPERIMENTAL API.
+    #
+    # @param [Symbol] type The request type
+    # @param [Hash] args The arguments for the call
+    #
+    def intercept!(type, args = {})
+      return yield if @interceptors.none?
+
+      i = @interceptors.pop
+      return yield unless i
+
+      i.send(type, args) do
+        if @interceptors.any?
+          intercept!(type, args) do
+            yield
+          end
+        else
+          yield
+        end
+      end
+    end
+  end
+end

data/src/ruby/lib/grpc/generic/rpc_desc.rb

@@ -0,0 +1,204 @@
+# Copyright 2015 gRPC authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require_relative '../grpc'
+
+# GRPC contains the General RPC module.
+module GRPC
+  # RpcDesc is a Descriptor of an RPC method.
+  class RpcDesc < Struct.new(:name, :input, :output, :marshal_method,
+                             :unmarshal_method)
+    include Core::StatusCodes
+
+    # 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 { |o| o.class.send(marshal_method, o).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)
+      fail ArgumentError unless [:input, :output].include?(target)
+      unmarshal_class = send(target)
+      unmarshal_class = unmarshal_class.type if unmarshal_class.is_a? Stream
+      proc { |o| unmarshal_class.send(unmarshal_method, o) }
+    end
+
+    def handle_request_response(active_call, mth, inter_ctx)
+      req = active_call.read_unary_request
+      call = active_call.single_req_view
+
+      inter_ctx.intercept!(
+        :request_response,
+        method: mth,
+        call: call,
+        request: req
+      ) do
+        resp = mth.call(req, call)
+        active_call.server_unary_response(
+          resp,
+          trailing_metadata: active_call.output_metadata
+        )
+      end
+    end
+
+    def handle_client_streamer(active_call, mth, inter_ctx)
+      call = active_call.multi_req_view
+
+      inter_ctx.intercept!(
+        :client_streamer,
+        method: mth,
+        call: call
+      ) do
+        resp = mth.call(call)
+        active_call.server_unary_response(
+          resp,
+          trailing_metadata: active_call.output_metadata
+        )
+      end
+    end
+
+    def handle_server_streamer(active_call, mth, inter_ctx)
+      req = active_call.read_unary_request
+      call = active_call.single_req_view
+
+      inter_ctx.intercept!(
+        :server_streamer,
+        method: mth,
+        call: call,
+        request: req
+      ) do
+        replies = mth.call(req, call)
+        replies.each { |r| active_call.remote_send(r) }
+        send_status(active_call, OK, 'OK', active_call.output_metadata)
+      end
+    end
+
+    ##
+    # @param [GRPC::ActiveCall] active_call
+    # @param [Method] mth
+    # @param [Array<GRPC::InterceptionContext>] inter_ctx
+    #
+    def handle_bidi_streamer(active_call, mth, inter_ctx)
+      active_call.run_server_bidi(mth, inter_ctx)
+      send_status(active_call, OK, 'OK', active_call.output_metadata)
+    end
+
+    ##
+    # @param [GRPC::ActiveCall] active_call The current active call object
+    #   for the request
+    # @param [Method] mth The current RPC method being called
+    # @param [GRPC::InterceptionContext] inter_ctx The interception context
+    #   being executed
+    #
+    def run_server_method(active_call, mth, inter_ctx = InterceptionContext.new)
+      # 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.
+      if request_response?
+        handle_request_response(active_call, mth, inter_ctx)
+      elsif client_streamer?
+        handle_client_streamer(active_call, mth, inter_ctx)
+      elsif server_streamer?
+        handle_server_streamer(active_call, mth, inter_ctx)
+      else  # is a bidi_stream
+        handle_bidi_streamer(active_call, mth, inter_ctx)
+      end
+    rescue BadStatus => e
+      # this is raised by handlers that want GRPC to send an application error
+      # code and detail message and some additional app-specific metadata.
+      GRPC.logger.debug("app err:#{active_call}, status:#{e.code}:#{e.details}")
+      send_status(active_call, e.code, e.details, e.metadata)
+    rescue Core::CallError => e
+      # This is raised by GRPC internals but should rarely, if ever happen.
+      # Log it, but don't notify the other endpoint..
+      GRPC.logger.warn("failed call: #{active_call}\n#{e}")
+    rescue Core::OutOfTime
+      # This is raised when active_call#method.call exceeds the deadline
+      # event.  Send a status of deadline exceeded
+      GRPC.logger.warn("late call: #{active_call}")
+      send_status(active_call, DEADLINE_EXCEEDED, 'late')
+    rescue StandardError, NotImplementedError => e
+      # This will usuaally be an unhandled error in the handling code.
+      # Send back a UNKNOWN status to the client
+      #
+      # Note: this intentionally does not map NotImplementedError to
+      # UNIMPLEMENTED because NotImplementedError is intended for low-level
+      # OS interaction (e.g. syscalls) not supported by the current OS.
+      GRPC.logger.warn("failed handler: #{active_call}; sending status:UNKNOWN")
+      GRPC.logger.warn(e)
+      send_status(active_call, UNKNOWN, "#{e.class}: #{e.message}")
+    end
+
+    def assert_arity_matches(mth)
+      # A bidi handler function can optionally be passed a second
+      # call object parameter for access to metadata, cancelling, etc.
+      if bidi_streamer?
+        if mth.arity != 2 && mth.arity != 1
+          fail arity_error(mth, 2, "should be #{mth.name}(req, call) or " \
+            "#{mth.name}(req)")
+        end
+      elsif request_response? || server_streamer?
+        if mth.arity != 2
+          fail arity_error(mth, 2, "should be #{mth.name}(req, call)")
+        end
+      else
+        if mth.arity != 1
+          fail arity_error(mth, 1, "should be #{mth.name}(call)")
+        end
+      end
+    end
+
+    def request_response?
+      !input.is_a?(Stream) && !output.is_a?(Stream)
+    end
+
+    def client_streamer?
+      input.is_a?(Stream) && !output.is_a?(Stream)
+    end
+
+    def server_streamer?
+      !input.is_a?(Stream) && output.is_a?(Stream)
+    end
+
+    def 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, metadata = {})
+      details = 'Not sure why' if details.nil?
+      GRPC.logger.debug("Sending status  #{code}:#{details}")
+      active_client.send_status(code, details, code == OK, metadata: metadata)
+    rescue StandardError => e
+      GRPC.logger.warn("Could not send status #{code}:#{details}")
+      GRPC.logger.warn(e)
+    end
+  end
+end

data/src/ruby/lib/grpc/generic/rpc_server.rb

@@ -0,0 +1,551 @@
+# Copyright 2015 gRPC authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require_relative '../grpc'
+require_relative 'active_call'
+require_relative 'service'
+require 'thread'
+
+# GRPC contains the General RPC module.
+module GRPC
+  # Pool is a simple thread pool.
+  class Pool
+    # Default keep alive period is 1s
+    DEFAULT_KEEP_ALIVE = 1
+
+    def initialize(size, keep_alive: DEFAULT_KEEP_ALIVE)
+      fail 'pool size must be positive' unless size > 0
+      @jobs = Queue.new
+      @size = size
+      @stopped = false
+      @stop_mutex = Mutex.new # needs to be held when accessing @stopped
+      @stop_cond = ConditionVariable.new
+      @workers = []
+      @keep_alive = keep_alive
+
+      # Each worker thread has its own queue to push and pull jobs
+      # these queues are put into @ready_queues when that worker is idle
+      @ready_workers = Queue.new
+    end
+
+    # Returns the number of jobs waiting
+    def jobs_waiting
+      @jobs.size
+    end
+
+    def ready_for_work?
+      # Busy worker threads are either doing work, or have a single job
+      # waiting on them. Workers that are idle with no jobs waiting
+      # have their "queues" in @ready_workers
+      !@ready_workers.empty?
+    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)
+      return if blk.nil?
+      @stop_mutex.synchronize do
+        if @stopped
+          GRPC.logger.warn('did not schedule job, already stopped')
+          return
+        end
+        GRPC.logger.info('schedule another job')
+        fail 'No worker threads available' if @ready_workers.empty?
+        worker_queue = @ready_workers.pop
+
+        fail 'worker already has a task waiting' unless worker_queue.empty?
+        worker_queue << [blk, args]
+      end
+    end
+
+    # Starts running the jobs in the thread pool.
+    def start
+      @stop_mutex.synchronize do
+        fail 'already stopped' if @stopped
+      end
+      until @workers.size == @size.to_i
+        new_worker_queue = Queue.new
+        @ready_workers << new_worker_queue
+        next_thread = Thread.new(new_worker_queue) do |jobs|
+          catch(:exit) do  # allows { throw :exit } to kill a thread
+            loop_execute_jobs(jobs)
+          end
+          remove_current_thread
+        end
+        @workers << next_thread
+      end
+    end
+
+    # Stops the jobs in the pool
+    def stop
+      GRPC.logger.info('stopping, will wait for all the workers to exit')
+      @stop_mutex.synchronize do  # wait @keep_alive seconds for workers to stop
+        @stopped = true
+        loop do
+          break unless ready_for_work?
+          worker_queue = @ready_workers.pop
+          worker_queue << [proc { throw :exit }, []]
+        end
+        @stop_cond.wait(@stop_mutex, @keep_alive) if @workers.size > 0
+      end
+      forcibly_stop_workers
+      GRPC.logger.info('stopped, all workers are shutdown')
+    end
+
+    protected
+
+    # Forcibly shutdown any threads that are still alive.
+    def forcibly_stop_workers
+      return unless @workers.size > 0
+      GRPC.logger.info("forcibly terminating #{@workers.size} worker(s)")
+      @workers.each do |t|
+        next unless t.alive?
+        begin
+          t.exit
+        rescue StandardError => e
+          GRPC.logger.warn('error while terminating a worker')
+          GRPC.logger.warn(e)
+        end
+      end
+    end
+
+    # removes the threads from workers, and signal when all the
+    # threads are complete.
+    def remove_current_thread
+      @stop_mutex.synchronize do
+        @workers.delete(Thread.current)
+        @stop_cond.signal if @workers.size.zero?
+      end
+    end
+
+    def loop_execute_jobs(worker_queue)
+      loop do
+        begin
+          blk, args = worker_queue.pop
+          blk.call(*args)
+        rescue StandardError, GRPC::Core::CallError => e
+          GRPC.logger.warn('Error in worker thread')
+          GRPC.logger.warn(e)
+        end
+        # there shouldn't be any work given to this thread while its busy
+        fail('received a task while busy') unless worker_queue.empty?
+        @stop_mutex.synchronize do
+          return if @stopped
+          @ready_workers << worker_queue
+        end
+      end
+    end
+  end
+
+  # RpcServer hosts a number of services and makes them available on the
+  # network.
+  class RpcServer
+    include Core::CallOps
+    include Core::TimeConsts
+    extend ::Forwardable
+
+    def_delegators :@server, :add_http2_port
+
+    # Default thread pool size is 30
+    DEFAULT_POOL_SIZE = 30
+
+    # Deprecated due to internal changes to the thread pool
+    DEFAULT_MAX_WAITING_REQUESTS = 20
+
+    # Default poll period is 1s
+    DEFAULT_POLL_PERIOD = 1
+
+    # Signal check period is 0.25s
+    SIGNAL_CHECK_PERIOD = 0.25
+
+    # setup_connect_md_proc is used by #initialize to validate the
+    # connect_md_proc.
+    def self.setup_connect_md_proc(a_proc)
+      return nil if a_proc.nil?
+      fail(TypeError, '!Proc') unless a_proc.is_a? Proc
+      a_proc
+    end
+
+    # Creates a new RpcServer.
+    #
+    # The RPC server is configured using keyword arguments.
+    #
+    # There are some specific keyword args used to configure the RpcServer
+    # instance.
+    #
+    # * pool_size: the size of the thread pool the server uses to run its
+    # threads. No more concurrent requests can be made than the size
+    # of the thread pool
+    #
+    # * max_waiting_requests: Deprecated due to internal changes to the thread
+    # pool. This is still an argument for compatibility but is ignored.
+    #
+    # * poll_period: The amount of time in seconds to wait for
+    # currently-serviced RPC's to finish before cancelling them when shutting
+    # down the server.
+    #
+    # * pool_keep_alive: The amount of time in seconds to wait
+    # for currently busy thread-pool threads to finish before
+    # forcing an abrupt exit to each thread.
+    #
+    # * connect_md_proc:
+    # when non-nil is a proc for determining metadata to send back the client
+    # on receiving an invocation req.  The proc signature is:
+    #   {key: val, ..} func(method_name, {key: val, ...})
+    #
+    # * server_args:
+    # A server arguments hash to be passed down to the underlying core server
+    #
+    # * interceptors:
+    # An array of GRPC::ServerInterceptor objects that will be used for
+    # intercepting server handlers to provide extra functionality.
+    # Interceptors are an EXPERIMENTAL API.
+    #
+    def initialize(pool_size: DEFAULT_POOL_SIZE,
+                   max_waiting_requests: DEFAULT_MAX_WAITING_REQUESTS,
+                   poll_period: DEFAULT_POLL_PERIOD,
+                   pool_keep_alive: Pool::DEFAULT_KEEP_ALIVE,
+                   connect_md_proc: nil,
+                   server_args: {},
+                   interceptors: [])
+      @connect_md_proc = RpcServer.setup_connect_md_proc(connect_md_proc)
+      @max_waiting_requests = max_waiting_requests
+      @poll_period = poll_period
+      @pool_size = pool_size
+      @pool = Pool.new(@pool_size, keep_alive: pool_keep_alive)
+      @run_cond = ConditionVariable.new
+      @run_mutex = Mutex.new
+      # running_state can take 4 values: :not_started, :running, :stopping, and
+      # :stopped. State transitions can only proceed in that order.
+      @running_state = :not_started
+      @server = Core::Server.new(server_args)
+      @interceptors = InterceptorRegistry.new(interceptors)
+    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 called via run_till_terminated_or_interrupted,
+      #   signal stop_server_thread and don't do anything
+      if @stop_server.nil? == false && @stop_server == false
+        @stop_server = true
+        @stop_server_cv.broadcast
+        return
+      end
+      @run_mutex.synchronize do
+        fail 'Cannot stop before starting' if @running_state == :not_started
+        return if @running_state != :running
+        transition_running_state(:stopping)
+        deadline = from_relative_time(@poll_period)
+        @server.shutdown_and_notify(deadline)
+      end
+      @pool.stop
+    end
+
+    def running_state
+      @run_mutex.synchronize do
+        return @running_state
+      end
+    end
+
+    # Can only be called while holding @run_mutex
+    def transition_running_state(target_state)
+      state_transitions = {
+        not_started: :running,
+        running: :stopping,
+        stopping: :stopped
+      }
+      if state_transitions[@running_state] == target_state
+        @running_state = target_state
+      else
+        fail "Bad server state transition: #{@running_state}->#{target_state}"
+      end
+    end
+
+    def running?
+      running_state == :running
+    end
+
+    def stopped?
+      running_state == :stopped
+    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
+    # @return [true, false] true if the server is running, false otherwise
+    def wait_till_running(timeout = nil)
+      @run_mutex.synchronize do
+        @run_cond.wait(@run_mutex, timeout) if @running_state == :not_started
+        return @running_state == :running
+      end
+    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
+    # - its 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)
+      @run_mutex.synchronize do
+        unless @running_state == :not_started
+          fail 'cannot add services if the server has been started'
+        end
+        cls = service.is_a?(Class) ? service : service.class
+        assert_valid_service_class(cls)
+        add_rpc_descs_for(service)
+      end
+    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
+      @run_mutex.synchronize do
+        fail 'cannot run without registering services' if rpc_descs.size.zero?
+        @pool.start
+        @server.start
+        transition_running_state(:running)
+        @run_cond.broadcast
+      end
+      loop_handle_server_calls
+    end
+
+    alias_method :run_till_terminated, :run
+
+    # runs the server with signal handlers
+    # @param signals
+    #     List of String, Integer or both representing signals that the user
+    #     would like to send to the server for graceful shutdown
+    # @param wait_interval (optional)
+    #     Integer seconds that user would like stop_server_thread to poll
+    #     stop_server
+    def run_till_terminated_or_interrupted(signals, wait_interval = 60)
+      @stop_server = false
+      @stop_server_mu = Mutex.new
+      @stop_server_cv = ConditionVariable.new
+
+      @stop_server_thread = Thread.new do
+        loop do
+          break if @stop_server
+          @stop_server_mu.synchronize do
+            @stop_server_cv.wait(@stop_server_mu, wait_interval)
+          end
+        end
+
+        # stop is surrounded by mutex, should handle multiple calls to stop
+        #   correctly
+        stop
+      end
+
+      valid_signals = Signal.list
+
+      # register signal handlers
+      signals.each do |sig|
+        # input validation
+        target_sig = if sig.class == String
+                       # cut out the SIG prefix to see if valid signal
+                       sig.upcase.start_with?('SIG') ? sig.upcase[3..-1] : sig.upcase
+                     else
+                       sig
+                     end
+
+        # register signal traps for all valid signals
+        if valid_signals.value?(target_sig) || valid_signals.key?(target_sig)
+          Signal.trap(target_sig) do
+            @stop_server = true
+            @stop_server_cv.broadcast
+          end
+        else
+          fail "#{target_sig} not a valid signal"
+        end
+      end
+
+      run
+
+      @stop_server_thread.join
+    end
+
+    # Sends RESOURCE_EXHAUSTED if there are too many unprocessed jobs
+    def available?(an_rpc)
+      return an_rpc if @pool.ready_for_work?
+      GRPC.logger.warn('no free worker threads currently')
+      noop = proc { |x| x }
+
+      # Create a new active call that knows that metadata hasn't been
+      # sent yet
+      c = ActiveCall.new(an_rpc.call, noop, noop, an_rpc.deadline,
+                         metadata_received: true, started: false)
+      c.send_status(GRPC::Core::StatusCodes::RESOURCE_EXHAUSTED,
+                    'No free threads in thread pool')
+      nil
+    end
+
+    # Sends UNIMPLEMENTED if the method is not implemented by this server
+    def implemented?(an_rpc)
+      mth = an_rpc.method.to_sym
+      return an_rpc if rpc_descs.key?(mth)
+      GRPC.logger.warn("UNIMPLEMENTED: #{an_rpc}")
+      noop = proc { |x| x }
+
+      # Create a new active call that knows that
+      # metadata hasn't been sent yet
+      c = ActiveCall.new(an_rpc.call, noop, noop, an_rpc.deadline,
+                         metadata_received: true, started: false)
+      c.send_status(GRPC::Core::StatusCodes::UNIMPLEMENTED, '')
+      nil
+    end
+
+    # handles calls to the server
+    def loop_handle_server_calls
+      fail 'not started' if running_state == :not_started
+      while running_state == :running
+        begin
+          an_rpc = @server.request_call
+          break if (!an_rpc.nil?) && an_rpc.call.nil?
+          active_call = new_active_server_call(an_rpc)
+          unless active_call.nil?
+            @pool.schedule(active_call) do |ac|
+              c, mth = ac
+              begin
+                rpc_descs[mth].run_server_method(
+                  c,
+                  rpc_handlers[mth],
+                  @interceptors.build_context
+                )
+              rescue StandardError
+                c.send_status(GRPC::Core::StatusCodes::INTERNAL,
+                              'Server handler failed')
+              end
+            end
+          end
+        rescue Core::CallError, RuntimeError => e
+          # these might happen for various reasons.  The correct behavior of
+          # the server is to log them and continue, if it's not shutting down.
+          if running_state == :running
+            GRPC.logger.warn("server call failed: #{e}")
+          end
+          next
+        end
+      end
+      # @running_state should be :stopping here
+      @run_mutex.synchronize do
+        transition_running_state(:stopped)
+        GRPC.logger.info("stopped: #{self}")
+        @server.close
+      end
+    end
+
+    def new_active_server_call(an_rpc)
+      return nil if an_rpc.nil? || an_rpc.call.nil?
+
+      # allow the metadata to be accessed from the call
+      an_rpc.call.metadata = an_rpc.metadata  # attaches md to call for handlers
+      connect_md = nil
+      unless @connect_md_proc.nil?
+        connect_md = @connect_md_proc.call(an_rpc.method, an_rpc.metadata)
+      end
+
+      return nil unless available?(an_rpc)
+      return nil unless implemented?(an_rpc)
+
+      # Create the ActiveCall. Indicate that metadata hasnt been sent yet.
+      GRPC.logger.info("deadline is #{an_rpc.deadline}; (now=#{Time.now})")
+      rpc_desc = rpc_descs[an_rpc.method.to_sym]
+      c = ActiveCall.new(an_rpc.call,
+                         rpc_desc.marshal_proc,
+                         rpc_desc.unmarshal_proc(:input),
+                         an_rpc.deadline,
+                         metadata_received: true,
+                         started: false,
+                         metadata_to_send: connect_md)
+      c.attach_peer_cert(an_rpc.call.peer_cert)
+      mth = an_rpc.method.to_sym
+      [c, mth]
+    end
+
+    protected
+
+    def rpc_descs
+      @rpc_descs ||= {}
+    end
+
+    def rpc_handlers
+      @rpc_handlers ||= {}
+    end
+
+    def assert_valid_service_class(cls)
+      unless cls.include?(GenericService)
+        fail "#{cls} must 'include GenericService'"
+      end
+      fail "#{cls} should specify some rpc descriptions" if
+        cls.rpc_descs.size.zero?
+    end
+
+    # This should be called while holding @run_mutex
+    def add_rpc_descs_for(service)
+      cls = service.is_a?(Class) ? service : service.class
+      specs, handlers = (@rpc_descs ||= {}), (@rpc_handlers ||= {})
+      cls.rpc_descs.each_pair do |name, spec|
+        route = "/#{cls.service_name}/#{name}".to_sym
+        fail "already registered: rpc #{route} from #{spec}" if specs.key? route
+        specs[route] = spec
+        rpc_name = GenericService.underscore(name.to_s).to_sym
+        if service.is_a?(Class)
+          handlers[route] = cls.new.method(rpc_name)
+        else
+          handlers[route] = service.method(rpc_name)
+        end
+        GRPC.logger.info("handling #{route} with #{handlers[route]}")
+      end
+    end
+  end
+end