pyopencl 2025.1__cp311-cp311-macosx_10_14_x86_64.whl → 2025.2.2__cp311-cp311-macosx_10_14_x86_64.whl

pyopencl/__init__.py

@@ -23,27 +23,30 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 """
 
+from typing_extensions import override
+from dataclasses import dataclass
 import logging
-from sys import intern
-from typing import Any, Sequence
+from typing import (
+    TYPE_CHECKING, Any, Generic, Literal, TypeAlias, TypeVar, cast,
+    overload)
+from collections.abc import Callable
+from collections.abc import Sequence
 from warnings import warn
 
 # must import, otherwise dtype registry will not be fully populated
 import pyopencl.cltypes
-from pyopencl.version import VERSION, VERSION_STATUS, VERSION_TEXT  # noqa: F401
+from pyopencl.version import VERSION, VERSION_STATUS, VERSION_TEXT
 
 
 __version__ = VERSION_TEXT
 
 logger = logging.getLogger(__name__)
 
-# This supports ocl-icd find shipped OpenCL ICDs, cf.
+# This tells ocl-icd where to find shipped OpenCL ICDs, cf.
 # https://github.com/isuruf/ocl-icd/commit/3862386b51930f95d9ad1089f7157a98165d5a6b
 # via
 # https://github.com/inducer/pyopencl/blob/0b3d0ef92497e6838eea300b974f385f94cb5100/scripts/build-wheels.sh#L43-L44
 import os
-
-
 os.environ["PYOPENCL_HOME"] = os.path.dirname(os.path.abspath(__file__))
 
 try:
@@ -63,6 +66,12 @@ import sys
 
 _PYPY = "__pypy__" in sys.builtin_module_names
 
+from pyopencl.typing import (
+        DTypeT,
+        HasBufferInterface,
+        SVMInnerT,
+        WaitList,
+        )
 from pyopencl._cl import (  # noqa: F401
         get_cl_header_version,
         program_kind,
@@ -176,69 +185,64 @@ from pyopencl._cl import (  # noqa: F401
         )
 
 
-try:
-    from pyopencl._cl import DeviceTopologyAmd  # noqa: F401
-    from pyopencl._cl import enqueue_copy_buffer_p2p_amd  # noqa: F401
-except ImportError:
-    pass
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+    from pyopencl._cl import (
+        DeviceTopologyAmd,
+        enqueue_copy_buffer_p2p_amd,
+        enqueue_map_buffer,
+        enqueue_map_image,
+        UserEvent, ImageDescriptor,
+        SVM, SVMAllocation, SVMPointer,
+        # _enqueue_barrier_with_wait_list, _enqueue_fill_buffer,
+        # _enqueue_marker_with_wait_list,
+        enqueue_fill_image,
+        enqueue_migrate_mem_objects, unload_platform_compiler,
+        GLBuffer, GLRenderBuffer, GLTexture, gl_object_type, gl_texture_info,
+        get_apple_cgl_share_group,
+        enqueue_acquire_gl_objects,
+        enqueue_release_gl_objects,
+        )
+else:
+    try:
+        from pyopencl._cl import DeviceTopologyAmd
+        from pyopencl._cl import enqueue_copy_buffer_p2p_amd
+    except ImportError:
+        pass
 
-if not _PYPY:
-    # FIXME: Add back to default set when pypy support catches up
-    from pyopencl._cl import enqueue_map_buffer  # noqa: F401
-    from pyopencl._cl import enqueue_map_image  # noqa: F401
+    if not _PYPY:
+        # FIXME: Add back to default set when pypy support catches up
+        from pyopencl._cl import enqueue_map_buffer
+        from pyopencl._cl import enqueue_map_image
 
-if get_cl_header_version() >= (1, 1):
-    from pyopencl._cl import UserEvent  # noqa: F401
-if get_cl_header_version() >= (1, 2):
-    from pyopencl._cl import ImageDescriptor
-    from pyopencl._cl import (  # noqa: F401
-        _enqueue_barrier_with_wait_list, _enqueue_fill_buffer,
-        _enqueue_marker_with_wait_list, enqueue_fill_image,
-        enqueue_migrate_mem_objects, unload_platform_compiler)
+    if get_cl_header_version() >= (1, 1):
+        from pyopencl._cl import UserEvent
+    if get_cl_header_version() >= (1, 2):
+        from pyopencl._cl import ImageDescriptor
+        from pyopencl._cl import (  # noqa: F401
+            _enqueue_barrier_with_wait_list, _enqueue_fill_buffer,
+            _enqueue_marker_with_wait_list, enqueue_fill_image,
+            enqueue_migrate_mem_objects, unload_platform_compiler)
 
-if get_cl_header_version() >= (2, 0):
-    from pyopencl._cl import SVM, SVMAllocation, SVMPointer
+    if get_cl_header_version() >= (2, 0):
+        from pyopencl._cl import SVM, SVMAllocation, SVMPointer
 
-if _cl.have_gl():
-    from pyopencl._cl import (  # noqa: F401
-        GLBuffer, GLRenderBuffer, GLTexture, gl_object_type, gl_texture_info)
+    if _cl.have_gl():
+        from pyopencl._cl import (
+            GLBuffer, GLRenderBuffer, GLTexture, gl_object_type, gl_texture_info)
 
-    try:
-        from pyopencl._cl import get_apple_cgl_share_group  # noqa: F401
-    except ImportError:
-        pass
+        try:
+            from pyopencl._cl import get_apple_cgl_share_group
+        except ImportError:
+            pass
 
-    try:
-        from pyopencl._cl import enqueue_acquire_gl_objects  # noqa: F401
-        from pyopencl._cl import enqueue_release_gl_objects  # noqa: F401
-    except ImportError:
-        pass
+        try:
+            from pyopencl._cl import enqueue_acquire_gl_objects
+            from pyopencl._cl import enqueue_release_gl_objects
+        except ImportError:
+            pass
 
-import inspect as _inspect
-
-
-CONSTANT_CLASSES = tuple(
-        getattr(_cl, name) for name in dir(_cl)
-        if _inspect.isclass(getattr(_cl, name))
-        and name[0].islower() and name not in ["zip", "map", "range"])
-
-BITFIELD_CONSTANT_CLASSES = (
-        _cl.device_type,
-        _cl.device_fp_config,
-        _cl.device_exec_capabilities,
-        _cl.command_queue_properties,
-        _cl.mem_flags,
-        _cl.map_flags,
-        _cl.kernel_arg_type_qualifier,
-        _cl.device_affinity_domain,
-        _cl.mem_migration_flags,
-        _cl.device_svm_capabilities,
-        _cl.queue_properties,
-        _cl.svm_mem_flags,
-        _cl.device_atomic_capabilities,
-        _cl.device_device_enqueue_capabilities,
-        _cl.version_bits,
-        )
+import pyopencl._monkeypatch
 
 
 # {{{ diagnostics
@@ -271,11 +275,7 @@ def _find_pyopencl_include_path() -> str:
     # Try to find the include path in the same directory as this file
     include_path = join(abspath(dirname(__file__)), "cl")
     if not exists(include_path):
-        try:
-            # NOTE: only available in Python >=3.9
-            from importlib.resources import files
-        except ImportError:
-            from importlib_resources import files  # type: ignore[no-redef]
+        from importlib.resources import files
 
         include_path = str(files("pyopencl") / "cl")
         if not exists(include_path):
@@ -293,7 +293,9 @@ def _find_pyopencl_include_path() -> str:
 
 # {{{ build option munging
 
-def _split_options_if_necessary(options):
+def _split_options_if_necessary(
+            options: str | Sequence[str]
+        ) -> Sequence[str]:
     if isinstance(options, str):
         import shlex
 
@@ -302,8 +304,8 @@ def _split_options_if_necessary(options):
     return options
 
 
-def _find_include_path(options):
-    def unquote(path):
+def _find_include_path(options: Sequence[str]) -> list[str]:
+    def unquote(path: str):
         if path.startswith('"') and path.endswith('"'):
             return path[1:-1]
         else:
@@ -330,8 +332,8 @@ def _find_include_path(options):
     return include_path
 
 
-def _options_to_bytestring(options):
-    def encode_if_necessary(s):
+def _options_to_bytestring(options: Sequence[str | bytes]):
+    def encode_if_necessary(s: str | bytes) -> bytes:
         if isinstance(s, str):
             return s.encode("utf-8")
         else:
@@ -359,7 +361,7 @@ _PLAT_BUILD_OPTIONS: dict[str, list[str]] = {
         }
 
 
-def enable_debugging(platform_or_context):
+def enable_debugging(platform_or_context: Platform | Context) -> None:
     """Enables debugging for all code subsequently compiled by
     PyOpenCL on the passed *platform*. Alternatively, a context
     may be passed.
@@ -379,16 +381,44 @@ def enable_debugging(platform_or_context):
              stacklevel=2)
 
 
+class RepeatedKernelRetrieval(UserWarning):
+    pass
+
+
+RetT = TypeVar("RetT")
+
+
 class Program:
+    _prg: _Program | None
+    _context: Context
+    _source: str | bytes
+    _build_duration_info: tuple[str, bool, float] | None
+
+    @overload
+    def __init__(self, arg1: _Program) -> None: ...
+
+    @overload
+    def __init__(self, arg1: Context, arg2: str | bytes) -> None: ...
+
+    @overload
+    def __init__(
+            self,
+            arg1: Context,
+            arg2: Sequence[Device],
+            arg3: Sequence[bytes]
+        ) -> None: ...
+
     def __init__(self, arg1, arg2=None, arg3=None):
+        self._knl_retrieval_count: dict[str, int] = {}
+
         if arg2 is None:
             # 1-argument form: program
-            self._prg = arg1
-            self._context = self._prg.get_info(program_info.CONTEXT)
+            self._prg = cast("_Program", arg1)
+            self._context = cast("Context", self._prg.get_info(program_info.CONTEXT))
 
         elif arg3 is None:
             # 2-argument form: context, source
-            context, source = arg1, arg2
+            context, source = cast("tuple[Context, str | bytes]", (arg1, arg2))
 
             from pyopencl.tools import is_spirv
             if is_spirv(source):
@@ -402,13 +432,13 @@ class Program:
             self._prg = None
 
         else:
-            context, device, binaries = arg1, arg2, arg3
+            context, devices, binaries = arg1, arg2, arg3
             self._context = context
-            self._prg = _cl._Program(context, device, binaries)
+            self._prg = _cl._Program(context, devices, binaries)
 
         self._build_duration_info = None
 
-    def _get_prg(self):
+    def _get_prg(self) -> _Program:
         if self._prg is not None:
             return self._prg
         else:
@@ -419,13 +449,13 @@ class Program:
             self._prg = _cl._Program(self._context, self._source)
             return self._prg
 
-    def get_info(self, arg):
+    def get_info(self, arg: program_info) -> object:
         return self._get_prg().get_info(arg)
 
     def get_build_info(self, *args, **kwargs):
         return self._get_prg().get_build_info(*args, **kwargs)
 
-    def all_kernels(self):
+    def all_kernels(self) -> Sequence[Kernel]:
         return self._get_prg().all_kernels()
 
     @property
@@ -434,17 +464,30 @@ class Program:
     int_ptr.__doc__ = _cl._Program.int_ptr.__doc__
 
     @staticmethod
-    def from_int_ptr(int_ptr_value, retain=True):
+    def from_int_ptr(int_ptr_value: int, retain: bool = True):
         return Program(_cl._Program.from_int_ptr(int_ptr_value, retain))
     from_int_ptr.__doc__ = _cl._Program.from_int_ptr.__doc__
 
-    def __getattr__(self, attr):
+    def __getattr__(self, attr: str) -> Kernel:
         try:
             knl = Kernel(self, attr)
             # Nvidia does not raise errors even for invalid names,
             # but this will give an error if the kernel is invalid.
             knl.num_args  # noqa: B018
 
+            count = self._knl_retrieval_count[attr] = (
+                self._knl_retrieval_count.get(attr, 0) + 1)
+
+            if count == 2:
+                # https://github.com/inducer/pyopencl/issues/831
+                # https://github.com/inducer/pyopencl/issues/830#issuecomment-2913538384
+                warn(f"Kernel '{attr}' has been retrieved more than once. "
+                     "Each retrieval creates a new, independent kernel, "
+                     "at possibly considerable expense. "
+                     "To avoid the expense, reuse the retrieved kernel instance. "
+                     "To avoid this warning, use cl.Kernel(prg, name).",
+                     RepeatedKernelRetrieval, stacklevel=2)
+
             if self._build_duration_info is not None:
                 build_descr, _was_cached, duration = self._build_duration_info
                 if duration > 0.2:
@@ -463,29 +506,37 @@ class Program:
     # {{{ build
 
     @classmethod
-    def _process_build_options(cls, context, options, _add_include_path=False):
+    def _process_build_options(cls,
+                context: Context,
+                options: str | Sequence[str] | None,
+                _add_include_path: bool = False
+            ) -> tuple[bytes, Sequence[str]]:
         if options is None:
             options = []
-        if isinstance(options, tuple):
-            options = list(options)
 
         options = _split_options_if_necessary(options)
 
-        options = (options
-                + _DEFAULT_BUILD_OPTIONS
-                + _DEFAULT_INCLUDE_OPTIONS
-                + _PLAT_BUILD_OPTIONS.get(
-                    context.devices[0].platform.name, []))
+        options = (
+            *options,
+            *_DEFAULT_BUILD_OPTIONS,
+            *_DEFAULT_INCLUDE_OPTIONS,
+            *_PLAT_BUILD_OPTIONS.get(context.devices[0].platform.name, []))
 
         forced_options = os.environ.get("PYOPENCL_BUILD_OPTIONS")
         if forced_options:
-            options = options + forced_options.split()
+            options = (
+                *options,
+                *forced_options.split())
 
         return (
                 _options_to_bytestring(options),
                 _find_include_path(options))
 
-    def build(self, options=None, devices=None, cache_dir=None):
+    def build(self,
+              options: str | Sequence[str] | None = None,
+              devices: Sequence[Device] | None = None,
+              cache_dir: str | None = None,
+          ):
         options_bytes, include_path = self._process_build_options(
                 self._context, options)
 
@@ -542,7 +593,11 @@ class Program:
 
         return self
 
-    def _build_and_catch_errors(self, build_func, options_bytes, source=None):
+    def _build_and_catch_errors(self,
+                build_func: Callable[[], RetT],
+                options_bytes: bytes,
+                source: str | None = None,
+            ):
         try:
             return build_func()
         except RuntimeError as e:
@@ -575,7 +630,11 @@ class Program:
 
     # }}}
 
-    def compile(self, options=None, devices=None, headers=None):
+    def compile(self,
+                options: str | Sequence[str] | None = None,
+                devices: Sequence[Device] | None = None,
+                headers: Sequence[tuple[str, Program]] | None = None
+            ):
         if headers is None:
             headers = []
 
@@ -585,15 +644,32 @@ class Program:
                 [(name, prg._get_prg()) for name, prg in headers])
         return self
 
-    def __eq__(self, other):
-        return self._get_prg() == other._get_prg()
-
-    def __ne__(self, other):
-        return self._get_prg() == other._get_prg()
+    @override
+    def __eq__(self, other: object):
+        return (
+            isinstance(other, Program)
+            and self._get_prg() == other._get_prg())
 
+    @override
     def __hash__(self):
         return hash(self._get_prg())
 
+    reference_count: int  # pyright: ignore[reportUninitializedInstanceVariable]
+    context: Context    # pyright: ignore[reportUninitializedInstanceVariable]
+    num_devices: int    # pyright: ignore[reportUninitializedInstanceVariable]
+    devices: Sequence[Device]    # pyright: ignore[reportUninitializedInstanceVariable]
+    source: str    # pyright: ignore[reportUninitializedInstanceVariable]
+    binary_sizes: int    # pyright: ignore[reportUninitializedInstanceVariable]
+    binaries: Sequence[bytes]    # pyright: ignore[reportUninitializedInstanceVariable]
+    num_kernels: int    # pyright: ignore[reportUninitializedInstanceVariable]
+    kernel_names: str    # pyright: ignore[reportUninitializedInstanceVariable]
+    il: bytes    # pyright: ignore[reportUninitializedInstanceVariable]
+    scope_global_ctors_present: bool    # pyright: ignore[reportUninitializedInstanceVariable]
+    scope_global_dtors_present: bool    # pyright: ignore[reportUninitializedInstanceVariable]
+
+
+pyopencl._monkeypatch.add_get_info(Program, Program.get_info, _cl.program_info)
+
 
 def create_program_with_built_in_kernels(context, devices, kernel_names):
     if not isinstance(kernel_names, str):
@@ -615,868 +691,6 @@ def link_program(context, programs, options=None, devices=None):
 # }}}
 
 
-# {{{ monkeypatch C++ wrappers to add functionality
-
-def _add_functionality():
-    def generic_get_cl_version(self):
-        import re
-        version_string = self.version
-        match = re.match(r"^OpenCL ([0-9]+)\.([0-9]+) .*$", version_string)
-        if match is None:
-            raise RuntimeError("%s %s returned non-conformant "
-                               "platform version string '%s'" %
-                               (type(self).__name__, self, version_string))
-
-        return int(match.group(1)), int(match.group(2))
-
-    # {{{ Platform
-
-    def platform_repr(self):
-        return f"<pyopencl.Platform '{self.name}' at 0x{self.int_ptr:x}>"
-
-    Platform.__repr__ = platform_repr
-    Platform._get_cl_version = generic_get_cl_version
-
-    # }}}
-
-    # {{{ Device
-
-    def device_repr(self):
-        return "<pyopencl.Device '{}' on '{}' at 0x{:x}>".format(
-                self.name.strip(), self.platform.name.strip(), self.int_ptr)
-
-    def device_hashable_model_and_version_identifier(self):
-        return ("v1", self.vendor, self.vendor_id, self.name, self.version)
-
-    def device_persistent_unique_id(self):
-        warn("Device.persistent_unique_id is deprecated. "
-                "Use Device.hashable_model_and_version_identifier instead.",
-                DeprecationWarning, stacklevel=2)
-        return device_hashable_model_and_version_identifier(self)
-
-    Device.__repr__ = device_repr
-
-    # undocumented for now:
-    Device._get_cl_version = generic_get_cl_version
-    Device.hashable_model_and_version_identifier = property(
-            device_hashable_model_and_version_identifier)
-    Device.persistent_unique_id = property(device_persistent_unique_id)
-
-    # }}}
-
-    # {{{ Context
-
-    def context_repr(self):
-        return "<pyopencl.Context at 0x{:x} on {}>".format(self.int_ptr,
-                ", ".join(repr(dev) for dev in self.devices))
-
-    def context_get_cl_version(self):
-        return self.devices[0].platform._get_cl_version()
-
-    Context.__repr__ = context_repr
-    from pytools import memoize_method
-    Context._get_cl_version = memoize_method(context_get_cl_version)
-
-    # }}}
-
-    # {{{ CommandQueue
-
-    def command_queue_enter(self):
-        return self
-
-    def command_queue_exit(self, exc_type, exc_val, exc_tb):
-        self.finish()
-        self._finalize()
-
-    def command_queue_get_cl_version(self):
-        return self.device._get_cl_version()
-
-    CommandQueue.__enter__ = command_queue_enter
-    CommandQueue.__exit__ = command_queue_exit
-    CommandQueue._get_cl_version = memoize_method(command_queue_get_cl_version)
-
-    # }}}
-
-    # {{{ _Program (the internal, non-caching version)
-
-    def program_get_build_logs(self):
-        build_logs = []
-        for dev in self.get_info(_cl.program_info.DEVICES):
-            try:
-                log = self.get_build_info(dev, program_build_info.LOG)
-            except Exception:
-                log = "<error retrieving log>"
-
-            build_logs.append((dev, log))
-
-        return build_logs
-
-    def program_build(self, options_bytes, devices=None):
-        err = None
-        try:
-            self._build(options=options_bytes, devices=devices)
-        except Error as e:
-            msg = str(e) + "\n\n" + (75*"="+"\n").join(
-                    f"Build on {dev}:\n\n{log}"
-                    for dev, log in self._get_build_logs())
-            code = e.code
-            routine = e.routine
-
-            err = _cl.RuntimeError(
-                    _cl._ErrorRecord(
-                        msg=msg,
-                        code=code,
-                        routine=routine))
-
-        if err is not None:
-            # Python 3.2 outputs the whole list of currently active exceptions
-            # This serves to remove one (redundant) level from that nesting.
-            raise err
-
-        message = (75*"="+"\n").join(
-                f"Build on {dev} succeeded, but said:\n\n{log}"
-                for dev, log in self._get_build_logs()
-                if log is not None and log.strip())
-
-        if message:
-            if self.kind() == program_kind.SOURCE:
-                build_type = "From-source build"
-            elif self.kind() == program_kind.BINARY:
-                build_type = "From-binary build"
-            elif self.kind() == program_kind.IL:
-                build_type = "From-IL build"
-            else:
-                build_type = "Build"
-
-            compiler_output("%s succeeded, but resulted in non-empty logs:\n%s"
-                    % (build_type, message))
-
-        return self
-
-    _cl._Program._get_build_logs = program_get_build_logs
-    _cl._Program.build = program_build
-
-    # }}}
-
-    # {{{ Event
-    class ProfilingInfoGetter:
-        def __init__(self, event):
-            self.event = event
-
-        def __getattr__(self, name):
-            info_cls = _cl.profiling_info
-
-            try:
-                inf_attr = getattr(info_cls, name.upper())
-            except AttributeError as err:
-                raise AttributeError("%s has no attribute '%s'"
-                        % (type(self), name)) from err
-            else:
-                return self.event.get_profiling_info(inf_attr)
-
-    _cl.Event.profile = property(ProfilingInfoGetter)
-
-    # }}}
-
-    # {{{ Kernel
-
-    kernel_old_get_info = Kernel.get_info
-    kernel_old_get_work_group_info = Kernel.get_work_group_info
-
-    def kernel_set_arg_types(self, arg_types):
-        arg_types = tuple(arg_types)
-
-        # {{{ arg counting bug handling
-
-        # For example:
-        # https://github.com/pocl/pocl/issues/197
-        # (but Apple CPU has a similar bug)
-
-        work_around_arg_count_bug = False
-        warn_about_arg_count_bug = False
-
-        from pyopencl.characterize import has_struct_arg_count_bug
-
-        count_bug_per_dev = [
-                has_struct_arg_count_bug(dev, self.context)
-                for dev in self.context.devices]
-
-        from pytools import single_valued
-        if any(count_bug_per_dev):
-            if all(count_bug_per_dev):
-                work_around_arg_count_bug = single_valued(count_bug_per_dev)
-            else:
-                warn_about_arg_count_bug = True
-
-        # }}}
-
-        from pyopencl.invoker import generate_enqueue_and_set_args
-        self._set_enqueue_and_set_args(
-                *generate_enqueue_and_set_args(
-                        self.function_name,
-                        len(arg_types), self.num_args,
-                        arg_types,
-                        warn_about_arg_count_bug=warn_about_arg_count_bug,
-                        work_around_arg_count_bug=work_around_arg_count_bug,
-                        devs=self.context.devices))
-
-    def kernel_get_work_group_info(self, param, device):
-        try:
-            wg_info_cache = self._wg_info_cache
-        except AttributeError:
-            wg_info_cache = self._wg_info_cache = {}
-
-        cache_key = (param, device.int_ptr)
-        try:
-            return wg_info_cache[cache_key]
-        except KeyError:
-            pass
-
-        result = kernel_old_get_work_group_info(self, param, device)
-        wg_info_cache[cache_key] = result
-        return result
-
-    def kernel_capture_call(self, output_file, queue, global_size, local_size,
-            *args, **kwargs):
-        from pyopencl.capture_call import capture_kernel_call
-        capture_kernel_call(self, output_file, queue, global_size, local_size,
-                *args, **kwargs)
-
-    def kernel_get_info(self, param_name):
-        val = kernel_old_get_info(self, param_name)
-
-        if isinstance(val, _Program):
-            return Program(val)
-        else:
-            return val
-
-    Kernel.get_work_group_info = kernel_get_work_group_info
-
-    # FIXME: Possibly deprecate this version
-    Kernel.set_scalar_arg_dtypes = kernel_set_arg_types
-    Kernel.set_arg_types = kernel_set_arg_types
-
-    Kernel.capture_call = kernel_capture_call
-    Kernel.get_info = kernel_get_info
-
-    # }}}
-
-    # {{{ ImageFormat
-
-    def image_format_repr(self):
-        return "ImageFormat({}, {})".format(
-                channel_order.to_string(self.channel_order,
-                    "<unknown channel order 0x%x>"),
-                channel_type.to_string(self.channel_data_type,
-                    "<unknown channel data type 0x%x>"))
-
-    def image_format_eq(self, other):
-        return (self.channel_order == other.channel_order
-                and self.channel_data_type == other.channel_data_type)
-
-    def image_format_ne(self, other):
-        return not image_format_eq(self, other)
-
-    def image_format_hash(self):
-        return hash((type(self), self.channel_order, self.channel_data_type))
-
-    ImageFormat.__repr__ = image_format_repr
-    ImageFormat.__eq__ = image_format_eq
-    ImageFormat.__ne__ = image_format_ne
-    ImageFormat.__hash__ = image_format_hash
-
-    # }}}
-
-    # {{{ Image
-
-    def image_init(
-                self, context, flags, format, shape=None, pitches=None,
-                hostbuf=None, is_array=False, buffer=None, *,
-                desc: ImageDescriptor | None = None,
-                _through_create_image: bool = False,
-            ) -> None:
-        if hostbuf is not None and not \
-                (flags & (mem_flags.USE_HOST_PTR | mem_flags.COPY_HOST_PTR)):
-            warn("'hostbuf' was passed, but no memory flags to make use of it.",
-                 stacklevel=2)
-
-        if desc is not None:
-            if shape is not None:
-                raise TypeError("shape may not be passed when using descriptor")
-            if pitches is not None:
-                raise TypeError("pitches may not be passed when using descriptor")
-            if is_array:
-                raise TypeError("is_array may not be passed when using descriptor")
-            if buffer is not None:
-                raise TypeError("is_array may not be passed when using descriptor")
-
-            Image._custom_init(self, context, flags, format, desc, hostbuf)
-
-            return
-
-        if shape is None and hostbuf is None:
-            raise Error("'shape' must be passed if 'hostbuf' is not given")
-
-        if shape is None and hostbuf is not None:
-            shape = hostbuf.shape
-
-        if hostbuf is None and pitches is not None:
-            raise Error("'pitches' may only be given if 'hostbuf' is given")
-
-        if context._get_cl_version() >= (1, 2) and get_cl_header_version() >= (1, 2):
-            if not _through_create_image:
-                warn("Non-descriptor Image constructor called. "
-                     "This will stop working in 2026. "
-                     "Use create_image instead (with the same arguments).",
-                     DeprecationWarning, stacklevel=2)
-
-            if buffer is not None and is_array:
-                raise ValueError(
-                        "'buffer' and 'is_array' are mutually exclusive")
-
-            if len(shape) == 3:
-                if buffer is not None:
-                    raise TypeError(
-                            "'buffer' argument is not supported for 3D arrays")
-                elif is_array:
-                    image_type = mem_object_type.IMAGE2D_ARRAY
-                else:
-                    image_type = mem_object_type.IMAGE3D
-
-            elif len(shape) == 2:
-                if buffer is not None:
-                    raise TypeError(
-                            "'buffer' argument is not supported for 2D arrays")
-                elif is_array:
-                    image_type = mem_object_type.IMAGE1D_ARRAY
-                else:
-                    image_type = mem_object_type.IMAGE2D
-
-            elif len(shape) == 1:
-                if buffer is not None:
-                    image_type = mem_object_type.IMAGE1D_BUFFER
-                elif is_array:
-                    raise TypeError("array of zero-dimensional images not supported")
-                else:
-                    image_type = mem_object_type.IMAGE1D
-
-            else:
-                raise ValueError("images cannot have more than three dimensions")
-
-            desc = ImageDescriptor() \
-                # pylint: disable=possibly-used-before-assignment
-
-            desc.image_type = image_type
-            desc.shape = shape  # also sets desc.array_size
-
-            if pitches is None:
-                desc.pitches = (0, 0)
-            else:
-                desc.pitches = pitches
-
-            desc.num_mip_levels = 0  # per CL 1.2 spec
-            desc.num_samples = 0  # per CL 1.2 spec
-            desc.buffer = buffer
-
-            Image._custom_init(self, context, flags, format, desc, hostbuf)
-        else:
-            # legacy init for CL 1.1 and older
-            if is_array:
-                raise TypeError("'is_array=True' is not supported for CL < 1.2")
-            # if num_mip_levels is not None:
-                # raise TypeError(
-                #       "'num_mip_levels' argument is not supported for CL < 1.2")
-            # if num_samples is not None:
-                # raise TypeError(
-                #        "'num_samples' argument is not supported for CL < 1.2")
-            if buffer is not None:
-                raise TypeError("'buffer' argument is not supported for CL < 1.2")
-
-            Image._custom_init(self, context, flags, format, shape,
-                    pitches, hostbuf)
-
-    class _ImageInfoGetter:
-        def __init__(self, event):
-            warn(
-                "Image.image.attr is deprecated and will go away in 2021. "
-                "Use Image.attr directly, instead.", stacklevel=2)
-
-            self.event = event
-
-        def __getattr__(self, name):
-            try:
-                inf_attr = getattr(_cl.image_info, name.upper())
-            except AttributeError as err:
-                raise AttributeError("%s has no attribute '%s'"
-                        % (type(self), name)) from err
-            else:
-                return self.event.get_image_info(inf_attr)
-
-    def image_shape(self):
-        if self.type == mem_object_type.IMAGE2D:
-            return (self.width, self.height)
-        elif self.type == mem_object_type.IMAGE3D:
-            return (self.width, self.height, self.depth)
-        else:
-            raise LogicError("only images have shapes")
-
-    Image.__init__ = image_init
-    Image.image = property(_ImageInfoGetter)
-    Image.shape = property(image_shape)
-
-    # }}}
-
-    # {{{ Error
-
-    def error_str(self):
-        val = self.what
-        try:
-            val.routine  # noqa: B018
-        except AttributeError:
-            return str(val)
-        else:
-            result = ""
-            if val.code() != status_code.SUCCESS:
-                result = status_code.to_string(
-                        val.code(), "<unknown error %d>")
-            routine = val.routine()
-            if routine:
-                result = f"{routine} failed: {result}"
-            what = val.what()
-            if what:
-                if result:
-                    result += " - "
-                result += what
-            return result
-
-    def error_code(self):
-        return self.args[0].code()
-
-    def error_routine(self):
-        return self.args[0].routine()
-
-    def error_what(self):
-        return self.args[0]
-
-    Error.__str__ = error_str
-    Error.code = property(error_code)
-    Error.routine = property(error_routine)
-    Error.what = property(error_what)
-
-    # }}}
-
-    # {{{ MemoryMap
-
-    def memory_map_enter(self):
-        return self
-
-    def memory_map_exit(self, exc_type, exc_val, exc_tb):
-        self.release()
-
-    MemoryMap.__doc__ = """
-        This class may also be used as a context manager in a ``with`` statement.
-        The memory corresponding to this object will be unmapped when
-        this object is deleted or :meth:`release` is called.
-
-        .. automethod:: release
-        """
-    MemoryMap.__enter__ = memory_map_enter
-    MemoryMap.__exit__ = memory_map_exit
-
-    # }}}
-
-    # {{{ SVMPointer
-
-    if get_cl_header_version() >= (2, 0):
-        SVMPointer.__doc__ = """A base class for things that can be passed to
-            functions that allow an SVM pointer, e.g. kernel enqueues and memory
-            copies.
-
-            Objects of this type cannot currently be directly created or
-            implemented in Python.  To obtain objects implementing this type,
-            consider its subtypes :class:`SVMAllocation` and :class:`SVM`.
-
-
-            .. property:: svm_ptr
-
-                Gives the SVM pointer as an :class:`int`.
-
-            .. property:: size
-
-                An :class:`int` denoting the size in bytes, or *None*, if the size
-                of the SVM pointed to is not known.
-
-                *Most* objects of this type (e.g. instances of
-                :class:`SVMAllocation` and :class:`SVM` know their size, so that,
-                for example :class:`enqueue_copy` will automatically copy an entire
-                :class:`SVMAllocation` when a size is not explicitly specified.
-
-            .. automethod:: map
-            .. automethod:: map_ro
-            .. automethod:: map_rw
-            .. automethod:: as_buffer
-            .. property:: buf
-
-                An opaque object implementing the :c:func:`Python buffer protocol
-                <PyObject_GetBuffer>`. It exposes the pointed-to memory as
-                a one-dimensional buffer of bytes, with the size matching
-                :attr:`size`.
-
-                No guarantee is provided that two references to this attribute
-                result in the same object.
-            """
-
-    def svmptr_map(self, queue: CommandQueue, *, flags: int, is_blocking: bool =
-                   True, wait_for: Sequence[Event] | None = None,
-                   size: Event | None = None) -> SVMMap:
-        """
-        :arg is_blocking: If *False*, subsequent code must wait on
-            :attr:`SVMMap.event` in the returned object before accessing the
-            mapped memory.
-        :arg flags: a combination of :class:`pyopencl.map_flags`.
-        :arg size: The size of the map in bytes. If not provided, defaults to
-            :attr:`size`.
-
-        |std-enqueue-blurb|
-        """
-        return SVMMap(self,
-                np.asarray(self.buf),
-                queue,
-                _cl._enqueue_svm_map(queue, is_blocking, flags, self, wait_for,
-                                    size=size))
-
-    def svmptr_map_ro(self, queue: CommandQueue, *, is_blocking: bool = True,
-                      wait_for: Sequence[Event] | None = None,
-                      size: int | None = None) -> SVMMap:
-        """Like :meth:`map`, but with *flags* set for a read-only map.
-        """
-
-        return self.map(queue, flags=map_flags.READ,
-                is_blocking=is_blocking, wait_for=wait_for, size=size)
-
-    def svmptr_map_rw(self, queue: CommandQueue, *, is_blocking: bool = True,
-                      wait_for: Sequence[Event] | None = None,
-                      size: int | None = None) -> SVMMap:
-        """Like :meth:`map`, but with *flags* set for a read-only map.
-        """
-
-        return self.map(queue, flags=map_flags.READ | map_flags.WRITE,
-                is_blocking=is_blocking, wait_for=wait_for, size=size)
-
-    def svmptr__enqueue_unmap(self, queue, wait_for=None):
-        return _cl._enqueue_svm_unmap(queue, self, wait_for)
-
-    def svmptr_as_buffer(self, ctx: Context, *, flags: int | None = None,
-                         size: int | None = None) -> Buffer:
-        """
-        :arg ctx: a :class:`Context`
-        :arg flags: a combination of :class:`pyopencl.map_flags`, defaults to
-            read-write.
-        :arg size: The size of the map in bytes. If not provided, defaults to
-            :attr:`size`.
-        :returns: a :class:`Buffer` corresponding to *self*.
-
-        The memory referred to by this object must not be freed before
-        the returned :class:`Buffer` is released.
-        """
-
-        if flags is None:
-            flags = mem_flags.READ_WRITE | mem_flags.USE_HOST_PTR
-
-        if size is None:
-            size = self.size
-
-        return Buffer(ctx, flags, size=size, hostbuf=self.buf)
-
-    if get_cl_header_version() >= (2, 0):
-        SVMPointer.map = svmptr_map
-        SVMPointer.map_ro = svmptr_map_ro
-        SVMPointer.map_rw = svmptr_map_rw
-        SVMPointer._enqueue_unmap = svmptr__enqueue_unmap
-        SVMPointer.as_buffer = svmptr_as_buffer
-
-    # }}}
-
-    # {{{ SVMAllocation
-
-    if get_cl_header_version() >= (2, 0):
-        SVMAllocation.__doc__ = """
-            Is a :class:`SVMPointer`.
-
-            .. versionadded:: 2016.2
-
-            .. automethod:: __init__
-
-                :arg flags: See :class:`svm_mem_flags`.
-                :arg queue: If not specified, the allocation will be freed
-                    eagerly, irrespective of whether pending/enqueued operations
-                    are still using this memory.
-
-                    If specified, deallocation of the memory will be enqueued
-                    with the given queue, and will only be performed
-                    after previously-enqueue operations in the queue have
-                    completed.
-
-                    It is an error to specify an out-of-order queue.
-
-                    .. warning::
-
-                        Not specifying a queue will typically lead to undesired
-                        behavior, including crashes and memory corruption.
-                        See the warning in :ref:`svm`.
-
-            .. automethod:: enqueue_release
-
-                Enqueue the release of this allocation into *queue*.
-                If *queue* is not specified, enqueue the deallocation
-                into the queue provided at allocation time or via
-                :class:`bind_to_queue`.
-
-            .. automethod:: bind_to_queue
-
-                Change the queue used for implicit enqueue of deallocation
-                to *queue*. Sufficient synchronization is ensured by
-                enqueuing a marker into the old queue and waiting on this
-                marker in the new queue.
-
-            .. automethod:: unbind_from_queue
-
-                Configure the allocation to no longer implicitly enqueue
-                memory allocation. If such a queue was previously provided,
-                :meth:`~CommandQueue.finish` is automatically called on it.
-            """
-
-    # }}}
-
-    # {{{ SVM
-
-    if get_cl_header_version() >= (2, 0):
-        SVM.__doc__ = """Tags an object exhibiting the Python buffer interface
-            (such as a :class:`numpy.ndarray`) as referring to shared virtual
-            memory.
-
-            Is a :class:`SVMPointer`, hence objects of this type may be passed
-            to kernel calls and :func:`enqueue_copy`, and all methods declared
-            there are also available there. Note that :meth:`map` differs
-            slightly from :meth:`SVMPointer.map`.
-
-            Depending on the features of the OpenCL implementation, the following
-            types of objects may be passed to/wrapped in this type:
-
-            *   fine-grain shared memory as returned by (e.g.) :func:`fsvm_empty`,
-                if the implementation supports fine-grained shared virtual memory.
-                This memory may directly be passed to a kernel::
-
-                    ary = cl.fsvm_empty(ctx, 1000, np.float32)
-                    assert isinstance(ary, np.ndarray)
-
-                    prg.twice(queue, ary.shape, None, cl.SVM(ary))
-                    queue.finish() # synchronize
-                    print(ary) # access from host
-
-                Observe how mapping (as needed in coarse-grain SVM) is no longer
-                necessary.
-
-            *   any :class:`numpy.ndarray` (or other Python object with a buffer
-                interface) if the implementation supports fine-grained *system*
-                shared virtual memory.
-
-                This is how plain :mod:`numpy` arrays may directly be passed to a
-                kernel::
-
-                    ary = np.zeros(1000, np.float32)
-                    prg.twice(queue, ary.shape, None, cl.SVM(ary))
-                    queue.finish() # synchronize
-                    print(ary) # access from host
-
-            *   coarse-grain shared memory as returned by (e.g.) :func:`csvm_empty`
-                for any implementation of OpenCL 2.0.
-
-                .. note::
-
-                    Applications making use of coarse-grain SVM may be better
-                    served by opaque-style SVM. See :ref:`opaque-svm`.
-
-                This is how coarse-grain SVM may be used from both host and device::
-
-                    svm_ary = cl.SVM(
-                        cl.csvm_empty(ctx, 1000, np.float32, alignment=64))
-                    assert isinstance(svm_ary.mem, np.ndarray)
-
-                    with svm_ary.map_rw(queue) as ary:
-                        ary.fill(17)  # use from host
-
-                    prg.twice(queue, svm_ary.mem.shape, None, svm_ary)
-
-            Coarse-grain shared-memory *must* be mapped into host address space
-            using :meth:`~SVMPointer.map` before being accessed through the
-            :mod:`numpy` interface.
-
-            .. note::
-
-                This object merely serves as a 'tag' that changes the behavior
-                of functions to which it is passed. It has no special management
-                relationship to the memory it tags. For example, it is permissible
-                to grab a :class:`numpy.ndarray` out of :attr:`SVM.mem` of one
-                :class:`SVM` instance and use the array to construct another.
-                Neither of the tags need to be kept alive.
-
-            .. versionadded:: 2016.2
-
-            .. attribute:: mem
-
-                The wrapped object.
-
-            .. automethod:: __init__
-            .. automethod:: map
-            .. automethod:: map_ro
-            .. automethod:: map_rw
-            """
-
-    # }}}
-
-    def svm_map(self, queue, flags, is_blocking=True, wait_for=None):
-        """
-        :arg is_blocking: If *False*, subsequent code must wait on
-            :attr:`SVMMap.event` in the returned object before accessing the
-            mapped memory.
-        :arg flags: a combination of :class:`pyopencl.map_flags`.
-        :returns: an :class:`SVMMap` instance
-
-        This differs from the inherited :class:`SVMPointer.map` in that no size
-        can be specified, and that :attr:`mem` is the exact array produced
-        when the :class:`SVMMap` is used as a context manager.
-
-        |std-enqueue-blurb|
-        """
-        return SVMMap(
-                self,
-                self.mem,
-                queue,
-                _cl._enqueue_svm_map(queue, is_blocking, flags, self, wait_for))
-
-    def svm_map_ro(self, queue, is_blocking=True, wait_for=None):
-        """Like :meth:`map`, but with *flags* set for a read-only map."""
-
-        return self.map(queue, map_flags.READ,
-                is_blocking=is_blocking, wait_for=wait_for)
-
-    def svm_map_rw(self, queue, is_blocking=True, wait_for=None):
-        """Like :meth:`map`, but with *flags* set for a read-only map."""
-
-        return self.map(queue, map_flags.READ | map_flags.WRITE,
-                is_blocking=is_blocking, wait_for=wait_for)
-
-    def svm__enqueue_unmap(self, queue, wait_for=None):
-        return _cl._enqueue_svm_unmap(queue, self, wait_for)
-
-    if get_cl_header_version() >= (2, 0):
-        SVM.map = svm_map
-        SVM.map_ro = svm_map_ro
-        SVM.map_rw = svm_map_rw
-        SVM._enqueue_unmap = svm__enqueue_unmap
-
-    # }}}
-
-    # ORDER DEPENDENCY: Some of the above may override get_info, the effect needs
-    # to be visible through the attributes. So get_info attr creation needs to happen
-    # after the overriding is complete.
-    cls_to_info_cls = {
-            _cl.Platform: (_cl.Platform.get_info, _cl.platform_info, []),
-            _cl.Device: (_cl.Device.get_info, _cl.device_info,
-                ["PLATFORM", "MAX_WORK_GROUP_SIZE", "MAX_COMPUTE_UNITS"]),
-            _cl.Context: (_cl.Context.get_info, _cl.context_info, []),
-            _cl.CommandQueue: (_cl.CommandQueue.get_info, _cl.command_queue_info,
-                ["CONTEXT", "DEVICE"]),
-            _cl.Event: (_cl.Event.get_info, _cl.event_info, []),
-            _cl.MemoryObjectHolder:
-            (MemoryObjectHolder.get_info, _cl.mem_info, []),
-            Image: (_cl.Image.get_image_info, _cl.image_info, []),
-            Pipe: (_cl.Pipe.get_pipe_info, _cl.pipe_info, []),
-            Program: (Program.get_info, _cl.program_info, []),
-            Kernel: (Kernel.get_info, _cl.kernel_info, []),
-            _cl.Sampler: (Sampler.get_info, _cl.sampler_info, []),
-            }
-
-    def to_string(cls, value, default_format=None):
-        if cls._is_bitfield:
-            names = []
-            for name in dir(cls):
-                attr = getattr(cls, name)
-                if not isinstance(attr, int):
-                    continue
-                if attr == value or attr & value:
-                    names.append(name)
-            if names:
-                return " | ".join(names)
-        else:
-            for name in dir(cls):
-                if (not name.startswith("_")
-                        and getattr(cls, name) == value):
-                    return name
-
-        if default_format is None:
-            raise ValueError("a name for value %d was not found in %s"
-                    % (value, cls.__name__))
-        else:
-            return default_format % value
-
-    for cls in CONSTANT_CLASSES:
-        cls._is_bitfield = cls in BITFIELD_CONSTANT_CLASSES
-        cls.to_string = classmethod(to_string)
-
-    # {{{ get_info attributes -------------------------------------------------
-
-    def make_getinfo(info_method, info_name, info_attr):
-        def result(self):
-            return info_method(self, info_attr)
-
-        return property(result)
-
-    def make_cacheable_getinfo(info_method, info_name, cache_attr, info_attr):
-        def result(self):
-            try:
-                return getattr(self, cache_attr)
-            except AttributeError:
-                pass
-
-            result = info_method(self, info_attr)
-            setattr(self, cache_attr, result)
-            return result
-
-        return property(result)
-
-    for cls, (info_method, info_class, cacheable_attrs) \
-            in cls_to_info_cls.items():
-        for info_name, _info_value in info_class.__dict__.items():
-            if info_name == "to_string" or info_name.startswith("_"):
-                continue
-
-            info_lower = info_name.lower()
-            info_constant = getattr(info_class, info_name)
-            if info_name in cacheable_attrs:
-                cache_attr = intern("_info_cache_"+info_lower)
-                setattr(cls, info_lower, make_cacheable_getinfo(
-                    info_method, info_lower, cache_attr, info_constant))
-            else:
-                setattr(cls, info_lower, make_getinfo(
-                        info_method, info_name, info_constant))
-
-    # }}}
-
-    if _cl.have_gl():
-        def gl_object_get_gl_object(self):
-            return self.get_gl_object_info()[1]
-
-        GLBuffer.gl_object = property(gl_object_get_gl_object)
-        GLTexture.gl_object = property(gl_object_get_gl_object)
-
-
-_add_functionality()
-
-# }}}
-
-
 # {{{ _OverriddenArrayInterfaceSVMAllocation
 
 if get_cl_header_version() >= (2, 0):
@@ -1597,7 +811,21 @@ def choose_devices(interactive: bool | None = None,
 
     # {{{ pick a platform
 
-    platforms = get_platforms()
+    try:
+        platforms = get_platforms()
+    except LogicError as e:
+        if "PLATFORM_NOT_FOUND_KHR" in str(e):
+            # With the cl_khr_icd extension, clGetPlatformIDs fails if no platform
+            # is available:
+            # https://registry.khronos.org/OpenCL/sdk/3.0/docs/man/html/clGetPlatformIDs.html
+            raise RuntimeError("no CL platforms available to ICD loader. "
+                               "Install a CL driver "
+                               "('ICD', such as pocl, rocm, Intel CL) to fix this. "
+                               "See pyopencl docs for help: "
+                               "https://documen.tician.de/pyopencl/"
+                               "misc.html#installation") from e
+        else:
+            raise
 
     if not platforms:
         raise Error("no platforms found")
@@ -1708,7 +936,8 @@ _csc = create_some_context
 
 # {{{ SVMMap
 
-class SVMMap:
+@dataclass
+class SVMMap(Generic[SVMInnerT]):
     """
     Returned by :func:`SVMPointer.map` and :func:`SVM.map`.
     This class may also be used as a context manager in a ``with`` statement.
@@ -1725,11 +954,10 @@ class SVMMap:
     .. automethod:: release
 
     """
-    def __init__(self, svm, array, queue, event):
-        self.svm = svm
-        self.array = array
-        self.queue = queue
-        self.event = event
+    svm: SVM[SVMInnerT] | None
+    array: SVMInnerT
+    queue: CommandQueue
+    event: Event
 
     def __del__(self):
         if self.svm is not None:
@@ -1741,7 +969,10 @@ class SVMMap:
     def __exit__(self, exc_type, exc_val, exc_tb):
         self.release()
 
-    def release(self, queue=None, wait_for=None):
+    def release(self,
+                queue: CommandQueue | None = None,
+                wait_for: WaitList = None
+            ) -> Event:
         """
         :arg queue: a :class:`pyopencl.CommandQueue`. Defaults to the one
             with which the map was created, if not specified.
@@ -1750,7 +981,8 @@ class SVMMap:
         |std-enqueue-blurb|
         """
 
-        evt = self.svm._enqueue_unmap(self.queue)
+        assert self.svm is not None
+        evt = self.svm._enqueue_unmap(queue or self.queue, wait_for)
         self.svm = None
 
         return evt
@@ -1765,7 +997,164 @@ if get_cl_header_version() >= (1, 2):
     _IMAGE_MEM_OBJ_TYPES.append(mem_object_type.IMAGE2D_ARRAY)
 
 
-def enqueue_copy(queue, dest, src, **kwargs):
+@overload
+def enqueue_copy(
+        queue: CommandQueue,
+        dest: Buffer,
+        src: HasBufferInterface,
+        *,
+        dst_offset: int = 0,
+        is_blocking: bool = True,
+        wait_for: WaitList = None
+    ) -> Event: ...
+
+@overload
+def enqueue_copy(
+        queue: CommandQueue,
+        dest: HasBufferInterface,
+        src: Buffer,
+        *,
+        src_offset: int = 0,
+        is_blocking: bool = True,
+        wait_for: WaitList = None
+    ) -> Event: ...
+
+@overload
+def enqueue_copy(
+        queue: CommandQueue,
+        dest: Buffer,
+        src: Buffer,
+        *,
+        src_offset: int = 0,
+        dst_offset: int = 0,
+        byte_count: int | None = None,
+        wait_for: WaitList = None
+    ) -> Event: ...
+
+@overload
+def enqueue_copy(
+        queue: CommandQueue,
+        dest: Buffer,
+        src: HasBufferInterface,
+        *,
+        origin: tuple[int, ...],
+        host_origin: tuple[int, ...],
+        region: tuple[int, ...],
+        buffer_pitches: tuple[int, ...] | None = None,
+        host_pitches: tuple[int, ...] | None = None,
+        is_blocking: bool = True,
+        wait_for: WaitList = None
+    ) -> Event: ...
+
+@overload
+def enqueue_copy(
+        queue: CommandQueue,
+        dest: HasBufferInterface,
+        src: Buffer,
+        *,
+        origin: tuple[int, ...],
+        host_origin: tuple[int, ...],
+        region: tuple[int, ...],
+        buffer_pitches: tuple[int, ...] | None = None,
+        host_pitches: tuple[int, ...] | None = None,
+        is_blocking: bool = True,
+        wait_for: WaitList = None
+    ) -> Event: ...
+
+@overload
+def enqueue_copy(
+        queue: CommandQueue,
+        dest: Buffer,
+        src: Buffer,
+        *,
+        src_origin: tuple[int, ...],
+        dst_origin: tuple[int, ...],
+        region: tuple[int, ...],
+        src_pitches: tuple[int, ...] | None = None,
+        dst_pitches: tuple[int, ...] | None = None,
+        wait_for: WaitList = None
+    ) -> Event: ...
+
+@overload
+def enqueue_copy(
+        queue: CommandQueue,
+        dest: HasBufferInterface,
+        src: Image,
+        *,
+        origin: tuple[int, ...],
+        region: tuple[int, ...],
+        pitches: tuple[int, ...] | None = None,
+        is_blocking: bool = True,
+        wait_for: WaitList = None
+    ) -> Event: ...
+
+@overload
+def enqueue_copy(
+        queue: CommandQueue,
+        dest: Image,
+        src: HasBufferInterface,
+        *,
+        origin: tuple[int, ...],
+        region: tuple[int, ...],
+        pitches: tuple[int, ...] | None = None,
+        is_blocking: bool = True,
+        wait_for: WaitList = None
+    ) -> Event: ...
+
+@overload
+def enqueue_copy(
+        queue: CommandQueue,
+        dest: Image,
+        src: Buffer,
+        *,
+        origin: tuple[int, ...],
+        region: tuple[int, ...],
+        pitches: tuple[int, ...] | None = None,
+        wait_for: WaitList = None
+    ) -> Event: ...
+
+@overload
+def enqueue_copy(
+        queue: CommandQueue,
+        dest: Buffer,
+        src: Image,
+        *,
+        origin: tuple[int, ...],
+        region: tuple[int, ...],
+        pitches: tuple[int, ...] | None = None,
+        wait_for: WaitList = None
+    ) -> Event: ...
+
+@overload
+def enqueue_copy(
+        queue: CommandQueue,
+        dest: Image,
+        src: Image,
+        *,
+        src_origin: tuple[int, ...],
+        dest_origin: tuple[int, ...],
+        region: tuple[int, ...],
+        wait_for: WaitList = None
+    ) -> Event: ...
+
+@overload
+def enqueue_copy(
+        queue: CommandQueue,
+        dest: SVMPointer | HasBufferInterface,
+        src: SVMPointer | HasBufferInterface,
+        *,
+        byte_count: int | None = None,
+
+        # do not use, must be zero
+        src_offset: int = 0,
+        dst_offset: int = 0,
+
+        is_blocking: bool = True,
+        wait_for: WaitList = None
+    ) -> Event: ...
+
+
+def enqueue_copy(queue: CommandQueue, dest: Any, src: Any, **kwargs: Any) -> Event:
     """Copy from :class:`Image`, :class:`Buffer` or the host to
     :class:`Image`, :class:`Buffer` or the host. (Note: host-to-host
     copies are unsupported.)
@@ -2071,9 +1460,11 @@ def enqueue_copy(queue, dest, src, **kwargs):
 # {{{ enqueue_fill
 
 def enqueue_fill(queue: CommandQueue,
-        dest: MemoryObject | SVMPointer,
-        pattern: Any, size: int, *, offset: int = 0,
-        wait_for: Sequence[Event] | None = None) -> Event:
+        dest: MemoryObjectHolder | SVMPointer,
+        pattern: HasBufferInterface,
+        size: int,
+        *, offset: int = 0,
+        wait_for: WaitList = None) -> Event:
     """
     .. versionadded:: 2022.2
     """
@@ -2116,7 +1507,13 @@ DTYPE_TO_CHANNEL_TYPE_NORM = {
     }
 
 
-def image_from_array(ctx, ary, num_channels=None, mode="r", norm_int=False):
+def image_from_array(
+            ctx: Context,
+            ary: NDArray[Any],
+            num_channels: int | None = None,
+            mode: Literal["r"] | Literal["w"] = "r",
+            norm_int: bool = False
+        ) -> Image:
     if not ary.flags.c_contiguous:
         raise ValueError("array must be C-contiguous")
 
@@ -2174,7 +1571,7 @@ def image_from_array(ctx, ary, num_channels=None, mode="r", norm_int=False):
 
 # {{{ enqueue_* compatibility shims
 
-def enqueue_marker(queue, wait_for=None):
+def enqueue_marker(queue: CommandQueue, wait_for: WaitList = None) -> Event:
     if queue._get_cl_version() >= (1, 2) and get_cl_header_version() >= (1, 2):
         return _cl._enqueue_marker_with_wait_list(queue, wait_for)
     else:
@@ -2183,7 +1580,7 @@ def enqueue_marker(queue, wait_for=None):
         return _cl._enqueue_marker(queue)
 
 
-def enqueue_barrier(queue, wait_for=None):
+def enqueue_barrier(queue: CommandQueue, wait_for: WaitList = None) -> Event:
     if queue._get_cl_version() >= (1, 2) and get_cl_header_version() >= (1, 2):
         return _cl._enqueue_barrier_with_wait_list(queue, wait_for)
     else:
@@ -2193,7 +1590,14 @@ def enqueue_barrier(queue, wait_for=None):
         return _cl._enqueue_marker(queue)
 
 
-def enqueue_fill_buffer(queue, mem, pattern, offset, size, wait_for=None):
+def enqueue_fill_buffer(
+            queue: CommandQueue,
+            mem: MemoryObjectHolder,
+            pattern: HasBufferInterface,
+            offset: int,
+            size: int,
+            wait_for: WaitList = None
+        ) -> Event:
     if not (queue._get_cl_version() >= (1, 2) and get_cl_header_version() >= (1, 2)):
         warn(
             "The context for this queue does not declare OpenCL 1.2 support, so "
@@ -2203,14 +1607,21 @@ def enqueue_fill_buffer(queue, mem, pattern, offset, size, wait_for=None):
     if _PYPY and isinstance(pattern, np.generic):
         pattern = np.asarray(pattern)
 
-    return _cl._enqueue_fill_buffer(queue, mem, pattern, offset, size, wait_for)
+    return _cl._enqueue_fill_buffer(queue, mem, pattern, offset, size,
+                                    wait_for)
 
 # }}}
 
 
 # {{{ numpy-like svm allocation
 
-def enqueue_svm_memfill(queue, dest, pattern, byte_count=None, wait_for=None):
+def enqueue_svm_memfill(
+            queue: CommandQueue,
+            dest: SVMPointer,
+            pattern: HasBufferInterface,
+            byte_count: int | None = None,
+            wait_for: WaitList = None
+        ) -> Event:
     """Fill shared virtual memory with a pattern.
 
     :arg dest: a Python buffer object, or any implementation of :class:`SVMPointer`.
@@ -2231,7 +1642,12 @@ def enqueue_svm_memfill(queue, dest, pattern, byte_count=None, wait_for=None):
             queue, dest, pattern, byte_count=byte_count, wait_for=wait_for)
 
 
-def enqueue_svm_migratemem(queue, svms, flags, wait_for=None):
+def enqueue_svm_migrate_mem(
+            queue: CommandQueue,
+            svms: Sequence[SVMPointer],
+            flags: svm_mem_flags,
+            wait_for: WaitList = None,
+        ):
     """
     :arg svms: a collection of Python buffer objects (e.g. :mod:`numpy`
         arrays), or any implementation of :class:`SVMPointer`.
@@ -2244,10 +1660,18 @@ def enqueue_svm_migratemem(queue, svms, flags, wait_for=None):
     This function requires OpenCL 2.1.
     """
 
-    return _cl._enqueue_svm_migratemem(queue, svms, flags, wait_for)
+    return _cl._enqueue_svm_migrate_mem(queue, svms, flags, wait_for)
 
 
-def svm_empty(ctx, flags, shape, dtype, order="C", alignment=None, queue=None):
+def svm_empty(
+            ctx: Context,
+            flags: svm_mem_flags,
+            shape: int | tuple[int, ...],
+            dtype: DTypeT,
+            order: Literal["F"] | Literal["C"] = "C",
+            alignment: int | None = None,
+            queue: CommandQueue | None = None,
+        ) -> np.ndarray[tuple[int, ...], DTypeT]:
     """Allocate an empty :class:`numpy.ndarray` of the given *shape*, *dtype*
     and *order*. (See :func:`numpy.empty` for the meaning of these arguments.)
     The array will be allocated in shared virtual memory belonging
@@ -2274,6 +1698,7 @@ def svm_empty(ctx, flags, shape, dtype, order="C", alignment=None, queue=None):
     dtype = np.dtype(dtype)
 
     try:
+        shape = cast("tuple[int, ...]", shape)
         s = 1
         for dim in shape:
             s *= dim
@@ -2321,13 +1746,16 @@ def svm_empty(ctx, flags, shape, dtype, order="C", alignment=None, queue=None):
     return np.asarray(svm_alloc)
 
 
-def svm_empty_like(ctx, flags, ary, alignment=None):
+def svm_empty_like(
+            ctx: Context,
+            flags: svm_mem_flags,
+            ary: np.ndarray[tuple[int, ...], DTypeT],
+            alignment: int | None = None,
+        ) -> np.ndarray[tuple[int, ...], DTypeT]:
     """Allocate an empty :class:`numpy.ndarray` like the existing
     :class:`numpy.ndarray` *ary*.  The array will be allocated in shared
     virtual memory belonging to *ctx*.
 
-    :arg ctx: a :class:`Context`
-    :arg flags: a combination of flags from :class:`svm_mem_flags`.
     :arg alignment: the number of bytes to which the beginning of the memory
         is aligned. Defaults to the :attr:`numpy.dtype.itemsize` of *dtype*.
 
@@ -2350,27 +1778,46 @@ def svm_empty_like(ctx, flags, ary, alignment=None):
             alignment=alignment)
 
 
-def csvm_empty(ctx, shape, dtype, order="C", alignment=None):
+def csvm_empty(
+            ctx: Context,
+            shape: int | tuple[int, ...],
+            dtype: DTypeT,
+            order: Literal["F"] | Literal["C"] = "C",
+            alignment: int | None = None,
+            queue: CommandQueue | None = None,
+        ) -> np.ndarray[tuple[int, ...], DTypeT]:
     """
     Like :func:`svm_empty`, but with *flags* set for a coarse-grain read-write
     buffer.
 
     .. versionadded:: 2016.2
     """
-    return svm_empty(ctx, svm_mem_flags.READ_WRITE, shape, dtype, order, alignment)
+    return svm_empty(ctx, svm_mem_flags.READ_WRITE, shape, dtype, order,
+                     alignment, queue=queue)
 
 
-def csvm_empty_like(ctx, ary, alignment=None):
+def csvm_empty_like(
+            ctx: Context,
+            ary: np.ndarray[tuple[int, ...], DTypeT],
+            alignment: int | None = None,
+        ) -> np.ndarray[tuple[int, ...], DTypeT]:
     """
     Like :func:`svm_empty_like`, but with *flags* set for a coarse-grain
     read-write buffer.
 
     .. versionadded:: 2016.2
     """
-    return svm_empty_like(ctx, svm_mem_flags.READ_WRITE, ary)
+    return svm_empty_like(ctx, svm_mem_flags.READ_WRITE, ary, alignment)
 
 
-def fsvm_empty(ctx, shape, dtype, order="C", alignment=None):
+def fsvm_empty(
+            ctx: Context,
+            shape: int | tuple[int, ...],
+            dtype: DTypeT,
+            order: Literal["F"] | Literal["C"] = "C",
+            alignment: int | None = None,
+            queue: CommandQueue | None = None,
+        ) -> np.ndarray[tuple[int, ...], DTypeT]:
     """
     Like :func:`svm_empty`, but with *flags* set for a fine-grain read-write
     buffer.
@@ -2379,10 +1826,14 @@ def fsvm_empty(ctx, shape, dtype, order="C", alignment=None):
     """
     return svm_empty(ctx,
             svm_mem_flags.READ_WRITE | svm_mem_flags.SVM_FINE_GRAIN_BUFFER,
-            shape, dtype, order, alignment)
+            shape, dtype, order, alignment, queue)
 
 
-def fsvm_empty_like(ctx, ary, alignment=None):
+def fsvm_empty_like(
+            ctx: Context,
+            ary: np.ndarray[tuple[int, ...], DTypeT],
+            alignment: int | None = None,
+        ) -> np.ndarray[tuple[int, ...], DTypeT]:
     """
     Like :func:`svm_empty_like`, but with *flags* set for a fine-grain
     read-write buffer.
@@ -2392,7 +1843,8 @@ def fsvm_empty_like(ctx, ary, alignment=None):
     return svm_empty_like(
             ctx,
             svm_mem_flags.READ_WRITE | svm_mem_flags.SVM_FINE_GRAIN_BUFFER,
-            ary)
+            ary,
+            alignment)
 
 # }}}
 
@@ -2402,9 +1854,142 @@ _KERNEL_ARG_CLASSES: tuple[type, ...] = (
         Sampler,
         CommandQueue,
         LocalMemory,
+        *([SVM] if get_cl_header_version() >= (2, 0) else [])
         )
-if get_cl_header_version() >= (2, 0):
-    _KERNEL_ARG_CLASSES = (*_KERNEL_ARG_CLASSES, SVM)
+
+
+CtxFactory: TypeAlias = Callable[[], Context]
+
+
+__all__ = [
+    "SVM",
+    "VERSION",
+    "VERSION_STATUS",
+    "VERSION_TEXT",
+    "Buffer",
+    "CommandQueue",
+    "Context",
+    "CtxFactory",
+    "Device",
+    "DeviceTopologyAmd",
+    "Error",
+    "Event",
+    "GLBuffer",
+    "GLRenderBuffer",
+    "GLTexture",
+    "Image",
+    "ImageDescriptor",
+    "ImageFormat",
+    "Kernel",
+    "LocalMemory",
+    "LogicError",
+    "MemoryError",
+    "MemoryMap",
+    "MemoryObject",
+    "MemoryObjectHolder",
+    "NannyEvent",
+    "Pipe",
+    "Platform",
+    "Program",
+    "RuntimeError",
+    "SVMAllocation",
+    "SVMAllocation",
+    "SVMMap",
+    "SVMPointer",
+    "Sampler",
+    "UserEvent",
+    "WaitList",
+    "_csc",
+    "addressing_mode",
+    "channel_order",
+    "channel_type",
+    "choose_devices",
+    "command_execution_status",
+    "command_queue_info",
+    "command_queue_properties",
+    "command_type",
+    "context_info",
+    "context_properties",
+    "create_image",
+    "create_program_with_built_in_kernels",
+    "create_some_context",
+    "csvm_empty",
+    "csvm_empty_like",
+    "device_affinity_domain",
+    "device_atomic_capabilities",
+    "device_device_enqueue_capabilities",
+    "device_exec_capabilities",
+    "device_fp_config",
+    "device_info",
+    "device_local_mem_type",
+    "device_mem_cache_type",
+    "device_partition_property",
+    "device_svm_capabilities",
+    "device_topology_type_amd",
+    "device_type",
+    "enable_debugging",
+    "enqueue_acquire_gl_objects",
+    "enqueue_barrier",
+    "enqueue_copy",
+    "enqueue_copy_buffer_p2p_amd",
+    "enqueue_fill",
+    "enqueue_fill_buffer",
+    "enqueue_fill_image",
+    "enqueue_map_buffer",
+    "enqueue_map_image",
+    "enqueue_marker",
+    "enqueue_migrate_mem_objects",
+    "enqueue_nd_range_kernel",
+    "enqueue_release_gl_objects",
+    "enqueue_svm_memfill",
+    "enqueue_svm_migrate_mem",
+    "event_info",
+    "filter_mode",
+    "fsvm_empty",
+    "fsvm_empty_like",
+    "get_apple_cgl_share_group",
+    "get_cl_header_version",
+    "get_platforms",
+    "get_supported_image_formats",
+    "gl_context_info",
+    "gl_object_type",
+    "gl_texture_info",
+    "have_gl",
+    "image_from_array",
+    "image_info",
+    "kernel_arg_access_qualifier",
+    "kernel_arg_address_qualifier",
+    "kernel_arg_info",
+    "kernel_arg_type_qualifier",
+    "kernel_info",
+    "kernel_sub_group_info",
+    "kernel_work_group_info",
+    "khronos_vendor_id",
+    "link_program",
+    "map_flags",
+    "mem_flags",
+    "mem_info",
+    "mem_migration_flags",
+    "mem_object_type",
+    "pipe_info",
+    "pipe_properties",
+    "platform_info",
+    "profiling_info",
+    "program_binary_type",
+    "program_build_info",
+    "program_info",
+    "program_kind",
+    "queue_properties",
+    "sampler_info",
+    "sampler_properties",
+    "status_code",
+    "svm_empty",
+    "svm_empty_like",
+    "svm_mem_flags",
+    "unload_platform_compiler",
+    "version_bits",
+    "wait_for_events",
+]
 
 
 # vim: foldmethod=marker