Skip to content

Commit 02ff4f8

Browse files
davidbrochartagronholmerlend-aasland
authored
Added BlockingPortal.call_async() (#1343)
Co-authored-by: Alex Grönholm <[email protected]> Co-authored-by: Erlend E. Aasland <[email protected]>
1 parent 1af29a4 commit 02ff4f8

8 files changed

Lines changed: 412 additions & 5 deletions

File tree

‎changelog.d/1342.added.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Added ``BlockingPortal.call_async()`` for asynchronously calling into an event loop
2+
with optional abandonment on cancellation
Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
from anyio import run, to_thread
2+
from anyio.from_thread import BlockingPortal
3+
4+
5+
async def server_operation() -> str:
6+
return "result from the server's event loop"
7+
8+
9+
async def user_code(portal: BlockingPortal) -> None:
10+
result = await portal.call_async(server_operation)
11+
print(result)
12+
13+
14+
async def main() -> None:
15+
async with BlockingPortal() as portal:
16+
# Run the user-code event loop in a separate thread
17+
await to_thread.run_sync(run, user_code, portal)
18+
19+
20+
run(main)

‎docs/threads.rst‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,22 @@ event loop in its own dedicated thread:
9292

9393
.. note:: The event loop is shut down as soon as you exit the context manager.
9494

95+
Calling between event loops
96+
+++++++++++++++++++++++++++
97+
98+
When a blocking portal belongs to an event loop running in another thread, code in an
99+
event loop can use :meth:`~.BlockingPortal.call_async` to call into it without blocking
100+
the calling thread. For example, a server can expose a portal in its existing event
101+
loop so that user code running in a separate event loop can call back into the server:
102+
103+
.. literalinclude:: snippets/threads/blocking_portal_call_async.py
104+
105+
Cancelling the calling task also cancels the task running in the portal.
106+
By default, the caller waits for the task to finish cleaning up. Any exception raised
107+
during cleanup is propagated to the caller; otherwise, the caller's cancellation is
108+
re-raised. Pass ``abandon_on_cancel=True`` to stop waiting immediately after requesting
109+
cancellation and ignore the task's subsequent return value or any raised exception.
110+
95111
Spawning tasks
96112
++++++++++++++
97113

‎src/anyio/_backends/_asyncio.py‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2852,6 +2852,24 @@ def wrapper() -> None:
28522852
loop.call_soon_threadsafe(wrapper)
28532853
return f.result()
28542854

2855+
@classmethod
2856+
def run_sync_soon(
2857+
cls,
2858+
func: Callable[[Unpack[PosArgsT]], object],
2859+
args: tuple[Unpack[PosArgsT]],
2860+
token: object,
2861+
) -> None:
2862+
loop = cast("AbstractEventLoop", token)
2863+
context = copy_context()
2864+
context.run(set_current_async_library, "asyncio")
2865+
try:
2866+
loop.call_soon_threadsafe(context.run, func, *args)
2867+
except RuntimeError:
2868+
if loop.is_closed():
2869+
raise RunFinishedError from None
2870+
2871+
raise
2872+
28552873
@classmethod
28562874
async def open_process(
28572875
cls,

‎src/anyio/_backends/_trio.py‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
Sequence,
1919
)
2020
from contextlib import AbstractContextManager
21-
from contextvars import Context
21+
from contextvars import Context, copy_context
2222
from dataclasses import dataclass
2323
from functools import partial, wraps
2424
from io import IOBase
@@ -1200,6 +1200,19 @@ def run_sync_from_thread(
12001200
except trio.RunFinishedError:
12011201
raise RunFinishedError from None
12021202

1203+
@classmethod
1204+
def run_sync_soon(
1205+
cls,
1206+
func: Callable[[Unpack[PosArgsT]], object],
1207+
args: tuple[Unpack[PosArgsT]],
1208+
token: object,
1209+
) -> None:
1210+
trio_token = cast("trio.lowlevel.TrioToken", token)
1211+
try:
1212+
trio_token.run_sync_soon(copy_context().run, func, *args)
1213+
except trio.RunFinishedError:
1214+
raise RunFinishedError from None
1215+
12031216
@classmethod
12041217
async def open_process(
12051218
cls,

‎src/anyio/abc/_eventloop.py‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -235,6 +235,16 @@ def run_sync_from_thread(
235235
) -> T_Retval:
236236
pass
237237

238+
@classmethod
239+
@abstractmethod
240+
def run_sync_soon(
241+
cls,
242+
func: Callable[[Unpack[PosArgsT]], object],
243+
args: tuple[Unpack[PosArgsT]],
244+
token: object,
245+
) -> None:
246+
"""Schedule a synchronous callable in an event loop without waiting."""
247+
238248
@classmethod
239249
@abstractmethod
240250
async def open_process(

‎src/anyio/from_thread.py‎

Lines changed: 105 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@
3636
threadlocals,
3737
)
3838
from ._core._eventloop import run as run_eventloop
39-
from ._core._exceptions import NoEventLoopError
39+
from ._core._exceptions import NoEventLoopError, RunFinishedError
4040
from ._core._synchronization import Event
4141
from ._core._tasks import CancelScope, create_task_group
4242
from .abc._tasks import TaskStatus
@@ -253,9 +253,16 @@ def callback(f: Future[T_Retval]) -> None:
253253
if event_loop_thread_id == get_ident():
254254
scope.cancel("the future was cancelled")
255255
elif event_loop_thread_id is not None:
256-
run_sync(
257-
scope.cancel, "the future was cancelled", token=self._token
258-
)
256+
try:
257+
self._token.backend_class.run_sync_soon(
258+
scope.cancel,
259+
("the future was cancelled",),
260+
self._token.native_token,
261+
)
262+
except RunFinishedError:
263+
# The target event loop is gone, so there's nothing left to
264+
# cancel or notify
265+
pass
259266

260267
try:
261268
retval_or_awaitable = func(*args, **kwargs)
@@ -339,6 +346,100 @@ def call(
339346
"""
340347
return cast(T_Retval, self.start_task_soon(func, *args).result())
341348

349+
@overload
350+
async def call_async(
351+
self,
352+
func: Callable[[Unpack[PosArgsT]], Awaitable[T_Retval]],
353+
*args: Unpack[PosArgsT],
354+
abandon_on_cancel: bool = False,
355+
) -> T_Retval: ...
356+
357+
@overload
358+
async def call_async(
359+
self,
360+
func: Callable[[Unpack[PosArgsT]], T_Retval],
361+
*args: Unpack[PosArgsT],
362+
abandon_on_cancel: bool = False,
363+
) -> T_Retval: ...
364+
365+
async def call_async(
366+
self,
367+
func: Callable[[Unpack[PosArgsT]], Awaitable[T_Retval] | T_Retval],
368+
*args: Unpack[PosArgsT],
369+
abandon_on_cancel: bool = False,
370+
) -> T_Retval:
371+
"""
372+
Call the given function in the portal's event loop from another event loop.
373+
374+
If the callable returns an awaitable, it is awaited on. Cancelling the calling
375+
task cancels the task running in the portal.
376+
377+
:param func: any callable
378+
:param abandon_on_cancel: if ``False``, wait for the cancelled task to finish
379+
and propagate any exception raised during cleanup, or otherwise re-raise
380+
the caller's cancellation; if ``True``, stop waiting immediately and ignore
381+
the task's subsequent return value or exception
382+
:raises RuntimeError: if the portal is not running or if this method is called
383+
from within the portal's event loop thread
384+
385+
.. versionadded:: 4.16.0
386+
"""
387+
self._check_running()
388+
source_token = current_token()
389+
event = Event()
390+
future: Future[T_Retval] = Future()
391+
cancellation: Future[None] = Future()
392+
393+
async def run_call() -> None:
394+
with CancelScope() as scope:
395+
396+
def cancel_target(_: Future[None]) -> None:
397+
try:
398+
self._token.backend_class.run_sync_soon(
399+
scope.cancel,
400+
("the calling task was cancelled",),
401+
self._token.native_token,
402+
)
403+
except RunFinishedError:
404+
pass
405+
406+
cancellation.add_done_callback(cancel_target)
407+
await self._call_func(func, args, {}, future)
408+
409+
def notify_source(_: Future[T_Retval]) -> None:
410+
try:
411+
source_token.backend_class.run_sync_soon(
412+
event.set, (), source_token.native_token
413+
)
414+
except RunFinishedError:
415+
pass
416+
417+
def spawn_task() -> None:
418+
try:
419+
self._task_group.start_soon(run_call)
420+
except BaseException as exc:
421+
if not future.done():
422+
future.set_exception(exc)
423+
424+
future.add_done_callback(notify_source)
425+
self._token.backend_class.run_sync_soon(
426+
spawn_task, (), self._token.native_token
427+
)
428+
try:
429+
await event.wait()
430+
except get_cancelled_exc_class():
431+
cancellation.cancel()
432+
if not abandon_on_cancel:
433+
with CancelScope(shield=True):
434+
await event.wait()
435+
436+
if not future.cancelled():
437+
future.result()
438+
439+
raise
440+
441+
return future.result()
442+
342443
@overload
343444
def start_task_soon(
344445
self,

0 commit comments

Comments
 (0)