Source code for dynasor.logging_tools

""" This module contains functions and variables to control dynasor's logging

* `logger` - the module logger
"""

import logging
import sys

import numba


# This is the root logger of dynasor.
logger = logging.getLogger('dynasor')

# Will process all levels of INFO or higher. This sets the default level.
logger.setLevel(logging.INFO)

# If you know what you are doing you may set this to True.
logger.propagate = False

# The dynasor logger will collect events from children and the default behavior
# is to print it directly to stdout.
ch = logging.StreamHandler(sys.stdout)
ch.setFormatter(logging.Formatter(
    r'%(levelname)s %(asctime)s: %(message)s', datefmt='%Y-%m-%d %H:%M:%S'))
logger.addHandler(ch)




def set_logging_level(level: str) -> None:
    """
    Alters the logging verbosity logging is handled.

    Possible values from least to most verbose:
    `CRITICAL`, `ERROR`, `WARNING`, `INFO`, `DEBUG`.

    Parameters
    ----------
    level
        Verbosity level; see `Python logging library
        <https://docs.python.org/3/library/logging.html>`_ for details.
    """
    logger.setLevel(level)



_has_checked_numba_threading_layer = False




def warn_if_numba_threading_layer_is_slow() -> None:
    """
    Emit a one-time warning if Numba has fallen back to the ``workqueue``
    threading layer, which is available everywhere but not tuned for
    performance; installing `TBB <https://pypi.org/project/tbb/>`_ (``pip
    install tbb``) lets Numba pick a faster, fork-safe layer instead.

    Numba only selects its threading layer lazily, the first time a
    parallel (``@numba.njit(parallel=True)``) kernel actually runs, so this
    is a no-op until that has happened at least once; call it right after
    such a kernel has run.
    """
    global _has_checked_numba_threading_layer
    if _has_checked_numba_threading_layer:
        return
    try:
        layer = numba.threading_layer()
    except ValueError:
        # Threading layer not yet initialized; nothing to check yet.
        return
    _has_checked_numba_threading_layer = True
    if layer == 'workqueue':
        logger.warning(
            'Numba is using the "workqueue" threading layer, which is slower '
            'than the alternatives; install TBB (`pip install tbb`) for '
            'faster parallel CPU kernels.'
        )