<commit_before>.. _signals:

Signals
=======

The consumer will send various signals as it processes tasks. Callbacks can be
registered as signal handlers, and will be called synchronously by the consumer
process.

The following signals are implemented by Huey:

* ``SIGNAL_CANCELED``: task was canceled due to a pre-execute hook raising
  a :py:class:`CancelExecution` exception.
* ``SIGNAL_COMPLETE``: task has been executed successfully.
* ``SIGNAL_ERROR``: task failed due to an unhandled exception.
* ``SIGNAL_EXECUTING``: task is about to be executed.
* ``SIGNAL_LOCKED``: failed to acquire lock, aborting task.
* ``SIGNAL_RETRYING``: task failed, but will be retried.
* ``SIGNAL_REVOKED``: task is revoked and will not be executed.
* ``SIGNAL_SCHEDULED``: task is not yet ready to run and has been added to the
  schedule for future execution.
* ``SIGNAL_INTERRUPTED``: task is interrupted when consumer exits

When a signal handler is called, it will be called with the following
arguments:

* ``signal``: the signal name, e.g. ``'executing'``.
* ``task``: the :py:class:`Task` instance.

The following signals will include additional arguments:

* ``SIGNAL_ERROR``: includes a third argument ``exc``, which is the
  ``Exception`` that was raised while executing the task.

To register a signal handler, use the :py:meth:`Huey.signal` method:

.. code-block:: python

    @huey.signal()
    def all_signal_handler(signal, task, exc=None):
        # This handler will be called for every signal.
        print('%s - %s' % (signal, task.id))

    @huey.signal(SIGNAL_ERROR, SIGNAL_LOCKED, SIGNAL_CANCELED, SIGNAL_REVOKED)
    def task_not_executed_handler(signal, task, exc=None):
        # This handler will be called for the 4 signals listed, which
        # correspond to error conditions.
        print('[%s] %s - not executed' % (signal, task.id))

    @huey.signal(SIGNAL_COMPLETE)
    def task_success(signal, task):
        # This handle will be called for each task that completes successfully.
        pass<commit_msg>Add interrupted signal handler caveat.<commit_after>.. _signals:

Signals
=======

The consumer will send various signals as it processes tasks. Callbacks can be
registered as signal handlers, and will be called synchronously by the consumer
process.

The following signals are implemented by Huey:

* ``SIGNAL_CANCELED``: task was canceled due to a pre-execute hook raising
  a :py:class:`CancelExecution` exception.
* ``SIGNAL_COMPLETE``: task has been executed successfully.
* ``SIGNAL_ERROR``: task failed due to an unhandled exception.
* ``SIGNAL_EXECUTING``: task is about to be executed.
* ``SIGNAL_LOCKED``: failed to acquire lock, aborting task.
* ``SIGNAL_RETRYING``: task failed, but will be retried.
* ``SIGNAL_REVOKED``: task is revoked and will not be executed.
* ``SIGNAL_SCHEDULED``: task is not yet ready to run and has been added to the
  schedule for future execution.
* ``SIGNAL_INTERRUPTED``: task is interrupted when consumer exits - **only
  available when using the `process` worker model.**

When a signal handler is called, it will be called with the following
arguments:

* ``signal``: the signal name, e.g. ``'executing'``.
* ``task``: the :py:class:`Task` instance.

The following signals will include additional arguments:

* ``SIGNAL_ERROR``: includes a third argument ``exc``, which is the
  ``Exception`` that was raised while executing the task.

To register a signal handler, use the :py:meth:`Huey.signal` method:

.. code-block:: python

    @huey.signal()
    def all_signal_handler(signal, task, exc=None):
        # This handler will be called for every signal.
        print('%s - %s' % (signal, task.id))

    @huey.signal(SIGNAL_ERROR, SIGNAL_LOCKED, SIGNAL_CANCELED, SIGNAL_REVOKED)
    def task_not_executed_handler(signal, task, exc=None):
        # This handler will be called for the 4 signals listed, which
        # correspond to error conditions.
        print('[%s] %s - not executed' % (signal, task.id))

    @huey.signal(SIGNAL_COMPLETE)
    def task_success(signal, task):
        # This handle will be called for each task that completes successfully.
        pass
{'fraction_non_alphanumeric': 0.10421179302045729, 'fraction_numerical': 0.0004813477737665463, 'mean_word_length': 4.188514357053683, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1598589', 'n_tokens_mistral': 1249, 'n_tokens_neox': 1220, 'n_words': 489}