============
Module event
============

.. lua:module:: event

Core events

Fundament event sources exposed by deai. This is the building blocks of other event
sources.

See :lua:meth:`dbus <dbus>`, :lua:meth:`evdev <evdev>`, :lua:meth:`event <event>`, :lua:meth:`file <file>`, :lua:meth:`hwinfo <hwinfo>`, :lua:meth:`log <log>`, :lua:meth:`lua <lua>`, :lua:meth:`misc <misc>`, :lua:meth:`os <os>`, :lua:meth:`spawn <spawn>`, :lua:meth:`udev <udev>`, :lua:meth:`xorg <xorg>` for more information about this type

Methods
==========

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

   * - :lua:meth:`any_promise(promises) <any_promise>`
     - Wait for any of the given promises to resolve.
   * - :lua:meth:`fdevent(fd, flag) <fdevent>`
     - File descriptor events
   * - :lua:meth:`join_promises(promises) <join_promises>`
     - Wait for all given promises resolve.
   * - :lua:meth:`new_promise() <new_promise>`
     - Create a new promise object
   * - :lua:meth:`periodic(interval, offset) <periodic>`
     - Periodic timer event
   * - :lua:meth:`ready_promise(value) <ready_promise>`
     - Create a new promise that is already resolved
   * - :lua:meth:`timer(timeout) <timer>`
     - Timer events

.. lua:method:: any_promise(promises) -> Promise

   :rtype: :lua:mod:`Promise <deai.Promise>`
   :type promises: :lua:mod:`[Promise] <deai.Promise>`
   :param promises:

   Wait for any of the given promises to resolve. 

   Returns a promise that resolves when any of the given promises resolves. The
   returned promise will resolve with the value of the first promise that resolves.

.. lua:method:: fdevent(fd, flag) -> IoEv

   :rtype: :lua:mod:`IoEv <deai.builtin.event.IoEv>`
   :type fd: integer
   :param fd:
   :param flag: bit mask of which events to monitor. bit 0 for readability, bit 1 for writability.
   :type flag: integer

   File descriptor events 

   Wait for a file descriptor to be readable/writable.

.. lua:method:: join_promises(promises) -> Promise

   :rtype: :lua:mod:`Promise <deai.Promise>`
   :type promises: :lua:mod:`[Promise] <deai.Promise>`
   :param promises:

   Wait for all given promises resolve. 

   Returns a promises that resolves into an array, which stores the results of
   the promises. The promises can resolve in any order.

.. lua:method:: new_promise() -> Promise

   :rtype: :lua:mod:`Promise <deai.Promise>`

   Create a new promise object 

.. lua:method:: periodic(interval, offset) -> Periodic

   :rtype: :lua:mod:`Periodic <deai.builtin.event.Periodic>`
   :type interval: float
   :param interval:
   :type offset: float
   :param offset:

   Periodic timer event 

   A timer that first fire after :code:`offset` seconds, then every :code:`interval`
   seconds.

.. lua:method:: ready_promise(value) -> Promise

   :rtype: :lua:mod:`Promise <deai.Promise>`
   :param value: what the returned promise will resolve to
   :type value: any

   Create a new promise that is already resolved 

.. lua:method:: timer(timeout) -> Timer

   :rtype: :lua:mod:`Timer <deai.builtin.event.Timer>`
   :param timeout: timeout in seconds
   :type timeout: float

   Timer events 

   Create a timer that emits a signal after timeout is reached. Note that signals will
   only be emitted if listeners exist. If no listeners existed during the timeout window,
   the singal will be emitted when the first listener is attached.