Commit 6825fc1a authored by Jason Madden's avatar Jason Madden

Strengthen the wording about closing 'Timeout' objects. [skip ci]

parent ade482c8
...@@ -83,15 +83,16 @@ class Timeout(BaseException): ...@@ -83,15 +83,16 @@ class Timeout(BaseException):
finally: finally:
timeout.close() timeout.close()
.. note:: .. warning::
If the code that the timeout was protecting finishes You must **always** call `close` on a ``Timeout`` object you have created,
executing before the timeout elapses, be sure to ``close`` the whether or not the code that the timeout was protecting finishes
timeout so it is not unexpectedly raised in the future. Even if it executing before the timeout elapses (whether or not the
is raised, it is a best practice to close it. This ``try/finally`` ``Timeout`` exception is raised) This ``try/finally``
construct or a ``with`` statement is a recommended pattern. (If construct or a ``with`` statement is a good pattern. (If
the timeout object will be started again, use ``cancel`` instead the timeout object will be started again, use `cancel` instead
of ``close``; this is rare.) of `close`; this is rare. You must still `close` it when you are
done.)
When *exception* is omitted or ``None``, the ``Timeout`` instance When *exception* is omitted or ``None``, the ``Timeout`` instance
itself is raised:: itself is raised::
...@@ -187,7 +188,7 @@ class Timeout(BaseException): ...@@ -187,7 +188,7 @@ class Timeout(BaseException):
.. versionchanged:: 1.3a1 .. versionchanged:: 1.3a1
Timeout objects now have a :meth:`close` Timeout objects now have a :meth:`close`
method that must be called when the timeout will no longer be method that *must* be called when the timeout will no longer be
used to properly clean up native resources. used to properly clean up native resources.
The ``with`` statement does this automatically. The ``with`` statement does this automatically.
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment