Coverage for cuda/core/_host.py: 100.00%

1# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. 

2# SPDX-License-Identifier: Apache-2.0 

3 

4from __future__ import annotations (empty)

5 

6import threading (empty)

7from typing import ClassVar (empty)

8 

9__all__ = ["Host"] (empty)

10 

11 

12class Host: (empty)

13 """Host (CPU) location for managed-memory operations. 

14 

15 Use one of the following forms: 

16 

17 * ``Host()`` — generic host (any NUMA node). 

18 * ``Host(numa_id=N)`` — specific NUMA node ``N``. 

19 * ``Host.numa_current()`` or ``Host(is_numa_current=True)`` — NUMA node 

20 of the calling thread. ``numa_id`` and ``is_numa_current`` are 

21 mutually exclusive. 

22 

23 ``Host`` is the symmetric counterpart of :class:`~cuda.core.Device` 

24 for managed-memory `prefetch`, `advise`, and `discard_prefetch` 

25 targets. Pass either a ``Device`` or a ``Host`` to those operations 

26 and to ``ManagedBuffer.preferred_location`` / ``accessed_by``. 

27 

28 ``Host`` is a singleton class, mirroring :class:`~cuda.core.Device`: 

29 constructor calls with the same arguments return the same instance, 

30 so ``Host() is Host()`` and ``Host(numa_id=1) is Host(numa_id=1)``. 

31 ``Host.numa_current()`` returns its own singleton, distinct from 

32 ``Host()`` because it represents a thread-relative location rather 

33 than a fixed one. 

34 """ 

35 

36 __slots__ = ("__weakref__", "_is_numa_current", "_numa_id") (empty)

37 

38 _numa_id: int | None (empty)

39 _is_numa_current: bool (empty)

40 

41 # Singleton cache keyed by (numa_id, is_numa_current). 

42 _instances: ClassVar[dict[tuple[int | None, bool], Host]] = {} (empty)

43 _instances_lock: ClassVar[threading.Lock] = threading.Lock() (empty)

44 

45 def __new__(cls, numa_id: int | None = None, *, is_numa_current: bool = False) -> Host: (empty)

46 if is_numa_current and numa_id is not None: 33 ctx1rstijkuefgnmpvwxyozCDEFAdlGBqHhcb

47 raise ValueError("numa_id and is_numa_current are mutually exclusive") 1 ctx1B

48 if numa_id is not None and (isinstance(numa_id, bool) or not isinstance(numa_id, int) or numa_id < 0): 33 ctx1rstijkuefgnmpvwxyozCDEFAdlGBqHhcb

49 raise ValueError(f"numa_id must be a non-negative int, got {numa_id!r}") 2 ctx1GH

50 return cls._get_or_create(numa_id, is_numa_current) 31 ctx1rstijkuefgnmpvwxyozCDEFAdlBqhcb

51 

52 @classmethod (empty)

53 def _get_or_create(cls, numa_id: int | None, is_numa_current: bool) -> Host: (empty)

54 key = (numa_id, is_numa_current) 31 ctx1rstijkuefgnmpvwxyozCDEFAdlBqhcb

55 cache = cls._instances 31 ctx1rstijkuefgnmpvwxyozCDEFAdlBqhcb

56 inst = cache.get(key) 31 ctx1rstijkuefgnmpvwxyozCDEFAdlBqhcb

57 if inst is not None: 31 ctx1rstijkuefgnmpvwxyozCDEFAdlBqhcb

58 return inst 28 ctx1rstuefgnmpvwxyozCDEFAdlBqhcb

59 with cls._instances_lock: 11 ctx1ijkefgdlhcb

60 inst = cache.get(key) 11 ctx1ijkefgdlhcb

61 if inst is None: 11 ctx1ijkefgdlhcb

62 inst = object.__new__(cls) 11 ctx1ijkefgdlhcb

63 inst._numa_id = numa_id 11 ctx1ijkefgdlhcb

64 inst._is_numa_current = is_numa_current 11 ctx1ijkefgdlhcb

65 cache[key] = inst 11 ctx1ijkefgdlhcb

66 return inst 11 ctx1ijkefgdlhcb

67 

68 @property (empty)

69 def numa_id(self) -> int | None: (empty)

70 """NUMA node ID, or ``None`` if not pinned to a specific NUMA node.""" 

71 return self._numa_id 20 ctx1stjkufgnmpvwxyozAqhb

72 

73 @property (empty)

74 def is_numa_current(self) -> bool: (empty)

75 """``True`` if this ``Host`` represents the calling thread's NUMA node (constructed via :meth:`numa_current`).""" 

76 return self._is_numa_current 22 ctx1rstijkuefgmpvwxyozAqhb

77 

78 @classmethod (empty)

79 def numa_current(cls) -> Host: (empty)

80 """Construct a ``Host`` referring to the calling thread's NUMA node.""" 

81 return cls(is_numa_current=True) 9 ctx1riepdBqcb

82 

83 def __eq__(self, other: object) -> bool: (empty)

84 if not isinstance(other, Host): 4 ctx1nmod

85 return NotImplemented 2 ctx1nm

86 return self is other 2 ctx1od

87 

88 def __hash__(self) -> int: (empty)

89 return hash((Host, self._numa_id, self._is_numa_current)) 3 ctx1nmd

90 

91 def __reduce__(self) -> tuple[object, ...]: (empty)

92 if self._is_numa_current: 1 ctx1c

93 return (_reconstruct_numa_current, ()) 1 ctx1c

94 return (Host, (self._numa_id,)) 1 ctx1c

95 

96 def __repr__(self) -> str: (empty)

97 if self.is_numa_current: 1 ctx1b

98 return "Host.numa_current()" 1 ctx1b

99 if self.numa_id is None: 1 ctx1b

100 return "Host()" 1 ctx1b

101 return f"Host(numa_id={self.numa_id})" 1 ctx1b

102 

103 

104def _reconstruct_numa_current() -> Host: (empty)

105 return Host.numa_current() 1 ctx1c