asyncio.run_coroutine_threadsafe

Concurrency & Async

Meaning

Runs a coroutine in a given event loop from another thread, returning a concurrent.futures.Future that can be used to retrieve the result or exception. This bridges threading and asyncio by safely scheduling the coroutine on the target loop.

Primary Function

Concurrency / Thread-safe coroutine execution

Communicative Purpose

Allows scheduling a coroutine to run on a specific event loop from a different thread, enabling safe interaction between blocking threads and asyncio code.

Pattern

asyncio.run_coroutine_threadsafe(coro, loop)

Core Structure

asyncio.run_coroutine_threadsafe(..., ...)

Função primária

Concurrency / Thread-safe coroutine execution

Propósito comunicativo

Allows scheduling a coroutine to run on a specific event loop from a different thread, enabling safe interaction between blocking threads and asyncio code.

Situações de gatilho

Calling asyncio code from a GUI toolkit callback, from a ThreadPoolExecutor worker, or from a signal handler where the calling thread does not own the event loop.

Contextos

Python asyncio applications that integrate with threading, GUI frameworks like Tkinter or Qt, or when using concurrent.futures alongside asyncio.

Padrão

asyncio.run_coroutine_threadsafe(coro, loop)

Estrutura central

asyncio.run_coroutine_threadsafe(..., ...)

Slots de substituição

coro: coroutine object, loop: asyncio.AbstractEventLoop (must be running)

Colocados típicos

asyncio.get_event_loop()
concurrent.futures.ThreadPoolExecutor
loop.call_soon_threadsafe
Future.result()

Substituições comuns

Using loop.create_task() when already on the loop's thread
asyncio.run() for top-level entry
or awaiting the coroutine directly if already inside the event loop.

Erros comuns

Passing a regular function instead of a coroutine, using a loop that is not running or closed, forgetting to handle the returned Future's exception, calling from the same thread leading to unnecessary overhead.

Similar / contraste

asyncio.run_coroutine_threadsafe vs loop.call_soon_threadsafe (schedules a callback, not a coroutine); asyncio.run (starts a new loop and runs a coroutine, not thread-safe).

Interferências

Coming from languages with threaded GUI (e.g., C#'s Invoke): may mistakenly think you need to marshal UI updates directly; in Python you must schedule coroutines via run_coroutine_threadsafe.

Família do chunk

asyncio.run_coroutine_threadsafe
loop.call_soon_threadsafe
asyncio.to_thread
asyncio.run

Nuance

Do not use when already on the target event loop thread; await or create_task instead. Using it adds unnecessary thread‑switch overhead. If the loop stops before the Future completes, the result may be lost.

Efeito pragmático

Enables safe integration of blocking threads with asyncio code, preventing race conditions and loop corruption.

Dica de memória

Think 'run coroutine from thread safely'.

Nota

The loop must be running and not closed; calling on a stopped loop raises RuntimeError. The returned Future is thread-safe for result() but does not propagate cancellation to the coroutine – cancellation must be handled inside the coroutine itself.

Upgrade path

Consider using asyncio.to_thread() (Python 3.9+) for offloading blocking calls, or asyncio.create_task() with loop.call_soon_threadsafe for more control.

Frequência: MediumFormulaicidade: Semi-fixedTipo de construção: function callPrioridade de aquisição: Active recallPrioridade de output: BothTag de espaçamento: Medium-termIdioma?: Sim

Examples

import asyncio\nimport threading\nfrom concurrent.futures import ThreadPoolExecutor\nasync def update_status(message: str):\n print(f\"[UI] {message}\" )\ndef blocking_work():\n import time\n time.sleep(2)\n return \"Done\"\ndef worker_thread(loop):\n result = blocking_work()\n future = asyncio.run_coroutine_threadsafe(update_status(result), loop)\n future.result()\nasync def main():\n loop = asyncio.get_running_loop()\n with ThreadPoolExecutor(max_workers=1) as executor:\n executor.submit(worker_thread, loop)\n await asyncio.sleep(3)\nasyncio.run(main())

import asyncio import tkinter as tk from tkinter import ttk import threading async def background_task(): await asyncio.sleep(2) return "Finished" def start_task(): loop = asyncio.get_event_loop() future = asyncio.run_coroutine_threadsafe(background_task(), loop) def check(): if future.done(): try: result = future.result() label.config(text=result) except Exception as e: label.config(text=f"Error: {e}") else: root.after(100, check) root.after(100, check) root = tk.Tk() label = ttk.Label(root, text="Idle") label.pack(padx=20, pady=20) btn = ttk.Button(root, text="Run", command=start_task) btn.pack(padx=20, pady=10) def run_loop(): asyncio.run(asyncio.sleep(3600)) threading.Thread(target=run_loop, daemon=True).start() root.mainloop()

import asyncio import threading async def write_log(entry: str): with open("log.txt", "a") as f: f.write(entry + "\n") def worker(loop, msg): import time time.sleep(1) fut = asyncio.run_coroutine_threadsafe(write_log(msg), loop) fut.result() async def main(): loop = asyncio.get_running_loop() threads = [] for i in range(3): t = threading.Thread(target=worker, args=(loop, f"Message {i}")) t.start() threads.append(t) for t in threads: t.join() await asyncio.sleep(0.5) asyncio.run(main())