=================
Type deai:Promise
=================

.. lua:module:: deai.Promise

A pending value

This encapsulates a pending value. Once this value become available, a "resolved"
signal will be emitted with the value. Each promise should resolve only once ever.

See :lua:meth:`event.any_promise <event.any_promise>`, :lua:meth:`event.join_promises <event.join_promises>`, :lua:meth:`event.new_promise <event.new_promise>`, :lua:meth:`event.ready_promise <event.ready_promise>`, :lua:attr:`Promise.catch <deai.Promise.catch>`, :lua:attr:`Promise.then <deai.Promise.then>` for more information about this type

Methods
==========

.. list-table::
   :header-rows: 0

   * - :lua:meth:`catch(handler) <catch>`
     - Catch promise rejections
   * - :lua:meth:`then(handler) <then>`
     - Chain computation to a promise

.. lua:method:: catch(handler) -> Promise

   :rtype: :lua:mod:`Promise <deai.Promise>`
   :type handler: object
   :param handler:

   Catch promise rejections 

   Create a new promise that resolves when the given promise rejects. The handler will
   be called with the rejection value, and its return value will be what the returned
   promise resolves to.

.. lua:method:: then(handler) -> Promise

   :rtype: :lua:mod:`Promise <deai.Promise>`
   :type handler: object
   :param handler:

   Chain computation to a promise 

   Register a handler to be called after `promise` resolves, the handler will be called
   with the resolved value as argument.

   Returns a promise that will be resolved after handler returns. If handler returns
   another promise, then the promise returned by this function will resolve after the
   promise returned by the handler resolves, otherwise the returned promise will resolve
   to the value returned by the handler.

   Note the handler will always be called after being registered, whether the
   promise returned by this function is freed or not.

   (this function is also available as "then\_", since "then" is a keyword in lua)