Start writing README

examples/python/cancellation/README.md

@@ -4,6 +4,35 @@ RPCs may be cancelled by both the client and the server.
 
 #### Cancellation on the Client Side
 
-
+A client may cancel an RPC for several reasons. Perhaps the data it requested
+has been made irrelevant. Perhaps you, as the client, want to be a good citizen
+of the server and are conserving compute resources.
 
 #### Cancellation on the Server Side
+
+A server is reponsible for cancellation in two ways. It must respond in some way
+when a client initiates a cancellation, otherwise long-running computations
+could continue indefinitely.
+
+It may also decide to cancel the RPC for its own reasons. In our example, the
+server can be configured to cancel an RPC after a certain number of hashes has
+been computed in order to conserve compute resources.
+
+##### Responding to Cancellations from a Servicer Thread
+
+It's important to remember that a gRPC Python server is backed by a thread pool
+with a fixed size. When an RPC is cancelled, the library does *not* terminate
+your servicer thread. It is your responsibility as the application author to
+ensure that your servicer thread terminates soon after the RPC has been
+cancelled.
+
+In this example, we use the `ServicerContext.add_callback` method to set a
+`threading.Event` object when the RPC is terminated. We pass this `Event` object
+down through our hashing algorithm and ensure to check that the RPC is still
+ongoing before each iteration.
+
+
+##### Initiating a Cancellation from a Servicer
+
+Initiating a cancellation from the server side is simpler. Just call
+`ServicerContext.cancel()`.

examples/python/cancellation/client.py

@@ -33,12 +33,6 @@ _LOGGER = logging.getLogger(__name__)
 #   Cancel after we have n matches or we have an exact match.
 
 
-# Test whether cancelling cancels a long-running unary RPC (I doubt it).
-# Start the server with a single thread.
-# Start a request and cancel it soon after.
-# Start another request. If it succesfully cancelled, this will block forever.
-# Add a bunch of logging so we know what's happening.
-
 def main():
     # TODO(rbellevi): Fix the connaissance of target.
     with grpc.insecure_channel('localhost:50051') as channel:

examples/python/cancellation/server.py

@@ -121,9 +121,7 @@ class HashFinder(hash_name_pb2_grpc.HashFinderServicer):
         def on_rpc_done():
             stop_event.set()
         context.add_callback(on_rpc_done)
-        print("Received request:\n{}".format(request))
         result = _find_secret(request.desired_name, request.maximum_hamming_distance, stop_event)
-        print("Returning result:\n{}".format(result))
         return result