@@ -58,6 +58,63 @@ see :PEP:`3153`.
5858Event loops
5959-----------
6060
61+ The event loop is the central execution device provided by :mod: `asyncio `.
62+ It provides multiple facilities, amongst which:
63+
64+ * Registering, executing and cancelling delayed calls (timeouts)
65+
66+ * Creating client and server :ref: `transports <transport >` for various
67+ kinds of communication
68+
69+ * Launching subprocesses and the associated :ref: `transports <transport >`
70+ for communication with an external program
71+
72+ * Delegating costly function calls to a pool of threads
73+
74+ Getting an event loop
75+ ^^^^^^^^^^^^^^^^^^^^^
76+
77+ The easiest way to get an event loop is to call the :func: `get_event_loop `
78+ function.
79+
80+ .. XXX more docs
81+
82+ Delayed calls
83+ ^^^^^^^^^^^^^
84+
85+ The event loop has its own internal clock for computing timeouts.
86+ Which clock is used depends on the (platform-specific) event loop
87+ implementation; ideally it is a monotonic clock. This will generally be
88+ a different clock than :func: `time.time `.
89+
90+ .. method :: time()
91+
92+ Return the current time, as a :class: `float ` value, according to the
93+ event loop's internal clock.
94+
95+ .. method :: call_later(delay, callback, *args)
96+
97+ Arrange for the *callback * to be called after the given *delay *
98+ seconds (either an int or float).
99+
100+ A "handle" is returned: an opaque object with a :meth: `cancel ` method
101+ that can be used to cancel the call.
102+
103+ *callback * will be called exactly once per call to :meth: `call_later `.
104+ If two callbacks are scheduled for exactly the same time, it is
105+ undefined which will be called first.
106+
107+ The optional positional *args * will be passed to the callback when it
108+ is called. If you want the callback to be called with some named
109+ arguments, use a closure or :func: `functools.partial `.
110+
111+ .. method :: call_at(when, callback, *args)
112+
113+ Arrange for the *callback * to be called at the given absolute timestamp
114+ *when * (an int or float), using the same time reference as :meth: `time `.
115+
116+ This method's behavior is the same as :meth: `call_later `.
117+
61118
62119.. _protocol :
63120
0 commit comments