Merge branch 'main' into guilhermeleobas/exception-handling

.flake8

@@ -29,6 +29,7 @@ exclude =
     __init__.py
     # Ignore vendored files
     numba/cloudpickle/*
+    versioneer.py
     # Grandfather in existing failing files.  This list should shrink over time
     numba/stencils/stencil.py
     numba/core/transforms.py

docs/source/cuda-reference/kernel.rst

@@ -175,7 +175,7 @@ Synchronization and Atomic Operations
     indices for indexing into multiple dimensional arrays. The number of element
     in ``idx`` must match the number of dimension of ``array``.
 
-    Returns the value of ``array[idx]`` before the storing the new value.
+    Returns the value of ``array[idx]`` before storing the new value.
     Behaves like an atomic load.
 
 .. function:: numba.cuda.atomic.sub(array, idx, value)
@@ -185,7 +185,7 @@ Synchronization and Atomic Operations
     indices for indexing into multi-dimensional arrays. The number of elements
     in ``idx`` must match the number of dimensions of ``array``.
 
-    Returns the value of ``array[idx]`` before the storing the new value.
+    Returns the value of ``array[idx]`` before storing the new value.
     Behaves like an atomic load.
 
 .. function:: numba.cuda.atomic.and_(array, idx, value)
@@ -195,7 +195,7 @@ Synchronization and Atomic Operations
     integer indices for indexing into multi-dimensional arrays. The number
     of elements in ``idx`` must match the number of dimensions of ``array``.
 
-    Returns the value of ``array[idx]`` before the storing the new value.
+    Returns the value of ``array[idx]`` before storing the new value.
     Behaves like an atomic load.
 
 .. function:: numba.cuda.atomic.or_(array, idx, value)
@@ -205,7 +205,7 @@ Synchronization and Atomic Operations
     integer indices for indexing into multi-dimensional arrays. The number
     of elements in ``idx`` must match the number of dimensions of ``array``.
 
-    Returns the value of ``array[idx]`` before the storing the new value.
+    Returns the value of ``array[idx]`` before storing the new value.
     Behaves like an atomic load.
 
 .. function:: numba.cuda.atomic.xor(array, idx, value)
@@ -215,7 +215,7 @@ Synchronization and Atomic Operations
     integer indices for indexing into multi-dimensional arrays. The number
     of elements in ``idx`` must match the number of dimensions of ``array``.
 
-    Returns the value of ``array[idx]`` before the storing the new value.
+    Returns the value of ``array[idx]`` before storing the new value.
     Behaves like an atomic load.
 
 .. function:: numba.cuda.atomic.exch(array, idx, value)
@@ -225,7 +225,7 @@ Synchronization and Atomic Operations
     integer indices for indexing into multi-dimensional arrays. The number
     of elements in ``idx`` must match the number of dimensions of ``array``.
 
-    Returns the value of ``array[idx]`` before the storing the new value.
+    Returns the value of ``array[idx]`` before storing the new value.
     Behaves like an atomic load.
 
 .. function:: numba.cuda.atomic.inc(array, idx, value)
@@ -236,7 +236,7 @@ Synchronization and Atomic Operations
     The number of elements in ``idx`` must match the number of dimensions of
     ``array``.
 
-    Returns the value of ``array[idx]`` before the storing the new value.
+    Returns the value of ``array[idx]`` before storing the new value.
     Behaves like an atomic load.
 
 .. function:: numba.cuda.atomic.dec(array, idx, value)
@@ -248,7 +248,7 @@ Synchronization and Atomic Operations
     The number of elements in ``idx`` must match the number of dimensions of
     ``array``.
 
-    Returns the value of ``array[idx]`` before the storing the new value.
+    Returns the value of ``array[idx]`` before storing the new value.
     Behaves like an atomic load.
 
 .. function:: numba.cuda.atomic.max(array, idx, value)
@@ -259,9 +259,20 @@ Synchronization and Atomic Operations
     The number of element in ``idx`` must match the number of dimension of
     ``array``.
 
-    Returns the value of ``array[idx]`` before the storing the new value.
+    Returns the value of ``array[idx]`` before storing the new value.
     Behaves like an atomic load.
 
+.. function:: numba.cuda.atomic.cas(array, idx, old, value)
+
+    Perform ``if array[idx] == old: array[idx] = value``. Supports int32,
+    int64, uint32, uint64 indexes only. The ``idx`` argument can be an integer
+    or a tuple of integer indices for indexing into multi-dimensional arrays.
+    The number of elements in ``idx`` must match the number of dimensions of
+    ``array``.
+
+    Returns the value of ``array[idx]`` before storing the new value.
+    Behaves like an atomic compare and swap.
+
 
 .. function:: numba.cuda.syncthreads
 

docs/source/cuda/minor_version_compatibility.rst

@@ -17,6 +17,9 @@ Numba supports MVC for CUDA 11 on Linux using the external ``cubinlinker`` and
 - Cooperative Groups are unsupported, because they require an archive to be
   linked.
 
+MVC is not yet supported on CUDA 12 - this will be added in a future release of
+Numba.
+
 MVC is not supported on Windows.
 
 

docs/source/reference/aot-compilation.rst

@@ -3,6 +3,9 @@
 Ahead-of-Time compilation
 =========================
 
+.. note:: This module is pending deprecation. Please see
+          :ref:`deprecation-numba-pycc` for more information.
+
 .. currentmodule:: numba.pycc
 
 .. class:: CC(extension_name, source_module=None)

docs/source/reference/deprecation.rst

@@ -387,6 +387,71 @@ for example::
   print(foo("a string"))
 
 
+.. _deprecation-numba-pycc:
+
+Deprecation of the ``numba.pycc`` module
+========================================
+Numba has supported some degree of Ahead-of-Time (AOT) compilation through the
+use of the tools in the ``numba.pycc`` module. This capability is very important
+to the Numba project and following an assessment of the viability of the current
+approach, it was decided to deprecate it in favour of developing new technology
+to better meet current needs.
+
+Reason for deprecation
+----------------------
+
+There are a number of reasons for this deprecation.
+
+* ``numba.pycc`` tools create C-Extensions that have symbols that are only
+  usable from the Python interpreter, they are not compatible with calls made
+  from within code compiled using Numba's JIT compiler. This drastically reduces
+  the utility of AOT compiled functions.
+* ``numba.pycc`` has some reliance on ``setuptools`` (and ``distutils``) which
+  is something Numba is trying to reduce, particularly due to the upcoming
+  removal of ``distutils`` in Python 3.12.
+* The ``numba.pycc`` compilation chain is very limited in terms of its feature
+  set in comparison to Numba's JIT compiler, it also has numerous technical
+  issues to do with declaring and linking both internal and external libraries.
+* The number of users of ``numba.pycc`` is assumed to be quite small, this was
+  indicated through discussions at a Numba public meeting on 2022-10-04 and
+  issue #8509.
+* The Numba project is working on new innovations in the AOT compiler space and
+  the maintainers consider it a better use of resources to develop these than
+  maintain and develop ``numba.pycc``.
+
+Example(s) of the impact
+------------------------
+
+Any source code using ``numba.pycc`` would fail to work once the functionality
+has been removed.
+
+Schedule
+--------
+
+This feature will be removed with respect to this schedule:
+
+* Pending-deprecation warnings will be issued in version 0.57.0.
+* Deprecation warnings will be issued once a replacement is developed.
+* Deprecation warnings will be given for a minimum of two releases prior to full
+  removal.
+
+Recommendations
+---------------
+
+Projects that need/rely on the deprecated behaviour should pin their dependency
+on Numba to a version prior to removal of this behaviour, or consider following
+replacement instructions below that outline how to adjust to the change.
+
+Replacement
+-----------
+
+A replacement for this functionality is being developed as part of the Numba
+2023 development focus. The ``numba.pycc`` module will not be removed until this
+replacement functionality is able to provide similar utility and offer an
+upgrade path. At the point of the new technology being deemed suitable,
+replacement instructions will be issued.
+
+
 Deprecation of eager compilation of CUDA device functions
 =========================================================
 

docs/source/user/pycc.rst

@@ -8,6 +8,9 @@ Compiling code ahead of time
 While Numba's main use case is :term:`Just-in-Time compilation`, it also
 provides a facility for :term:`Ahead-of-Time compilation` (AOT).
 
+.. note:: This module is pending deprecation. Please see
+          :ref:`deprecation-numba-pycc` for more information.
+
 
 Overview
 ========