Futures
*******

**Código fuente:** Lib/asyncio/futures.py, Lib/asyncio/base_futures.py

======================================================================

Los objetos *Future* se utilizan para conectar **código basado en
retrollamadas de bajo nivel** (*low-level callback-based code*) con
código *async/await* de alto nivel.


Funciones Future
================

asyncio.isfuture(obj)

   Retorna "True" si *obj* es uno de los siguientes:

   * una instancia de "asyncio.Future",

   * una instancia de "asyncio.Task",

   * un objeto tipo Future con un atributo "_asyncio_future_blocking".

   Nuevo en la versión 3.5.

asyncio.ensure_future(obj, *, loop=None)

   Retorna:

   * el argumento *obj* inalterado, si *obj* es una "Future", "Task",
     o un objeto tipo Future (esto se puede verificar con
     "isfuture()".)

   * un objeto "Task" envolviendo *obj*, si *obj* es una corrutina
     (esto se puede verificar con "iscoroutine()"); en este caso, la
     corrutina será programada por "ensure_future()".

   * un objeto "Task" que aguardará a *obj*, si *obj* es aguardable
     (esto se puede verificar con "inspect.isawaitable()".)

   Si *obj* no es ninguno de los superiores, se lanzará "TypeError".

   Importante:

     Ver también la función "create_task()", que es la forma preferida
     de crear nuevas *Tasks*.Save a reference to the result of this
     function, to avoid a task disappearing mid-execution.

   Distinto en la versión 3.5.1: La función acepta cualquier objeto
   *awaitable*.

   Obsoleto desde la versión 3.10: Se emite una advertencia de
   desaprobación si *obj* no es un objeto tipo Future y no se
   especifica *loop* y no hay un bucle de eventos en ejecución.

asyncio.wrap_future(future, *, loop=None)

   Envuelve un objeto "concurrent.futures.Future" en un objeto
   "asyncio.Future".

   Obsoleto desde la versión 3.10: Se emite una advertencia de
   desaprobación si *future* no es un objeto tipo Future y *loop* no
   se especifica y no hay un bucle de eventos en ejecución.


Objeto Future
=============

class asyncio.Future(*, loop=None)

   Un Future representa un resultado eventual de una operación
   asíncrona. No es seguro en hilos (*thread-safe*).

   Future is an *awaitable* object.  Coroutines can await on Future
   objects until they either have a result or an exception set, or
   until they are cancelled. A Future can be awaited multiple times
   and the result is same.

   Normalmente, los Futures se utilizan para permitir que código
   basado en retrollamadas de bajo nivel (*low-level callback-based
   code*) (por ejemplo, en protocolos implementados utilizando
   *asyncio* transports) interactúe con código *async/await* de alto
   nivel.

   Es recomendable no exponer nunca objetos Future en APIs expuestas
   al usuario, y la forma recomendada de crear un objeto Future es
   llamando a "loop.create_future()". De esta forma, implementaciones
   alternativas de bucles de eventos (*event loop*) pueden inyectar
   sus propias implementaciones optimizadas de un objeto Future.

   Distinto en la versión 3.7: Añadido soporte para el módulo
   "contextvars".

   Obsoleto desde la versión 3.10: Se emite una advertencia de
   desaprobación si no se especifica *loop* y no hay un bucle de
   eventos en ejecución.

   result()

      Retorna el resultado del Future.

      Si el Future es *done* y tiene un resultado establecido por el
      método "set_result()", el valor resultante es retornado.

      Si el Future es *done* y tiene una excepción establecida por el
      método "set_exception()", este método lanzará esta excepción.

      Si un evento es *cancelled*, este método lanzará una excepción
      "CancelledError".

      Si el resultado del Future todavía no está disponible, este
      método lanzará una excepción "InvalidStateError".

   set_result(result)

      Marca el Future como *done* y establece su resultado.

      Lanza un error "InvalidStateError" si el Future ya está *done*.

   set_exception(exception)

      Marca el Future como *done* y establece una excepción.

      Lanza un error "InvalidStateError" si el Future ya está *done*.

   done()

      Retorna "True" si el Future está *done*.

      Un Future está *done* si estaba *cancelled* o si tiene un
      resultado o excepción establecidos mediante llamadas a
      "set_result()" o "set_exception()".

   cancelled()

      Retorna "True" si el Future fue *cancelled*.

      El método suele utilizarse para comprobar que un Future no es
      *cancelled* antes de establecer un resultado o excepción al
      mismo:

         if not fut.cancelled():
             fut.set_result(42)

   add_done_callback(callback, *, context=None)

      Añade una retrollamada (*callback*) a ser ejecutada cuando el
      Future es *done*.

      La retrollamada (*callback*) es llamada con el objeto Future
      como su único argumento.

      Si el Future ya es *done* cuando se llama a este método, la
      retrollamada (*callback*) es programada con "loop.call_soon()".

      Un argumento opcional de contexto, por palabra clave, permite
      especificar un "contextvars.Context" personalizado para ser
      ejecutado en la retrollamada (*callback*). El contexto actual se
      utiliza cuando no se provee un contexto (*context*).

      "functools.partial()" se puede utilizar para dar parámetros a la
      retrollamada (*callback*), por ejemplo:

         # Call 'print("Future:", fut)' when "fut" is done.
         fut.add_done_callback(
             functools.partial(print, "Future:"))

      Distinto en la versión 3.7: El parámetro de contexto (*context*)
      por palabra clave fue añadido. Ver **PEP 567** para más
      detalles.

   remove_done_callback(callback)

      Elimina la retrollamada (*callback*) de la lista de
      retrollamadas.

      Retorna el número de retrollamadas (*callbacks*) eliminadas, que
      normalmente es 1, excepto si una retrollamada fue añadida más de
      una vez.

   cancel(msg=None)

      Cancela el Future y programa retrollamadas (*callbacks*).

      Si el Future ya está *done* o *cancelled*, retorna "False". De
      lo contrario, cambia el estado del Future a *cancelled*,
      programa las retrollamadas, y retorna "True".

      Distinto en la versión 3.9: Added the *msg* parameter.

   exception()

      Retorna la excepción definida en este Future.

      La excepción (o "None" si no se había establecido ninguna
      excepción) es retornada sólo si Future es *done*.

      Si un evento es *cancelled*, este método lanzará una excepción
      "CancelledError".

      Si el Future todavía no es *done*, este método lanza una
      excepción "InvalidStateError".

   get_loop()

      Retorna el bucle de eventos (*event loop*) al cual el objeto
      Future está asociado.

      Nuevo en la versión 3.7.

Este ejemplo crea un objeto Future, crea y programa una Task asíncrona
para establecer el resultado para el Future, y espera hasta que el
Future tenga un resultado:

   async def set_after(fut, delay, value):
       # Sleep for *delay* seconds.
       await asyncio.sleep(delay)

       # Set *value* as a result of *fut* Future.
       fut.set_result(value)

   async def main():
       # Get the current event loop.
       loop = asyncio.get_running_loop()

       # Create a new Future object.
       fut = loop.create_future()

       # Run "set_after()" coroutine in a parallel Task.
       # We are using the low-level "loop.create_task()" API here because
       # we already have a reference to the event loop at hand.
       # Otherwise we could have just used "asyncio.create_task()".
       loop.create_task(
           set_after(fut, 1, '... world'))

       print('hello ...')

       # Wait until *fut* has a result (1 second) and print it.
       print(await fut)

   asyncio.run(main())

Importante:

  El objeto Future fue diseñado para imitar a
  "concurrent.futures.Future". Entre las principales diferencias
  están:

  * al contrario que Futures de *asyncio*, las instancias de
    "concurrent.futures.Future" no son aguardables (*await*).

  * "asyncio.Future.result()" y "asyncio.Future.exception()" no
    aceptan el argumento *timeout*.

  * "asyncio.Future.result()" y "asyncio.Future.exception()" lanzan
    una excepción "InvalidStateError" cuando el Future no es *done*.

  * Las retrollamadas (*callbacks*) registradas con
    "asyncio.Future.add_done_callback()" no son llamadas
    inmediatamente, sino que son programadas con "loop.call_soon()".

  * *asyncio* Future no es compatible con las funciones
    "concurrent.futures.wait()" ni
    "concurrent.futures.as_completed()".

  * "asyncio.Future.cancel()" acepta un argumento opcional "msg", pero
    "concurrent.futures.cancel()" no.
