.. currentmodule:: event_collector.publisher


EventPublisher
==============

**Source code:** `event_collector.publisher.py`

.. py:module:: event_collector.publisher

   This module implements the CollectorEvent and EventPublisher.

.. pull-quote::

   An *EventPublisher* sends *CollectorEvents* to the collector queue. The publisher
   is automatically created when the collector queue is initialized.


Constants & Data Structures
---------------------------

.. autodata:: event_collector.publisher.DEFAULT_PRIORITY


.. autoclass:: event_collector.publisher.QueueType

   ``QueueType`` is an ``Enum`` class representing ``asyncio.Queue`` types.

   .. autoattribute:: FIFO

   .. autoattribute:: PRIORITY

   .. autoattribute:: LIFO


Event Publisher & CollectorEvent
--------------------------------

.. autoclass:: event_collector.publisher.EventPublisher
   :members: send, wait
   :member-order: bysource

   .. py:method:: send(data: Payload) -> CollectorEvent
      :async:

      The ``send`` method is used to put an input event payload onto
      the event queue. The method returns a ``CollectorEvent`` instance
      which can be used to `await` the result.

      Example:

      .. code-block:: python

          ...

          publisher = collector_queue.get_publisher()

          payload = Payload({"data": "some data"})
          event = await publisher.send(payload)

          # event.wait() will block until processing finishes
          result = await event.wait()

      If result is not needed -- in a "fire-and-forget" use case --
      just use ``send`` and ignore the return value::

          payload = Payload({"data": "some data"})
          await publisher.send(payload)

      If using a priority queue, include a priority value (int) in
      the ``Payload``::

          payload = Payload({"data": "some data"}, priority=1)
          await publisher.send(payload)

      Python's ``asyncio.PriorityQueue`` uses a min-heap and is sorted by
      lowest first (lower value has higher priority).


.. autoclass:: event_collector.publisher.CollectorEvent
   :members: get_result, is_done, wait, service_time, wait_time
   :member-order: bysource