@@ -192,12 +192,15 @@ Running and stopping the loop
192192..coroutinemethod ::loop.shutdown_default_executor()
193193
194194 Schedule the closure of the default executor and wait for it to join all of
195- the threads in the:class: `ThreadPoolExecutor `. After calling this method, a
196- :exc: `RuntimeError ` will be raised if:meth: `loop.run_in_executor ` is called
197- while using the default executor.
195+ the threads in the:class: `~concurrent.futures.ThreadPoolExecutor `.
196+ Once this method has been called,
197+ using the default executor with:meth: `loop.run_in_executor `
198+ will raise a:exc: `RuntimeError `.
198199
199- Note that there is no need to call this function when
200- :func: `asyncio.run ` is used.
200+ ..note ::
201+
202+ Do not call this method when using:func: `asyncio.run `,
203+ as the latter handles default executor shutdown automatically.
201204
202205 ..versionadded ::3.9
203206
@@ -210,22 +213,23 @@ Scheduling callbacks
210213 Schedule the *callback *:term: `callback ` to be called with
211214 *args * arguments at the next iteration of the event loop.
212215
216+ Return an instance of:class: `asyncio.Handle `,
217+ which can be used later to cancel the callback.
218+
213219 Callbacks are called in the order in which they are registered.
214220 Each callback will be called exactly once.
215221
216- An optional keyword-only *context * argumentallows specifying a
222+ The optional keyword-only *context * argumentspecifies a
217223 custom:class: `contextvars.Context ` for the *callback * to run in.
218- The current context is used when no *context * is provided.
219-
220- An instance of:class: `asyncio.Handle ` is returned, which can be
221- used later to cancel the callback.
224+ Callbacks use the current context when no *context * is provided.
222225
223- This method is not thread-safe.
226+ Unlike :meth: ` call_soon_threadsafe `, this method is not thread-safe.
224227
225228..method ::loop.call_soon_threadsafe(callback, *args, context=None)
226229
227- A thread-safe variant of:meth: `call_soon `. Must be used to
228- schedule callbacks *from another thread *.
230+ A thread-safe variant of:meth: `call_soon `. When scheduling callbacks from
231+ another thread, this function *must * be used, since:meth: `call_soon ` is not
232+ thread-safe.
229233
230234 Raises:exc: `RuntimeError ` if called on a loop that's been closed.
231235 This can happen on a secondary thread when the main application is