Merge remote-tracking branch 'wolever/pipeline-context-manager'

1 files changed, 40 insertions, 21 deletions

diff --git a/README.md b/README.md
index 296e152..d32fe9a 100644
--- a/README.md
+++ b/README.md
@@ -174,29 +174,48 @@ execution of that transaction, the entre transaction will be canceled and a
 WatchError will be raised. To implement our own client-side INCR command, we
 could do something like this:
 
+    >>> with r.pipeline() as pipe:
+    ...     while 1:
+    ...         try:
+    ...             # put a WATCH on the key that holds our sequence value
+    ...             pipe.watch('OUR-SEQUENCE-KEY')
+    ...             # after WATCHing, the pipeline is put into immediate execution
+    ...             # mode until we tell it to start buffering commands again.
+    ...             # this allows us to get the current value of our sequence
+    ...             current_value = pipe.get('OUR-SEQUENCE-KEY')
+    ...             next_value = int(current_value) + 1
+    ...             # now we can put the pipeline back into buffered mode with MULTI
+    ...             pipe.multi()
+    ...             pipe.set('OUR-SEQUENCE-KEY', next_value)
+    ...             # and finally, execute the pipeline (the set command)
+    ...             pipe.execute()
+    ...             # if a WatchError wasn't raised during execution, everything
+    ...             # we just did happened atomically.
+    ...             break
+    ...        except WatchError:
+    ...             # another client must have changed 'OUR-SEQUENCE-KEY' between
+    ...             # the time we started WATCHing it and the pipeline's execution.
+    ...             # our best bet is to just retry.
+    ...             continue
+
+Note that, because the `Pipeline` must bind to a single connection for the
+duration of a `watch`, care must be taken to ensure that he connection is
+returned to the connection pool by calling the `reset()` method. If the
+`Pipeline` is used as a context manager (as in the example above) `reset()`
+will be called automatically... But it can also be called manually, like this:
+
     >>> pipe = r.pipeline()
     >>> while 1:
-    >>>     try:
-    >>>         # put a WATCH on the key that holds our sequence value
-    >>>         pipe.watch('OUR-SEQUENCE-KEY')
-    >>>         # after WATCHing, the pipeline is put into immediate execution
-    >>>         # mode until we tell it to start buffering commands again.
-    >>>         # this allows us to get the current value of our sequence
-    >>>         current_value = pipe.get('OUR-SEQUENCE-KEY')
-    >>>         next_value = int(current_value) + 1
-    >>>         # now we can put the pipeline back into buffered mode with MULTI
-    >>>         pipe.multi()
-    >>>         pipe.set('OUR-SEQUENCE-KEY', next_value)
-    >>>         # and finally, execute the pipeline (the set command)
-    >>>         pipe.execute()
-    >>>         # if a WatchError wasn't raised during execution, everything
-    >>>         # we just did happened atomically.
-    >>>         break
-    >>>    except WatchError:
-    >>>         # another client must have changed 'OUR-SEQUENCE-KEY' between
-    >>>         # the time we started WATCHing it and the pipeline's execution.
-    >>>         # our best bet is to just retry.
-    >>>         continue
+    ...     try:
+    ...         pipe.watch('OUR-SEQUENCE-KEY')
+    ...         ...
+    ...         pipe.execute()
+    ...         break
+    ...     except WatchError:
+    ...         continue
+    ...     finally:
+    ...         pipe.reset()
+
 
 ## API Reference