From 7dccc07c2ac7e54cd44ed1e81cdd2b6daf944f62 Mon Sep 17 00:00:00 2001
From: Richard Belleville <rbellevi@google.com>
Date: Mon, 24 Jun 2019 16:02:34 -0700
Subject: [PATCH] Start writing README

---
 examples/python/cancellation/README.md | 31 +++++++++++++++++++++++++-
 examples/python/cancellation/client.py |  6 -----
 examples/python/cancellation/server.py |  2 --
 3 files changed, 30 insertions(+), 9 deletions(-)

diff --git a/examples/python/cancellation/README.md b/examples/python/cancellation/README.md
index af0c8592625..8d3e4767b9c 100644
--- a/examples/python/cancellation/README.md
+++ b/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()`.
diff --git a/examples/python/cancellation/client.py b/examples/python/cancellation/client.py
index 599a774fefe..93673ad8cc9 100644
--- a/examples/python/cancellation/client.py
+++ b/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:
diff --git a/examples/python/cancellation/server.py b/examples/python/cancellation/server.py
index badf5698b4a..6af36809348 100644
--- a/examples/python/cancellation/server.py
+++ b/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