Document the usage of context on server about grpc-go

[iamqizhao]

grpc exposes context for unary rpc and wraps context in stream object for
streaming rpc given a lot of consideration during the design phase.

On Mon, Apr 6, 2015 at 8:56 PM, prazzt [email protected] wrote:

It wasn't clear to me what's the use of context in the generated server
interface. In route guide example:

rpc GetFeature(Point) returns (Feature) {}
rpc ListFeatures(Rectangle) returns (stream Feature) {}

Why is GetFeature
https://github.com/grpc/grpc-go/blob/master/examples/route_guide/proto/route_guide.pb.go#L313
gets context while ListFeatures
https://github.com/grpc/grpc-go/blob/master/examples/route_guide/proto/route_guide.pb.go#L325
dont ?

—
Reply to this email directly or view it on GitHub
#151.

It's still not clear what's the use of context. Graceful shutdown ?

[dsymonds]

http://blog.golang.org/context

No, I understand what context is, but in this case, server implementation could just create it's own context if needed.

Is there any variable bound to the passed context, or is it just to listen to <-context.Done() (graceful shutdown) ?

[dsymonds]

I'm not sure you understand what a context is. It carries deadlines, trace information and cancelation information. A server implementation (that is, a concrete implementation of the interfaces present in the generated code) cannot create any of that.

As I understand from previous issue, client context doesn't get passed to server. So I don't see any use of it here.

An application can have its own context tree, and then only listen to that (if they wanna use context). Imposing the use of context here seems superfluous..

[dsymonds]

No, you misunderstand #130. I'm getting even more convinced you don't understand contexts, which are, admittedly, subtle.

To make myself clear, in blog.golang.org, the interface doesn't impose the use of context. It stays func (w http.ResponseWriter, req *http.Request){} instead of func (ctx context.Context, w http.ResponseWriter, req *http.Request){}

Application that wants to use context can just create it inside the implementation.

[dsymonds]

The net/http package was created and locked down long before the context package existed. If it were being freshly designed today then a context arg could very well be added.

Nothing is imposing the use of contexts. I don't get what your problem is with the context argument being present. If you don't understand contexts and don't want to use them then just ignore that argument.

I don't have any problem with it, since it seems it's already decided early. My question is clear from the beginning: What is the use of context in grpc implementation as of now? Graceful shutdown ? Any values bound to the passed context before ?

I'm asking this because I need to know in my long running grpc handler, what is the use case that might arise on <-ctx.Done() passed from grpc. Please don't be so condescending.

[dsymonds]

I'm not being condescending. You've claimed to understand contexts, but your comments imply otherwise. It's only your most recent comment that you've explained what your problem is.

The context is there because the server is a request handler. The context does what the context does: it carries deadlines and cancelation, as well as trace IDs and other request-scoped metadata.

If you have a long-running handler, yes, check ctx.Done() to determine if the request you are handling has timed out or been canceled. That's how to properly operate with contexts in general, whether in a gRPC handler or elsewhere that provides a context.

Sorry, I should be more clear. Thanks for answering...

I ended up browsing the code. It seems that the context hierarchy might still change. Currently:

1. It's new context derived from context.TODO() for every new transport.Stream
2. Stream scoped, closed when the stream is closed

Closing this issue since it's probably changed in the future.