# This file was generated by stubgen-pyx v0.2.6 from cuda_core/cuda/core/_linker.pyx

"""Linking machinery for combining object codes.

This module provides :class:`Linker` for linking one or more
:class:`~cuda.core.ObjectCode` objects, with :class:`LinkerOptions` for
configuration.
"""
from __future__ import annotations

from dataclasses import dataclass
from typing import Union

import cuda.bindings.driver
import cuda.bindings.nvjitlink
from cuda.core._module import ObjectCode
from cuda.core.typing import CompilerBackendType, ObjectCodeFormatType


class Linker:
    """Represent a linking machinery to link one or more object codes into
    :class:`~cuda.core.ObjectCode`.

    This object provides a unified interface to multiple underlying
    linker libraries (such as nvJitLink or cuLink* from the CUDA driver).

    Parameters
    ----------
    object_codes : :class:`~cuda.core.ObjectCode`
        One or more ObjectCode objects to be linked.
    options : :class:`LinkerOptions`, optional
        Options for the linker. If not provided, default options will be used.
    """

    def __init__(self, options: LinkerOptions | None=None, *object_codes: ObjectCode):
        ...

    def link(self, target_type: ObjectCodeFormatType | str) -> ObjectCode:
        """Link the provided object codes into a single output of the specified target type.

        Parameters
        ----------
        target_type : ObjectCodeFormatType | str
            The type of the target output. Must be either "cubin" or "ptx".

        Returns
        -------
        :class:`~cuda.core.ObjectCode`
            The linked object code of the specified target type.

        .. note::

            Ensure that input object codes were compiled with appropriate
            flags for linking (e.g., relocatable device code enabled).
        """

    def get_error_log(self) -> str:
        """Get the error log generated by the linker.

        Returns
        -------
        str
            The error log.
        """

    def get_info_log(self) -> str:
        """Get the info log generated by the linker.

        Returns
        -------
        str
            The info log.
        """

    def close(self) -> None:
        """Destroy this linker."""

    @property
    def handle(self) -> LinkerHandleT:
        """Return the underlying handle object.

        .. note::

           The type of the returned object depends on the backend.

        .. caution::

            This handle is a Python object. To get the memory address of the underlying C
            handle, call ``int(Linker.handle)``.
        """

    @classmethod
    def which_backend(cls) -> CompilerBackendType:
        """Return which linking backend will be used.

        Returns :attr:`~CompilerBackendType.NVJITLINK` when the nvJitLink
        library is available and meets the minimum version requirement,
        otherwise :attr:`~CompilerBackendType.DRIVER`.

        .. note::

            Prefer letting :class:`Linker` decide. Query ``which_backend()``
            only when you need to dispatch based on input format (for
            example: choose PTX vs. LTOIR before constructing a
            ``Linker``). The returned value names an implementation
            detail whose support matrix may shift across CTK releases.
        """

@dataclass
class LinkerOptions:
    """Customizable options for configuring :class:`Linker`.

    Since the linker may choose to use nvJitLink or the driver APIs as the linking backend,
    not all options are applicable. When the system's installed nvJitLink is too old (<12.3),
    or not installed, the driver APIs (cuLink) will be used instead.

    Attributes
    ----------
    name : str, optional
        Name of the linker. If the linking succeeds, the name is passed down to the generated :class:`ObjectCode`.
    arch : str, optional
        Pass the SM architecture value, such as ``sm_<CC>`` (for generating CUBIN) or
        ``compute_<CC>`` (for generating PTX). If not provided, the current device's architecture
        will be used.
    max_register_count : int, optional
        Maximum register count.
    time : bool, optional
        Print timing information to the info log.
        Default: False.
    verbose : bool, optional
        Print verbose messages to the info log.
        Default: False.
    link_time_optimization : bool, optional
        Perform link time optimization.
        Default: False.
    ptx : bool, optional
        Emit PTX after linking instead of CUBIN; only supported with ``link_time_optimization=True``.
        Default: False.
    optimization_level : int, optional
        Set optimization level. Only 0 and 3 are accepted.
    debug : bool, optional
        Generate debug information.
        Default: False.
    lineinfo : bool, optional
        Generate line information.
        Default: False.
    ftz : bool, optional
        Flush denormal values to zero.
        Default: False.
    prec_div : bool, optional
        Use precise division.
        Default: True.
    prec_sqrt : bool, optional
        Use precise square root.
        Default: True.
    fma : bool, optional
        Use fast multiply-add.
        Default: True.
    kernels_used : [str | tuple[str] | list[str]], optional
        Pass a kernel or sequence of kernels that are used; any not in the list can be removed.
    variables_used : [str | tuple[str] | list[str]], optional
        Pass a variable or sequence of variables that are used; any not in the list can be removed.
    optimize_unused_variables : bool, optional
        Assume that if a variable is not referenced in device code, it can be removed.
        Default: False.
    ptxas_options : [str | tuple[str] | list[str]], optional
        Pass options to PTXAS.
    split_compile : int, optional
        Split compilation maximum thread count. Use 0 to use all available processors. Value of 1 disables split
        compilation (default).
        Default: 1.
    split_compile_extended : int, optional
        A more aggressive form of split compilation available in LTO mode only. Accepts a maximum thread count value.
        Use 0 to use all available processors. Value of 1 disables extended split compilation (default). Note: This
        option can potentially impact performance of the compiled binary.
        Default: 1.
    no_cache : bool, optional
        Do not cache the intermediate steps of nvJitLink.
        Default: False.
    """
    name: str | None = '<default linker>'
    arch: str | None = None
    max_register_count: int | None = None
    time: bool | None = None
    verbose: bool | None = None
    link_time_optimization: bool | None = None
    ptx: bool | None = None
    optimization_level: int | None = None
    debug: bool | None = None
    lineinfo: bool | None = None
    ftz: bool | None = None
    prec_div: bool | None = None
    prec_sqrt: bool | None = None
    fma: bool | None = None
    kernels_used: str | tuple[str] | list[str] | None = None
    variables_used: str | tuple[str] | list[str] | None = None
    optimize_unused_variables: bool | None = None
    ptxas_options: str | tuple[str] | list[str] | None = None
    split_compile: int | None = None
    split_compile_extended: int | None = None
    no_cache: bool | None = None
    numba_debug: bool | None = None

    def __post_init__(self) -> None:
        ...

    def _prepare_nvjitlink_options(self, as_bytes: bool=False) -> list[bytes] | list[str]:
        ...

    def _prepare_driver_options(self) -> tuple[list[object], list[object]]:
        ...

    def as_bytes(self, backend: str='nvjitlink') -> list[bytes]:
        """Convert linker options to bytes format for the nvjitlink backend.

        Parameters
        ----------
        backend : str, optional
            The linker backend. Only "nvjitlink" is supported. Default is "nvjitlink".

        Returns
        -------
        list[bytes]
            List of option strings encoded as bytes.

        Raises
        ------
        ValueError
            If an unsupported backend is specified.
        RuntimeError
            If nvJitLink backend is not available.
        """
_keep_driver_in_stub: 'cuda.bindings.driver.CUlinkState'
_keep_nvjitlink_in_stub: 'cuda.bindings.nvjitlink.nvJitLinkHandle'
__all__ = ['Linker', 'LinkerOptions']
LinkerHandleT = Union['cuda.bindings.nvjitlink.nvJitLinkHandle', 'cuda.bindings.driver.CUlinkState']
_driver = None
_inited = False
_use_nvjitlink_backend = None
_nvjitlink_input_types = None
_driver_input_types = None

def _nvjitlink_has_version_symbol(nvjitlink) -> bool:
    ...

def _decide_nvjitlink_or_driver() -> bool:
    """Return True if falling back to the cuLink* driver APIs."""

def _lazy_init() -> None:
    ...