buffer

Define the canonical IRx buffer owner and buffer view contract that Arx may target without introducing a user-facing scientific array API.

Classes:

• BufferHandle –
• BufferIndexBoundsPolicy –
• BufferMutability –
• BufferOwnership –
• BufferViewMetadata –

Functions:

• buffer_dtype_handle –
• buffer_dtype_name –
• buffer_dtype_token –
• buffer_flags_include –
• buffer_view_flags –
• buffer_view_has_validity_bitmap –
• buffer_view_is_readonly –
• buffer_view_ownership –
• validate_buffer_view_metadata –

BufferHandle dataclass

BufferHandle(address: int | None = None)

Model a pointer-valued handle for semantic validation and deterministic lowering. None means the handle is statically null. attributes: address: type: int | None

Attributes:

• is_null (bool) –

is_null property

is_null: bool

BufferIndexBoundsPolicy

Bases: str, Enum

DEFAULT performs semantic static-bounds rejection when analysis can prove the bounds and emits no runtime bounds helper yet. CHECKED and UNCHECKED are reserved for future lowering modes.

BufferMutability

Bases: str, Enum

BufferOwnership

Bases: str, Enum

BufferViewMetadata dataclass

BufferViewMetadata(
    data: BufferHandle,
    owner: BufferHandle,
    dtype: BufferHandle,
    ndim: int,
    shape: tuple[int, ...],
    strides: tuple[int, ...],
    offset_bytes: int,
    flags: int,
)

Represents the semantic contents of the canonical IRx buffer view. This is not a scientific array object; it is a plain descriptor shape. attributes: data: type: BufferHandle owner: type: BufferHandle dtype: type: BufferHandle ndim: type: int shape: type: tuple[int, Ellipsis] strides: type: tuple[int, Ellipsis] offset_bytes: type: int flags: type: int

buffer_dtype_handle

buffer_dtype_handle(name: str) -> BufferHandle

Source code in src/irx/buffer.py

@public
@typechecked
def buffer_dtype_handle(name: str) -> BufferHandle:
    """
    title: Return one canonical primitive dtype token as a buffer handle.
    parameters:
      name:
        type: str
    returns:
      type: BufferHandle
    """
    return BufferHandle(buffer_dtype_token(name))

buffer_dtype_name

buffer_dtype_name(token: int) -> str

Source code in src/irx/buffer.py

@public
@typechecked
def buffer_dtype_name(token: int) -> str:
    """
    title: Return the canonical name for one primitive dtype token.
    parameters:
      token:
        type: int
    returns:
      type: str
    """
    try:
        return BUFFER_DTYPE_NAMES[token]
    except KeyError as exc:  # pragma: no cover - narrow guard
        raise ValueError(f"unknown buffer dtype token {token!r}") from exc

buffer_dtype_token

buffer_dtype_token(name: str) -> int

Source code in src/irx/buffer.py

@public
@typechecked
def buffer_dtype_token(name: str) -> int:
    """
    title: Return one canonical primitive dtype token.
    parameters:
      name:
        type: str
    returns:
      type: int
    """
    try:
        return BUFFER_DTYPE_TOKENS[name]
    except KeyError as exc:  # pragma: no cover - narrow guard
        raise ValueError(f"unknown buffer dtype token {name!r}") from exc

buffer_flags_include

buffer_flags_include(flags: int, flag: int) -> bool

Source code in src/irx/buffer.py

@public
@typechecked
def buffer_flags_include(flags: int, flag: int) -> bool:
    """
    title: Return whether one buffer flag is set.
    parameters:
      flags:
        type: int
      flag:
        type: int
    returns:
      type: bool
    """
    return (flags & flag) == flag

buffer_view_flags

buffer_view_flags(
    ownership: BufferOwnership,
    mutability: BufferMutability,
    *,
    c_contiguous: bool = False,
    f_contiguous: bool = False,
) -> int

Source code in src/irx/buffer.py

@public
@typechecked
def buffer_view_flags(
    ownership: BufferOwnership,
    mutability: BufferMutability,
    *,
    c_contiguous: bool = False,
    f_contiguous: bool = False,
) -> int:
    """
    title: Build canonical buffer view flags.
    parameters:
      ownership:
        type: BufferOwnership
      mutability:
        type: BufferMutability
      c_contiguous:
        type: bool
      f_contiguous:
        type: bool
    returns:
      type: int
    """
    flags = {
        BufferOwnership.BORROWED: BUFFER_FLAG_BORROWED,
        BufferOwnership.OWNED: BUFFER_FLAG_OWNED,
        BufferOwnership.EXTERNAL_OWNER: BUFFER_FLAG_EXTERNAL_OWNER,
    }[ownership]
    flags |= {
        BufferMutability.READONLY: BUFFER_FLAG_READONLY,
        BufferMutability.WRITABLE: BUFFER_FLAG_WRITABLE,
    }[mutability]
    if c_contiguous:
        flags |= BUFFER_FLAG_C_CONTIGUOUS
    if f_contiguous:
        flags |= BUFFER_FLAG_F_CONTIGUOUS
    return flags

buffer_view_has_validity_bitmap

buffer_view_has_validity_bitmap(flags: int) -> bool

This flag only says that the producer has separate validity metadata. It does not make generic buffer indexing null-aware. parameters: flags: type: int returns: type: bool

Source code in src/irx/buffer.py

@public
@typechecked
def buffer_view_has_validity_bitmap(flags: int) -> bool:
    """
    title: Return whether a buffer view advertises a validity sidecar.
    summary: >-
      This flag only says that the producer has separate validity metadata. It
      does not make generic buffer indexing null-aware.
    parameters:
      flags:
        type: int
    returns:
      type: bool
    """
    return buffer_flags_include(flags, BUFFER_FLAG_VALIDITY_BITMAP)

buffer_view_is_readonly

buffer_view_is_readonly(flags: int) -> bool

Source code in src/irx/buffer.py

@public
@typechecked
def buffer_view_is_readonly(flags: int) -> bool:
    """
    title: Return whether a buffer view is readonly.
    parameters:
      flags:
        type: int
    returns:
      type: bool
    """
    return buffer_flags_include(flags, BUFFER_FLAG_READONLY)

buffer_view_ownership

buffer_view_ownership(flags: int) -> BufferOwnership | None

Source code in src/irx/buffer.py

@public
@typechecked
def buffer_view_ownership(flags: int) -> BufferOwnership | None:
    """
    title: Return the explicit ownership state encoded in flags.
    parameters:
      flags:
        type: int
    returns:
      type: BufferOwnership | None
    """
    ownership = [
        flag
        for flag in BUFFER_OWNERSHIP_FLAGS
        if buffer_flags_include(flags, flag)
    ]
    if len(ownership) != 1:
        return None
    if ownership[0] == BUFFER_FLAG_BORROWED:
        return BufferOwnership.BORROWED
    if ownership[0] == BUFFER_FLAG_OWNED:
        return BufferOwnership.OWNED
    return BufferOwnership.EXTERNAL_OWNER

validate_buffer_view_metadata

validate_buffer_view_metadata(
    metadata: BufferViewMetadata,
) -> tuple[str, ...]

Source code in src/irx/buffer.py

@public
@typechecked
def validate_buffer_view_metadata(
    metadata: BufferViewMetadata,
) -> tuple[str, ...]:
    """
    title: Validate static buffer view metadata.
    parameters:
      metadata:
        type: BufferViewMetadata
    returns:
      type: tuple[str, Ellipsis]
    """
    errors: list[str] = []

    ownership = [
        flag
        for flag in BUFFER_OWNERSHIP_FLAGS
        if buffer_flags_include(metadata.flags, flag)
    ]
    if len(ownership) != 1:
        errors.append(
            "buffer view must set exactly one ownership flag: "
            "borrowed, owned, or external_owner"
        )
    elif ownership[0] == BUFFER_FLAG_BORROWED and not metadata.owner.is_null:
        errors.append("borrowed buffer views must use a null owner handle")
    elif (
        ownership[0]
        in {
            BUFFER_FLAG_OWNED,
            BUFFER_FLAG_EXTERNAL_OWNER,
        }
        and metadata.owner.is_null
    ):
        errors.append("owned buffer views must use a non-null owner handle")

    mutability = [
        flag
        for flag in BUFFER_MUTABILITY_FLAGS
        if buffer_flags_include(metadata.flags, flag)
    ]
    if len(mutability) != 1:
        errors.append(
            "buffer view must set exactly one mutability flag: "
            "readonly or writable"
        )

    if metadata.ndim < 0:
        errors.append("buffer view ndim must be non-negative")
    if len(metadata.shape) != metadata.ndim:
        errors.append("buffer view shape length must match ndim")
    if len(metadata.strides) != metadata.ndim:
        errors.append("buffer view strides length must match ndim")
    if any(dim < 0 for dim in metadata.shape):
        errors.append("buffer view shape dimensions must be non-negative")
    if metadata.offset_bytes < 0:
        errors.append("buffer view offset_bytes must be non-negative")
    if metadata.dtype.is_null:
        errors.append("buffer view dtype handle must be non-null")

    extent = 1
    for dim in metadata.shape:
        extent *= dim
    if extent > 0 and metadata.data.is_null:
        errors.append("buffer view with nonzero extent must use non-null data")

    return tuple(errors)