[Python-checkins] cpython: Start documenting the event loop
antoine.pitrou
python-checkins at python.org
Sat Nov 23 13:10:16 CET 2013
http://hg.python.org/cpython/rev/b309f396ad26
changeset: 87404:b309f396ad26
user: Antoine Pitrou <solipsis at pitrou.net>
date: Sat Nov 23 13:10:08 2013 +0100
summary:
Start documenting the event loop
files:
Doc/library/asyncio.rst | 57 +++++++++++++++++++++++++++++
1 files changed, 57 insertions(+), 0 deletions(-)
diff --git a/Doc/library/asyncio.rst b/Doc/library/asyncio.rst
--- a/Doc/library/asyncio.rst
+++ b/Doc/library/asyncio.rst
@@ -58,6 +58,63 @@
Event loops
-----------
+The event loop is the central execution device provided by :mod:`asyncio`.
+It provides multiple facilities, amongst which:
+
+* Registering, executing and cancelling delayed calls (timeouts)
+
+* Creating client and server :ref:`transports <transport>` for various
+ kinds of communication
+
+* Launching subprocesses and the associated :ref:`transports <transport>`
+ for communication with an external program
+
+* Delegating costly function calls to a pool of threads
+
+Getting an event loop
+^^^^^^^^^^^^^^^^^^^^^
+
+The easiest way to get an event loop is to call the :func:`get_event_loop`
+function.
+
+.. XXX more docs
+
+Delayed calls
+^^^^^^^^^^^^^
+
+The event loop has its own internal clock for computing timeouts.
+Which clock is used depends on the (platform-specific) event loop
+implementation; ideally it is a monotonic clock. This will generally be
+a different clock than :func:`time.time`.
+
+.. method:: time()
+
+ Return the current time, as a :class:`float` value, according to the
+ event loop's internal clock.
+
+.. method:: call_later(delay, callback, *args)
+
+ Arrange for the *callback* to be called after the given *delay*
+ seconds (either an int or float).
+
+ A "handle" is returned: an opaque object with a :meth:`cancel` method
+ that can be used to cancel the call.
+
+ *callback* will be called exactly once per call to :meth:`call_later`.
+ If two callbacks are scheduled for exactly the same time, it is
+ undefined which will be called first.
+
+ The optional positional *args* will be passed to the callback when it
+ is called. If you want the callback to be called with some named
+ arguments, use a closure or :func:`functools.partial`.
+
+.. method:: call_at(when, callback, *args)
+
+ Arrange for the *callback* to be called at the given absolute timestamp
+ *when* (an int or float), using the same time reference as :meth:`time`.
+
+ This method's behavior is the same as :meth:`call_later`.
+
.. _protocol:
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list