Update GRPC Ruby Documentation to Cover Operation Control Feature

[jonmchan]

For server streaming ruby client, there exists functionality to check on the state of the connection and cancel the connection if desired through the return_op: true parameter and utilizing the operation object. I believe it would be beneficial to include this functionality in the documentation, even just as a code snippet example to help others utilize this. I was able to figure this out after digging through the source code for several hours, but I think a simple example would go a long way to help others be able to use this functionality and know that it exists.

Something as simple as:

For advance usage and to be able to control the stream connection:

op = stub.list_features(LIST_FEATURES_RECT, return_op: true)
Thread.new do 
  resps = operation.execute
  resps.each do |r|
    p "- found '#{r.name}' at #{r.location.inspect}"
  end
rescue GRPC::Cancelled => e
  puts "this will terminate with an exception when we hit cancel - #{e}"
end

# controls for the operation
op.status
op.cancelled?
op.cancel # terminates connection and raises GRPC::Cancelled in the thread.

My StackOverflow self-answered question for reference:

https://stackoverflow.com/questions/70635596/aborting-a-grpc-server-stream-connection-in-grpc-ruby-client/70636126#70636126

[sanjaypujare]

Since this is answered on SO, this can be closed?

[jonmchan]

I would argue that the official documentation would be more visible and help developers do less googling than having to search or dig into the source code themselves, but this ultimately has to be decided by the maintainers of the project.

I would argue that this is critical functionality that has been left undocumented in the official docs.

[sanjaypujare]

... I would argue that this is critical functionality that has been left undocumented in the official docs.

Fair enough. So in terms what needs to be added to the official docs I think you suggested adding an example ("...but I think a simple example would go a long way to help others be able to use this functionality and know that it exists...."). Do you want to create a PR for the example? And also some more docs on this site by way of a PR?