__init__.pyi

import asyncio
from types import FrameType
from typing import Optional
from typing import Sequence
from typing import Union

from ddtrace._trace import context
from ddtrace._trace import span as ddspan

# Core stack v2 functions
def start(min_interval: float = ...) -> bool: ...
def stop() -> None: ...
def is_origin_task_linking_enabled() -> bool: ...
def _native_call_registry_size() -> int: ...

# executor worker thread <-> originating asyncio task association
def link_origin_task(task_id: int, task_name: str) -> None: ...
def unlink_origin_task() -> None: ...

# Sampling configuration
def set_adaptive_sampling(do_adaptive_sampling: bool = False) -> None: ...
def set_target_overhead(target_overhead: float) -> None: ...
def set_max_sampling_period(max_interval_us: int) -> None: ...
def set_adaptive_sampling_baseline(baseline_core_pct: float) -> None: ...
def set_p_stable_window_s(p_stable_window_s: int) -> None: ...
def set_p_stable_percentile(p_stable_percentile: float) -> None: ...
def set_max_threads(max_threads: int) -> None: ...
def set_uvloop_mode(thread_id: int, uvloop_mode: bool) -> None:
    """Enable uvloop-specific stack unwinding in the native profiler for a specific thread.

    This changes the boundary frame detection from `Handle._run` to `Runner.run`,
    and skips the uvloop wrapper frame in task stacks.

    Args:
        thread_id: The Python thread ID (threading.current_thread().ident) to set uvloop mode for.
        uvloop_mode: Whether to enable uvloop mode for this thread.
    """
    ...

def set_interval(new_interval: float) -> None: ...

# Memory copy strategy
def set_fast_copy(enabled: bool) -> None: ...
def is_safe_copy_failed() -> bool: ...
def fast_copy_memory_active() -> bool: ...  # test introspection: is safe_memcpy active?

# _set_fast_copy_warmup_seconds is test-only; accessed via _stack (import * skips it).

def uninstall_segv_handler() -> None: ...
def reinstall_segv_handler() -> None:
    """Reinstall SIGSEGV/SIGBUS handlers after another component overwrites them.

    This is used to reclaim the signal handlers after faulthandler.enable() or
    similar overwrites them. Our handler chains to the previous one for non-recovery
    faults, so both systems coexist correctly.
    """
    ...

def segv_handler_installed() -> bool:
    """Return True if our handler is the installed disposition for SIGSEGV and SIGBUS.

    Primarily test introspection: it queries the live disposition via sigaction(2)
    for both signals on every call, so it is not free. Do not call it on hot paths.
    """
    ...

# Pause/resume sampling
def pause_sampling() -> bool | None:
    """Pause the sampling thread and wait for any in-flight sample to complete.

    Returns True  if the sampler was paused successfully.
    Returns False if the sampler was not running (nothing to pause).
    Returns None  if the sampler is running but timed out waiting for it to
                  reach a safe pause point; the caller must NOT swap signal
                  handlers in this case to avoid a race with safe_memcpy.
    """
    ...

def resume_sampling() -> None: ...

# span <-> profile association
def link_span(span: Optional[Union[context.Context, ddspan.Span]]) -> None: ...

# Thread management
def register_thread(python_thread_id: int, native_id: int, name: str) -> None: ...
def unregister_thread(python_thread_id: int) -> None: ...

# Asyncio support
def track_asyncio_loop(thread_id: int, loop: Optional[asyncio.AbstractEventLoop]) -> None: ...
def link_tasks(parent: asyncio.Task, child: asyncio.Future) -> None: ...
def weak_link_tasks(parent: asyncio.Task, child: asyncio.Future) -> None: ...
def init_asyncio(
    scheduled_tasks: Sequence[asyncio.Task],
    eager_tasks: Optional[Sequence[asyncio.Task]],
) -> None: ...

# Greenlet support
def track_greenlet(greenlet_id: int, name: str, frame: Union[FrameType, bool, None]) -> None: ...
def untrack_greenlet(greenlet_id: int) -> None: ...
def link_greenlets(greenlet_id: int, parent_id: int) -> None: ...
def record_greenlet_switch(
    origin_id: int,
    origin_frame: Union[FrameType, bool, None],
    target_id: int,
    target_frame: Union[FrameType, bool, None],
    update_target_frame: bool,
) -> None: ...

# Module attributes
is_available: bool
failure_msg: str