cocotb 1.9.2__cp312-cp312-win32.whl → 2.0.0rc2__cp312-cp312-win32.whl

cocotb/handle.py

@@ -1,48 +1,71 @@
-#!/usr/bin/env python
-
+# Copyright cocotb contributors
 # Copyright (c) 2013 Potential Ventures Ltd
 # Copyright (c) 2013 SolarFlare Communications Inc
-# All rights reserved.
-#
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
-#     * Redistributions of source code must retain the above copyright
-#       notice, this list of conditions and the following disclaimer.
-#     * Redistributions in binary form must reproduce the above copyright
-#       notice, this list of conditions and the following disclaimer in the
-#       documentation and/or other materials provided with the distribution.
-#     * Neither the name of Potential Ventures Ltd,
-#       SolarFlare Communications Inc nor the
-#       names of its contributors may be used to endorse or promote products
-#       derived from this software without specific prior written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
-# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-# DISCLAIMED. IN NO EVENT SHALL POTENTIAL VENTURES LTD BE LIABLE FOR ANY
-# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
-# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-# -*- coding: utf-8 -*-
-
-import ctypes
+# Licensed under the Revised BSD License, see LICENSE for details.
+# SPDX-License-Identifier: BSD-3-Clause
+
 import enum
-import warnings
+import logging
+import os
+import re
+from abc import ABC, abstractmethod
 from functools import lru_cache
-from typing import Optional
+from logging import Logger
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Generic,
+    Iterable,
+    Iterator,
+    NoReturn,
+    Optional,
+    Sequence,
+    Tuple,
+    Type,
+    TypeVar,
+    Union,
+    cast,
+)
 
 import cocotb
 from cocotb import simulator
-from cocotb.binary import BinaryRepresentation, BinaryValue
-from cocotb.log import SimLog
-from cocotb.types import Logic, LogicArray
-
-# Only issue a warning for each deprecated attribute access
-_deprecation_warned = set()
+from cocotb._base_triggers import Event
+from cocotb._deprecation import deprecated
+from cocotb._gpi_triggers import (
+    Edge,
+    FallingEdge,
+    ReadOnly,
+    ReadWrite,
+    RisingEdge,
+    ValueChange,
+    current_gpi_trigger,
+)
+from cocotb._py_compat import cached_property, insertion_ordered_dict
+from cocotb._utils import DocIntEnum
+from cocotb.task import Task
+from cocotb.types import Array, Logic, LogicArray, Range
+from cocotb.types._indexing import do_indexing_changed_warning, indexing_changed
+
+__all__ = (
+    "ArrayObject",
+    "Deposit",
+    "EnumObject",
+    "Force",
+    "Freeze",
+    "GPIDiscovery",
+    "HierarchyArrayObject",
+    "HierarchyObject",
+    "Immediate",
+    "IntegerObject",
+    "LogicArrayObject",
+    "LogicObject",
+    "RealObject",
+    "Release",
+    "SimHandleBase",
+    "StringObject",
+    "ValueObjectBase",
+)
 
 
 class _Limits(enum.IntEnum):
@@ -52,7 +75,7 @@ class _Limits(enum.IntEnum):
 
 
 @lru_cache(maxsize=None)
-def _value_limits(n_bits, limits):
+def _value_limits(n_bits: int, limits: _Limits) -> Tuple[int, int]:
     """Calculate min/max for given number of bits and limits class"""
     if limits == _Limits.SIGNED_NBIT:
         min_val = -(2 ** (n_bits - 1))
@@ -67,58 +90,52 @@ def _value_limits(n_bits, limits):
     return min_val, max_val
 
 
-class SimHandleBase:
+class SimHandleBase(ABC):
     """Base class for all simulation objects.
 
-    We maintain a handle which we can use for GPI calls.
+    All simulation objects are hashable and equatable by identity.
+
+    .. code-block:: python
+
+        a = dut.clk
+        b = dut.clk
+        assert a == b
+
+    .. versionchanged:: 2.0
+        ``get_definition_name()`` and ``get_definition_file()`` were removed in favor of :meth:`_def_name` and :meth:`_def_file`, respectively.
     """
 
-    # For backwards compatibility we support a mapping of old member names
-    # which may alias with the simulator hierarchy.  In these cases the
-    # simulator result takes priority, only falling back to the python member
-    # if there is no colliding object in the elaborated design.
-    _compat_mapping = {
-        "log": "_log",
-        "fullname": "_fullname",
-        "name": "_name",
-    }
-
-    def __init__(self, handle, path):
-        """
-        .. Constructor. This RST comment works around sphinx-doc/sphinx#6885
+    @abstractmethod
+    def __init__(self, handle: simulator.gpi_sim_hdl, path: Optional[str]) -> None:
+        self._handle = handle
+        self._path: str = self._name if path is None else path
+        """The path to this handle, or its name if this is the root handle.
 
-        Args:
-            handle (int): The GPI handle to the simulator object.
-            path (str): Path to this handle, ``None`` if root.
+        :meta public:
         """
-        self._handle = handle
-        self._len: Optional[int] = None
-        """The "length" (the number of elements) of the underlying object. For vectors this is the number of bits."""
-        self._sub_handles: dict = {}
-        """Dictionary of this handle's children."""
-        self._invalid_sub_handles: set = set()
-        """Python :class:`set` of invalid queries, for caching purposes."""
-        self._name: str = self._handle.get_name_string()
+
+    @cached_property
+    def _name(self) -> str:
         """The name of an object.
 
         :meta public:
         """
-        self._type: str = self._handle.get_type_string()
+        return self._handle.get_name_string()
+
+    @cached_property
+    def _type(self) -> str:
         """The type of an object as a string.
 
         :meta public:
         """
-        self._fullname: str = self._name + "(%s)" % self._type
-        """The name of an object with its type appended in parentheses."""
-        self._path: str = self._name if path is None else path
-        """The path to this handle, or its name if this is the root handle.
+        return self._handle.get_type_string()
 
-        :meta public:
-        """
-        self._log = SimLog("cocotb.%s" % self._name)
-        """The logging object."""
-        self._log.debug("Created")
-        self._def_name: str = self._handle.get_definition_name()
+    @cached_property
+    def _log(self) -> Logger:
+        return logging.getLogger(f"cocotb.{self._name}")
+
+    @cached_property
+    def _def_name(self) -> str:
         """The name of a GPI object's definition.
 
         This is the value of ``vpiDefName`` for VPI, ``vhpiNameP`` for VHPI,
@@ -127,7 +144,10 @@ class SimHandleBase:
 
         :meta public:
         """
-        self._def_file: str = self._handle.get_definition_file()
+        return self._handle.get_definition_name()
+
+    @cached_property
+    def _def_file(self) -> str:
         """The name of the file that sources the object's definition.
 
         This is the value of ``vpiDefFile`` for VPI, ``vhpiFileNameP`` for VHPI,
@@ -136,43 +156,17 @@ class SimHandleBase:
 
         :meta public:
         """
+        return self._handle.get_definition_file()
 
-    def get_definition_name(self):
-        return self._def_name
-
-    def get_definition_file(self):
-        return self._def_file
-
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash(self._handle)
 
-    def __len__(self):
-        """Return the "length" (the number of elements) of the underlying object.
-
-        For vectors this is the number of bits.
-        """
-        if self._len is None:
-            self._len = self._handle.get_num_elems()
-        return self._len
-
-    def __eq__(self, other):
-        """Compare equality of handles.
-
-        Example usage::
-
-            if clk == dut.clk:
-                do_something()
-        """
+    def __eq__(self, other: object) -> bool:
         if not isinstance(other, SimHandleBase):
             return NotImplemented
         return self._handle == other._handle
 
-    def __ne__(self, other):
-        if not isinstance(other, SimHandleBase):
-            return NotImplemented
-        return self._handle != other._handle
-
-    def __repr__(self):
+    def __repr__(self) -> str:
         desc = self._path
         defname = self._def_name
         if defname:
@@ -182,78 +176,104 @@ class SimHandleBase:
                 desc += " (at " + deffile + ")"
         return type(self).__qualname__ + "(" + desc + ")"
 
-    def __str__(self):
-        return self._path
-
-    def __setattr__(self, name, value):
-        if name in self._compat_mapping:
-            if name not in _deprecation_warned:
-                warnings.warn(
-                    "Use of attribute {!r} is deprecated, use {!r} instead".format(
-                        name, self._compat_mapping[name]
-                    ),
-                    DeprecationWarning,
-                    stacklevel=3,
-                )
-                _deprecation_warned.add(name)
-            return setattr(self, self._compat_mapping[name], value)
-        else:
-            return object.__setattr__(self, name, value)
+    def __bool__(self) -> NoReturn:
+        raise TypeError(
+            "This object cannot be cast to bool or used in conditionals. Use `obj is not None` check in conditionals."
+        )
 
-    def __getattr__(self, name):
-        if name in self._compat_mapping:
-            if name not in _deprecation_warned:
-                warnings.warn(
-                    "Use of attribute {!r} is deprecated, use {!r} instead".format(
-                        name, self._compat_mapping[name]
-                    ),
-                    DeprecationWarning,
-                    stacklevel=3,
-                )
-                _deprecation_warned.add(name)
-            return getattr(self, self._compat_mapping[name])
-        else:
-            return object.__getattribute__(self, name)
 
+class _RangeableObjectMixin(SimHandleBase):
+    """Base class for simulation objects that have a range."""
+
+    @cached_property
+    def range(self) -> Range:
+        """Return a :class:`~cocotb.types.Range` over the indexes of the array/vector."""
+        left, right, direction = self._handle.get_range()
+        if direction == simulator.RANGE_NO_DIR:
+            raise RuntimeError("Expected range to have a direction but got none!")
+        return Range(left, "to" if direction == simulator.RANGE_UP else "downto", right)
+
+    @property
+    def left(self) -> int:
+        """Return the leftmost index in the array/vector."""
+        return self.range.left
+
+    @property
+    def direction(self) -> str:
+        """Return the direction (``"to"``/``"downto"``) of indexes in the array/vector."""
+        return self.range.direction
+
+    @property
+    def right(self) -> int:
+        """Return the rightmost index in the array/vector."""
+        return self.range.right
+
+    def __len__(self) -> int:
+        return len(self.range)
+
+
+#: Type of keys (name or index) in HierarchyObjectBase.
+KeyType = TypeVar("KeyType")
+
+#: Subtype of :class:`SimHandleBase` returned when iterating or indexing a :class:`HierarchyArrayObject`.
+HierarchyChildObjectT = TypeVar("HierarchyChildObjectT", bound=SimHandleBase)
 
-class RegionObject(SimHandleBase):
-    """A region object, such as a scope or namespace.
 
-    Region objects don't have values, they are effectively scopes or namespaces.
+class GPIDiscovery(DocIntEnum):
+    """Simulator object discovery strategy."""
+
+    AUTO = (0, "Automatic discovery using all registered interfaces.")
+    NATIVE = (1, "Native discovery using only the parent's native interface.")
+
+
+class _HierarchyObjectBase(SimHandleBase, Generic[KeyType]):
+    """Base class for hierarchical simulation objects.
+
+    Hierarchical objects don't have values, they are just scopes/namespaces of other objects.
+    This includes array-like hierarchical structures like "generate loops"
+    and named hierarchical structures like "generate blocks" or "module"/"entity" instantiations.
+
+    This base class defines logic to discover, cache, and inspect child objects.
+    It provides a :class:`dict`-like interface for doing so.
+
+    :meth:`_keys`, :meth:`_values`, and :meth:`_items` mimic their :class:`dict` counterparts.
+    You can also iterate over an object, which returns child objects, not keys like in :class:`dict`;
+    and can check the :func:`len`.
+
+    See :class:`HierarchyObject` and :class:`HierarchyArrayObject` for examples.
     """
 
-    def __init__(self, handle, path):
-        SimHandleBase.__init__(self, handle, path)
-        self._discovered = False  # True if this object has already been discovered
-
-    def __iter__(self):
-        """Iterate over all known objects in this layer of hierarchy."""
-        if not self._discovered:
-            self._discover_all()
-
-        for name, handle in self._sub_handles.items():
-            if isinstance(handle, list):
-                self._log.debug("Found index list length %d", len(handle))
-                for subindex, subhdl in enumerate(handle):
-                    if subhdl is None:
-                        self._log.warning(
-                            "Index %d doesn't exist in %s.%s",
-                            subindex,
-                            self._name,
-                            name,
-                        )
-                        continue
-                    self._log.debug(
-                        "Yielding index %d from %s (%s)", subindex, name, type(subhdl)
-                    )
-                    yield subhdl
-            else:
-                self._log.debug(
-                    "Yielding %s of type %s (%s)", name, type(handle), handle._path
-                )
-                yield handle
+    @abstractmethod
+    def __init__(self, handle: simulator.gpi_sim_hdl, path: Optional[str]) -> None:
+        super().__init__(handle, path)
+        self._sub_handles: Dict[KeyType, SimHandleBase] = {}
+        self._discovered = False
+
+    def _keys(self) -> Iterable[KeyType]:
+        """Iterate over the keys (name or index) of the child objects.
+
+        :meta public:
+        """
+        self._discover_all()
+        return self._sub_handles.keys()
+
+    def _values(self) -> Iterable[SimHandleBase]:
+        """Iterate over the child objects.
+
+        :meta public:
+        """
+        self._discover_all()
+        return self._sub_handles.values()
+
+    def _items(self) -> Iterable[Tuple[KeyType, SimHandleBase]]:
+        """Iterate over ``(key, object)`` tuples of child objects.
+
+        :meta public:
+        """
+        self._discover_all()
+        return self._sub_handles.items()
 
-    def _discover_all(self):
+    def _discover_all(self) -> None:
         """When iterating or performing IPython tab completion, we run through ahead of
         time and discover all possible children, populating the :any:`_sub_handles`
         mapping. Hierarchy can't change after elaboration so we only have to
@@ -261,914 +281,1471 @@ class RegionObject(SimHandleBase):
         """
         if self._discovered:
             return
-        self._log.debug("Discovering all on %s", self._name)
+
         for thing in self._handle.iterate(simulator.OBJECTS):
             name = thing.get_name_string()
-            path = self._child_path(name)
-            try:
-                hdl = SimHandle(thing, path)
-            except NotImplementedError as e:
-                self._log.debug("%s", e)
-                continue
 
+            # translate HDL name into a consistent key name
             try:
                 key = self._sub_handle_key(name)
             except ValueError:
-                self._log.debug(
+                self._log.exception(
                     "Unable to translate handle >%s< to a valid _sub_handle key",
-                    hdl._name,
+                    name,
                 )
                 continue
 
+            # compute a full path using the key name
+            path = self._child_path(key)
+
+            # attempt to create the child object
+            try:
+                hdl = _make_sim_object(thing, path)
+            except NotImplementedError:
+                self._log.exception(
+                    "Unable to construct a SimHandle object for %s", path
+                )
+                continue
+
+            # add to cache
             self._sub_handles[key] = hdl
 
         self._discovered = True
 
-    def _child_path(self, name) -> str:
-        """Return a string of the path of the child :any:`SimHandle` for a given *name*."""
-        return self._path + "." + name
+    def _get(
+        self, key: KeyType, discovery_method: GPIDiscovery = GPIDiscovery.AUTO
+    ) -> Union[SimHandleBase, None]:
+        """Query the simulator for an object with the specified *key*.
 
-    def _sub_handle_key(self, name):
-        """Translate the handle name to a key to use in :any:`_sub_handles` dictionary."""
-        return name.split(".")[-1]
+        Like Python's native dictionary ``get``-function, this returns ``None`` if the object
+        is not found instead of raising an :exc:`AttributeError`.
 
-    def __dir__(self):
-        """Permits IPython tab completion to work."""
-        self._discover_all()
-        return super().__dir__() + [str(k) for k in self._sub_handles]
+        Generally, use the ``handle[child_name]`` syntax instead, unless you have to change the
+        *discovery_method* or want to check for optional signals.
 
+        :meta public:
 
-class HierarchyObject(RegionObject):
-    """Hierarchy objects are namespace/scope objects."""
+        Args:
+            key: The child object by name.
+            discovery_method: Optional selection of discovery strategy. :data:`~cocotb.handle.GPIDiscovery.AUTO` by default.
 
-    def __get_sub_handle_by_name(self, name):
+        Returns:
+            The child object, or ``None`` if not found.
+        """
+        # try to use cached value
         try:
-            return self._sub_handles[name]
+            return self._sub_handles[key]
         except KeyError:
             pass
 
-        # Cache to avoid a call to the simulator if we already know the name is
-        # invalid. Unclear if we care, but we had this before.
-        if name in self._invalid_sub_handles:
+        # try to get value from GPI
+        new_handle = self._get_handle_by_key(key, discovery_method)
+        if new_handle is None:
             return None
 
-        new_handle = self._handle.get_handle_by_name(name)
-
-        if not new_handle:
-            self._invalid_sub_handles.add(name)
-            return None
+        # if successful, construct and cache
+        sub_handle = _make_sim_object(new_handle, self._child_path(key))
+        self._sub_handles[key] = sub_handle
 
-        sub_handle = SimHandle(new_handle, self._child_path(name))
-        self._sub_handles[name] = sub_handle
         return sub_handle
 
-    def __setattr__(self, name, value):
-        """Provide transparent access to signals via the hierarchy.
+    @abstractmethod
+    def _get_handle_by_key(
+        self, key: KeyType, discovery_method: GPIDiscovery
+    ) -> Union[simulator.gpi_sim_hdl, None]:
+        """Get child object by key from the simulator.
 
-        Slightly hacky version of operator overloading in Python.
+        Args:
+            key: The key of the child object.
+            discovery_method: How to discover the object using the GPI.
 
-        Raise an :exc:`AttributeError` if users attempt to create new members which
-        don't exist in the design.
+        Returns:
+            A raw simulator handle for the child object at the given key, or ``None``.
         """
 
-        # private attributes pass through directly
-        if name.startswith("_"):
-            return SimHandleBase.__setattr__(self, name, value)
-
-        # then try handles
-        sub = self.__get_sub_handle_by_name(name)
-        if sub is not None:
-            warnings.warn(
-                "Setting values on handles using the ``dut.handle = value`` syntax is deprecated. "
-                "Instead use the ``handle.value = value`` syntax",
-                DeprecationWarning,
-                stacklevel=2,
-            )
-            sub.value = value
-            return
+    @abstractmethod
+    def _child_path(self, key: KeyType) -> str:
+        """Compute the path string of a child object at the given key.
 
-        # compat behavior
-        if name in self._compat_mapping:
-            return SimHandleBase.__setattr__(self, name, value)
+        Args:
+            key: The key of the child object.
+
+        Returns:
+            A path string of the child object at the a given key.
+        """
+
+    @abstractmethod
+    def _sub_handle_key(self, name: str) -> KeyType:
+        """Translate a discovered child object name into a key.
+
+        Args:
+            name: The GPI name of the child object.
 
-        raise AttributeError(f"{self._name} contains no object named {name}")
+        Returns:
+            A unique key for the child object.
 
-    def __getattr__(self, name):
-        """Query the simulator for an object with the specified name
-        and cache the result to build a tree of objects.
+        Raises:
+            ValueError: if unable to translate handle to a valid _sub_handle key.
         """
+
+    def __iter__(self) -> Iterator[SimHandleBase]:
+        return iter(self._values())
+
+    def __len__(self) -> int:
+        self._discover_all()
+        return len(self._sub_handles)
+
+    def __dir__(self) -> Iterable[str]:
+        """Permits IPython tab completion and debuggers to work."""
+        self._discover_all()
+        return set(super().__dir__()) | {str(k) for k in self._keys()}
+
+
+class HierarchyObject(_HierarchyObjectBase[str]):
+    r"""A simulation object that is a name-indexed collection of hierarchical simulation objects.
+
+    Inherits from :class:`SimHandleBase`.
+
+    This class is used for named hierarchical structures, such as "generate blocks" or "module"/"entity" instantiations.
+
+    Children under this structure are found by using the name of the child with either the attribute syntax or index syntax.
+    For example, if in your :envvar:`COCOTB_TOPLEVEL` entity/module you have a signal/net named ``count``, you could do either of the following.
+
+    .. code-block:: python
+
+        dut.count  # attribute syntax
+        dut["count"]  # index syntax
+
+    Attribute syntax is usually shorter and easier to read, and is more common.
+    However, it has limitations:
+
+    - the name cannot start with a number
+    - the name cannot start with a ``_`` character
+    - the name can only contain ASCII letters, numbers, and the ``_`` character.
+
+    Any possible name of an object is supported with the index syntax,
+    but it can be more verbose.
+
+    Accessing a non-existent child with attribute syntax results in an :class:`AttributeError`,
+    and accessing a non-existent child with index syntax results in a :class:`KeyError`.
+
+    .. note::
+        If you need to access signals/nets that start with ``_``,
+        or use escaped identifier (Verilog) or extended identifier (VHDL) characters,
+        you have to use the index syntax.
+        Accessing escaped/extended identifiers requires enclosing the name
+        with leading and trailing double backslashes (``\\``).
+
+        .. code-block:: python
+
+            dut["_underscore_signal"]
+            dut["\\%extended !ID\\"]
+
+    Iteration yields all child objects in no particular order.
+    The :func:`len` function can be used to find the number of children.
+
+    .. code-block:: python
+
+        # discover all children in 'some_module'
+        total = 0
+        for handle in dut.some_module:
+            cocotb.log("Found %r", handle._path)
+            total += 1
+
+        # make sure we found them all
+        assert len(dut.some_module) == total
+    """
+
+    def __init__(self, handle: simulator.gpi_sim_hdl, path: Optional[str]) -> None:
+        super().__init__(handle, path)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        # private attributes pass through directly
         if name.startswith("_"):
-            return SimHandleBase.__getattr__(self, name)
+            return object.__setattr__(self, name, value)
 
-        handle = self.__get_sub_handle_by_name(name)
-        if handle is not None:
-            return handle
+        try:
+            getattr(self, name)
+        except AttributeError:
+            raise AttributeError(
+                f"Cannot set attribute {name!r} on simulation object {self._path}. No such object exists."
+            ) from None
+        else:
+            raise AttributeError(
+                f"Cannot set attribute {name!r} on simulation object {self._path}. Did you forget to add `.value`?"
+            )
 
-        if name in self._compat_mapping:
-            return SimHandleBase.__getattr__(self, name)
+    def __getattr__(self, name: str) -> SimHandleBase:
+        if name.startswith("_"):
+            return object.__getattribute__(self, name)
+
+        handle = self._get(name)
+        if handle is None:
+            raise AttributeError(f"{self._path} contains no child object named {name}")
+        return handle
 
-        raise AttributeError(f"{self._name} contains no object named {name}")
+    def __getitem__(self, key: str) -> SimHandleBase:
+        handle = self._get(key)
+        if handle is None:
+            raise KeyError(f"{self._path} contains no child object named {key}")
+        return handle
 
-    def _id(self, name, extended: bool = True):
-        """Query the simulator for an object with the specified *name*,
-        and cache the result to build a tree of objects.
+    @deprecated(
+        "Use `handle[child_name]` syntax instead. If extended identifiers are needed simply add a '\\' character before and after the name."
+    )
+    def _id(self, name: str, extended: bool = True) -> SimHandleBase:
+        """Query the simulator for an object with the specified *name*.
 
         If *extended* is ``True``, run the query only for VHDL extended identifiers.
         For Verilog, only ``extended=False`` is supported.
 
         :meta public:
+
+        Args:
+            name: The child object by name.
+            extended: If ``True``, treat the *name* as an extended identifier.
+
+        Returns:
+            The child object.
+
+        Raises:
+            AttributeError: If the child object is not found.
+
+        .. deprecated:: 2.0
+            Use ``handle[child_name]`` syntax instead.
+            If extended identifiers are needed simply add a ``\\`` character before and after the name.
+
         """
         if extended:
             name = "\\" + name + "\\"
 
-        handle = self.__get_sub_handle_by_name(name)
-        if handle is not None:
-            return handle
+        handle = self._get(name)
+        if handle is None:
+            raise AttributeError(f"{self._path} contains no child object named {name}")
+        return handle
+
+    def _child_path(self, key: str) -> str:
+        delimiter = "::" if self._type == "GPI_PACKAGE" else "."
+        return f"{self._path}{delimiter}{key}"
+
+    def _sub_handle_key(self, name: str) -> str:
+        return name
+
+    def _get_handle_by_key(
+        self, key: str, discovery_method: GPIDiscovery
+    ) -> Union[simulator.gpi_sim_hdl, None]:
+        return self._handle.get_handle_by_name(key, discovery_method)
+
+
+class HierarchyArrayObject(
+    _HierarchyObjectBase[int], _RangeableObjectMixin, Generic[HierarchyChildObjectT]
+):
+    """A simulation object that is an array of hierarchical simulation objects.
+
+    Inherits from :class:`SimHandleBase`.
+
+    This class is used for array-like hierarchical structures like "generate loops".
+
+    Children of this object are found by supplying a numerical index using index syntax.
+    For example, if you have a design with a generate loop ``gen_pipe_stages`` from the range ``0`` to ``7``:
+
+    .. code-block:: python
+
+        block_0 = dut.gen_pipe_stages[0]
+        block_7 = dut.gen_pipe_stages[7]
 
-        raise AttributeError(f"{self._name} contains no object named {name}")
+    Accessing a non-existent child results in an :class:`IndexError`.
 
+    Iteration yields all child objects in order.
 
-class HierarchyArrayObject(RegionObject):
-    """Hierarchy Arrays are containers of Hierarchy Objects."""
+    .. code-block:: python
 
-    def _sub_handle_key(self, name):
-        """Translate the handle name to a key to use in :any:`_sub_handles` dictionary."""
+        # set all 'reg's in each pipe stage to 0
+        for pipe_stage in dut.gen_pipe_stages:
+            pipe_stage.reg.value = 0
+
+    Use the :meth:`range` property if you want to iterate over the indexes.
+    The :func:`len` function can be used to find the number of elements.
+
+    .. code-block:: python
+
+        # set all 'reg's in each pipe stage to 0
+        for idx in dut.gen_pipe_stages.range:
+            dut.gen_pipe_stages[idx].reg.value = 0
+
+        # make sure we have all the pipe stages
+        assert len(dut.gen_pipe_stage) == len(dut.gen_pipe_stages.range)
+    """
+
+    def __init__(self, handle: simulator.gpi_sim_hdl, path: Optional[str]) -> None:
+        super().__init__(handle, path)
+
+    def _sub_handle_key(self, name: str) -> int:
         # This is slightly hacky, but we need to extract the index from the name
         # See also GEN_IDX_SEP_* in VhpiImpl.h for the VHPI separators.
         #
         # FLI and VHPI:       _name(X) where X is the index
         # VHPI(ALDEC):        _name__X where X is the index
         # VPI:                _name[X] where X is the index
-        import re
-
-        result = re.match(rf"{self._name}__(?P<index>\d+)$", name)
+        result = re.match(rf"{re.escape(self._name)}__(?P<index>\d+)$", name)
         if not result:
-            result = re.match(rf"{self._name}\((?P<index>\d+)\)$", name, re.IGNORECASE)
+            result = re.match(
+                rf"{re.escape(self._name)}\((?P<index>\d+)\)$", name, re.IGNORECASE
+            )
         if not result:
-            result = re.match(rf"{self._name}\[(?P<index>\d+)\]$", name)
+            result = re.match(rf"{re.escape(self._name)}\[(?P<index>\d+)\]$", name)
 
         if result:
             return int(result.group("index"))
         else:
             raise ValueError(f"Unable to match an index pattern: {name}")
 
-    def __len__(self):
-        """Return the "length" of the generate block."""
-        if self._len is None:
-            if not self._discovered:
-                self._discover_all()
+    def _child_path(self, key: int) -> str:
+        return f"{self._path}[{key}]"
 
-            self._len = len(self._sub_handles)
-        return self._len
+    def _get_handle_by_key(
+        self, key: int, discovery_method: GPIDiscovery
+    ) -> Union[simulator.gpi_sim_hdl, None]:
+        if discovery_method is not GPIDiscovery.AUTO:
+            raise NotImplementedError(
+                f"Only GPIDiscovery.AUTO is supported for {type(self).__qualname__} right now"
+            )
+        return self._handle.get_handle_by_index(key)
 
-    def __getitem__(self, index):
-        if isinstance(index, slice):
-            raise IndexError("Slice indexing is not supported")
-        if index in self._sub_handles:
-            return self._sub_handles[index]
-        new_handle = self._handle.get_handle_by_index(index)
-        if not new_handle:
-            raise IndexError("%s contains no object at index %d" % (self._name, index))
-        path = self._path + "[" + str(index) + "]"
-        self._sub_handles[index] = SimHandle(new_handle, path)
-        return self._sub_handles[index]
+    def __getitem__(self, key: int) -> HierarchyChildObjectT:
+        if isinstance(key, slice):
+            raise TypeError("Slice indexing is not supported")
+
+        handle = self._get(key)
+        if handle is None:
+            raise IndexError(f"{self._path} contains no child object at index {key}")
+        return cast("HierarchyChildObjectT", handle)
+
+    # ideally `__len__` could be implemented in terms of `range`, but `range` doesn't work universally.
 
-    def _child_path(self, name):
-        """Return a string of the path of the child :any:`SimHandle` for a given name."""
-        index = self._sub_handle_key(name)
-        return self._path + "[" + str(index) + "]"
+    def __iter__(self) -> Iterator[HierarchyChildObjectT]:
+        # must use `sorted(self._keys())` instead of the range because `range` doesn't work universally.
+        for i in sorted(self._keys()):
+            yield self[i]
 
-    def __setitem__(self, index, value):
-        raise TypeError("Not permissible to set %s at index %d" % (self._name, index))
 
+class _GPISetAction(enum.Enum):
+    DEPOSIT = 0
+    FORCE = 1
+    RELEASE = 2
+    NO_DELAY = 3
+    OLD_IMMEDIATE = 0
 
-class _AssignmentResult:
+
+_ValueT = TypeVar("_ValueT")
+
+
+class Deposit(Generic[_ValueT]):
+    r""":term:`Inertially deposit <inertial deposit>` the given value on a simulator object.
+
+    If another :term:`deposit` comes after this deposit, the newer deposit overwrites the old value.
+    If an HDL process is :term:`driving` the signal/net/register where a deposit from cocotb is made,
+    the deposited value will be overwritten at the end of the next delta cycle,
+    essentially causing a single delta cycle "glitch" in the waveform.
+
+    .. note::
+        VHDL applies writes according to their definition.
+        ``signal`` writes are set inertially, regardless of using this class;
+        while ``variable`` writes are set immediately, regardless of using this class.
     """
-    An object that exists solely to provide an error message if the caller
-    is not aware of cocotb's meaning of ``<=``.
+
+    def __init__(self, value: _ValueT) -> None:
+        self.value = value
+
+
+class Force(Generic[_ValueT]):
+    r""":term:`Force <force>` the given value on a simulator object immediately.
+
+    Further :term:`deposits <deposit>` from cocotb or :term:`drives <driving>` from HDL processes
+    do not cause the value to change until the handle is :term:`released <release>` by cocotb or HDL code.
+    Further :term:`forces <force>` will overwrite the value and leave the value forced.
+
+    .. note::
+        VHDL applies writes according to their definition.
+        ``signal`` writes are set inertially, regardless of using this class;
+        while ``variable`` writes are set immediately, regardless of using this class.
+
+    .. note::
+        Verilog :class:`!Force`\ s are always immediate.
+        This also means that if there are multiple cocotb Tasks or multiple ``always`` blocks writing to the same object,
+        the resulting value is non-deterministic.
+
+    .. note::
+        Issuing a :class:`!Force` and :class:`Release` in the same evaluation cycle in VHDL will result in the :class:`!Force` "winning".
     """
 
-    def __init__(self, signal, value):
-        self._signal = signal
-        self._value = value
+    def __init__(self, value: _ValueT) -> None:
+        self.value = value
 
-    def __bool__(self):
-        raise TypeError(
-            "Attempted to use `{0._signal!r} <= {0._value!r}` (a cocotb "
-            "delayed write) as if it were a numeric comparison. To perform "
-            "comparison, use `{0._signal!r}.value <= {0._value!r}` instead.".format(
-                self
-            )
-        )
 
+class Freeze:
+    r""":term:`Force <force>` the simulator object with its current value.
 
-class NonHierarchyObject(SimHandleBase):
-    """Common base class for all non-hierarchy objects."""
+    Useful if you have done a :term:`deposit` and later decide to lock the value from changing.
+    Does not change the current value of the simulation object.
+    See :class:`Force` for information on behavior after this write completes.
 
-    def __iter__(self):
-        return iter(())
+    .. note::
+        VHDL applies writes according to their definition.
+        ``signal`` writes are set inertially, regardless of using this class;
+        while ``variable`` writes are set immediately, regardless of using this class.
 
-    @property
-    def value(self):
-        """The value of this simulation object.
+    .. note::
+        Verilog :class:`Force`\ s are always immediate.
+        This also means that if there are multiple cocotb Tasks or multiple ``always`` blocks writing to the same object,
+        the resulting value is non-deterministic.
 
-        .. note::
-            When setting this property, the value is stored by the :class:`~cocotb.scheduler.Scheduler`
-            and all stored values are written at the same time at the end of the current simulator time step.
+    .. note::
+        Issuing a :class:`!Force` and :class:`Release` in the same evaluation cycle in VHDL will result in the :class:`!Force` "winning".
+    """
 
-            Use :meth:`setimmediatevalue` to set the value immediately.
-        """
-        raise TypeError(
-            "Not permissible to get values of object {} of type {}".format(
-                self._name, type(self)
-            )
-        )
 
-    @value.setter
-    def value(self, value):
-        self._set_value(value, cocotb.scheduler._schedule_write)
+class Release:
+    r""":term:`Release <release>` a :term:`forced <force>` simulation object.
 
-    def setimmediatevalue(self, value):
-        """Assign a value to this simulation object immediately."""
+    Does not change the current value of the simulation object.
+    See :class:`Deposit` for information on behavior after this write completes.
 
-        def _call_now(handle, f, *args):
-            f(*args)
+    .. note::
+        VHDL applies writes according to their definition.
+        ``signal`` writes are set inertially, regardless of using this class,
+        while ``variable`` writes are set immediately, regardless of using this class.
 
-        self._set_value(value, _call_now)
+    .. note::
+        Verilog :class:`!Release`\ s are always immediate.
+        This also means that if there are multiple cocotb Tasks or multiple ``always`` blocks writing to the same object,
+        the resulting value is non-deterministic.
 
-    def _set_value(self, value, call_sim):
-        """This should be overriden in subclasses.
+    .. note::
+        Issuing a :class:`Force` and :class:`!Release` in the same evaluation cycle in VHDL will result in the :class:`!Force` "winning".
 
-        This is used to implement both the setter for :attr:`value`, and the
-        :meth:`setimmediatevalue` method.
+    .. note::
+        Releasing a ``reg`` or ``logic`` in Verilog will leave the current value.
+        Releasing a ``wire`` in Verilog will cause the value to be recomputed from the wire's drivers current values.
+        Releasing a ``signal`` in VHDL will cause the value to be recomputed from the signal's drivers current value.
+        Unconnected ``in`` ports and unconnected internal signals have no drivers and their value after :class:`!Release` will be ``U`` in VHDL and ``X`` in Verilog.
+    """
 
-        ``call_sim(handle, f, *args)`` should be used to schedule simulator writes,
-        rather than performing them directly as ``f(*args)``.
-        """
-        raise TypeError(
-            "Not permissible to set values on object {} of type {}".format(
-                self._name, type(self)
-            )
-        )
 
-    def __le__(self, value):
-        """Overload less-than-or-equal-to operator to provide an HDL-like shortcut.
+class Immediate(Generic[_ValueT]):
+    """:term:`Deposit <no-delay deposit>` a value on a simulator object without delay.
 
-        Example:
-        >>> module.signal <= 2
-        """
-        warnings.warn(
-            "Setting values on handles using the ``handle <= value`` syntax is deprecated. "
-            "Instead use the ``handle.value = value`` syntax",
-            DeprecationWarning,
-            stacklevel=2,
-        )
+    The value of the signal will be changed immediately
+    and should be able to be read back immediately following the write.
+    Otherwise, behaves like :class:`Deposit`.
+
+    .. note::
+        VHDL applies writes according to their definition.
+        ``signal`` writes are set inertially, regardless of using this class;
+        while ``variable`` writes are set immediately, regardless of using this class.
+
+    .. note::
+        In Verilog, because these writes are immediate,
+        if there are multiple cocotb Tasks or multiple ``always`` blocks writing to the same object,
+        the resulting value is non-deterministic.
+    """
+
+    def __init__(self, value: _ValueT) -> None:
         self.value = value
-        return _AssignmentResult(self, value)
 
-    def __eq__(self, other):
-        """Equality comparator for non-hierarchy objects
 
-        If ``other`` is not a :class:`SimHandleBase` instance the comparison
-        uses the comparison method of the ``other`` object against our
-        ``.value``.
-        """
-        if isinstance(other, SimHandleBase):
-            return SimHandleBase.__eq__(self, other)
-        return self.value == other
+class _OldImmediate(Generic[_ValueT]):
+    def __init__(self, value: _ValueT) -> None:
+        self.value = value
+
+
+_trust_inertial = bool(int(os.environ.get("COCOTB_TRUST_INERTIAL_WRITES", "0")))
+
+# A dictionary of pending (write_func, args), keyed by handle.
+# Writes are applied oldest to newest (least recently used).
+# Only the last scheduled write to a particular handle in a timestep is performed.
+_write_calls: "dict[ValueObjectBase[Any, Any], Tuple[Callable[[int, Any], None], _GPISetAction, Any]]" = insertion_ordered_dict()
+
+_write_task: Union[Task[None], None] = None
+
+_writes_pending = Event()
+
+
+async def _do_writes() -> None:
+    """An internal task that schedules a ReadWrite to force writes to occur."""
+    while True:
+        await _writes_pending.wait()
+        await ReadWrite()
+
+
+def _start_write_scheduler() -> None:
+    global _write_task
+    if _write_task is None:
+        _write_task = Task(_do_writes())
+        cocotb._scheduler_inst._schedule_task(_write_task)
+
+
+def _stop_write_scheduler() -> None:
+    global _write_task
+    if _write_task is not None:
+        _write_task.cancel()
+        _write_task = None
+    _write_calls.clear()
+    _writes_pending.clear()
+
+
+def _apply_scheduled_writes() -> None:
+    for func, action, value in _write_calls.values():
+        func(action.value, value)
+    _write_calls.clear()
+    _writes_pending.clear()
+
+
+if _trust_inertial:
+
+    def _schedule_write(
+        handle: "ValueObjectBase[Any, Any]",
+        write_func: Callable[[int, _ValueT], None],
+        action: _GPISetAction,
+        value: _ValueT,
+    ) -> None:
+        # Trust the simulator and just write.
+        write_func(action.value, value)
+else:
+
+    def _schedule_write(
+        handle: "ValueObjectBase[Any, Any]",
+        write_func: Callable[[int, _ValueT], None],
+        action: _GPISetAction,
+        value: _ValueT,
+    ) -> None:
+        if isinstance(current_gpi_trigger(), ReadWrite):
+            # If we are already in the ReadWrite phase, apply writes immediately as an optimization.
+            write_func(action.value, value)
+        elif action is _GPISetAction.DEPOSIT:
+            # Queue write for the beginning of the next ReadWrite phase because we can't trust the simulator. =(
+            if handle in _write_calls:
+                del _write_calls[handle]
+            _write_calls[handle] = (write_func, action, value)
+            _writes_pending.set()
+        else:
+            # If we are writing anything that isn't an inertial write, it must be applied immediately.
+            write_func(action.value, value)
+
+
+#: Type returned by the :attr:`~ValueObjectBase.value` getter and returned by the :meth:`~ValueObjectBase.get` method.
+ValueGetT = TypeVar("ValueGetT")
 
-    def __ne__(self, other):
-        if isinstance(other, SimHandleBase):
-            return SimHandleBase.__ne__(self, other)
-        return self.value != other
 
-    # Re-define hash because we defined __eq__
-    def __hash__(self):
-        return SimHandleBase.__hash__(self)
+#: Type accepted by the :attr:`~ValueObjectBase.value` setter and the :meth:`~ValueObjectBase.set` and :meth:`~ValueObjectBase.setimmediatevalue` methods.
+ValueSetT = TypeVar("ValueSetT")
 
 
-class ConstantObject(NonHierarchyObject):
-    """An object which has a value that can be read, but not set.
+class ValueObjectBase(SimHandleBase, Generic[ValueGetT, ValueSetT]):
+    """Abstract base class for simulation objects that have a value.
 
-    The value is cached in the class since it is fixed at elaboration
-    time and won't change within a simulation.
+    Inherits from :class:`SimHandleBase`.
     """
 
-    def __init__(self, handle, path, handle_type):
+    @property
+    def value(self) -> ValueGetT:
+        """Get or set the value of the simulation object.
+
+        :getter: Return the current value of the simulation object.
+
+        :setter:
+            Set the value of the simulation object.
+
+            See :class:`Deposit`, :class:`Force`, :class:`Freeze`, :class:`Release`, and :class:`Immediate`
+            for additional actions that can be taken when setting a value.
+            These are used like so:
+
+            .. code-block:: python
+
+                dut.handle.value = 1  # default Deposit action
+                dut.handle.value = Deposit(2)
+                dut.handle.value = Force(3)
+                dut.handle.value = Freeze()
+                dut.handle.value = Release()
+                dut.handle.value = Immediate(4)
         """
+        return self.get()
+
+    @value.setter
+    def value(self, value: ValueSetT) -> None:
+        self.set(value)
+
+    @abstractmethod
+    def get(self) -> ValueGetT:
+        """Return the current value of the simulation object."""
+
+    def set(
+        self,
+        value: Union[
+            ValueSetT,
+            Deposit[ValueSetT],
+            Force[ValueSetT],
+            Freeze,
+            Release,
+            Immediate[ValueSetT],
+        ],
+    ) -> None:
+        """Set the value of the simulation object.
+
+        See :class:`Deposit`, :class:`Force`, :class:`Freeze`, :class:`Release`, and :class:`Immediate`
+        for additional actions that can be taken when setting a value.
+
         Args:
-            handle (int): The GPI handle to the simulator object.
-            path (str): Path to this handle, ``None`` if root.
-            handle_type: The type of the handle
-                (``simulator.INTEGER``, ``simulator.ENUM``,
-                ``simulator.REAL``, ``simulator.STRING``).
+            value: The value to set the simulation object to. This may include type conversion.
+
+        Raises:
+            TypeError: If the *value* is of a type that cannot be converted to a simulation value,
+                or if the simulation object is immutable.
+            ValueError: If the *value* is of the correct type, but the value fails to convert.
         """
-        NonHierarchyObject.__init__(self, handle, path)
-        if handle_type in [simulator.INTEGER, simulator.ENUM]:
-            self._value = self._handle.get_signal_val_long()
-        elif handle_type == simulator.REAL:
-            self._value = self._handle.get_signal_val_real()
-        elif handle_type == simulator.STRING:
-            self._value = self._handle.get_signal_val_str()
+        if isinstance(current_gpi_trigger(), ReadOnly):
+            raise RuntimeError("Attempting settings a value during the ReadOnly phase.")
+        if self.is_const:
+            raise TypeError("Attempted setting an immutable object")
+        if isinstance(value, Deposit):
+            self._set_value(value.value, _GPISetAction.DEPOSIT)
+        elif isinstance(value, Force):
+            self._set_value(value.value, _GPISetAction.FORCE)
+        elif isinstance(value, Freeze):
+            # We assume that ValueSetT >= ValueGetT
+            self._set_value(cast("ValueSetT", self.get()), _GPISetAction.FORCE)
+        elif isinstance(value, Release):
+            # We assume that ValueSetT >= ValueGetT
+            self._set_value(cast("ValueSetT", self.get()), _GPISetAction.RELEASE)
+        elif isinstance(value, Immediate):
+            self._set_value(value.value, _GPISetAction.NO_DELAY)
+        elif isinstance(value, _OldImmediate):
+            self._set_value(value.value, _GPISetAction.OLD_IMMEDIATE)
         else:
-            val = self._handle.get_signal_val_binstr()
-            self._value = BinaryValue(n_bits=len(val))
-            try:
-                self._value.binstr = val
-            except Exception:
-                self._value = val
+            self._set_value(value, _GPISetAction.DEPOSIT)
+
+    @deprecated(
+        "Use `handle.set(Immediate(...))` or `handle.value = Immediate(...)` instead."
+    )
+    def setimmediatevalue(
+        self,
+        value: Union[
+            ValueSetT,
+            Deposit[ValueSetT],
+            Force[ValueSetT],
+            Freeze,
+            Release,
+            Immediate[ValueSetT],
+        ],
+    ) -> None:
+        r"""Set the value of the simulation object immediately.
+
+        See :class:`Deposit`, :class:`Force`, :class:`Freeze`, :class:`Release`, and :class:`Immediate`
+        for additional actions that can be taken when setting a value.
+
+        Passing :class:`Deposit`\ s and unwrapped values is equivalent to passing an :class:`Immediate` to :meth:`set`.
+
+        .. deprecated:: 2.0
+            Use ``handle.set(Immediate(...))`` or ``handle.value = Immediate(...)`` instead.
+            This could result in a change in behavior because prior to version 2.0 this function did not set values immediately.
+        """
+        if isinstance(value, Deposit):
+            value = _OldImmediate(value.value)  # type: ignore
+        elif not isinstance(value, (Force, Freeze, Release, Immediate)):
+            value = _OldImmediate(value)  # type: ignore
+        self.set(value)
+
+    @cached_property
+    def is_const(self) -> bool:
+        """``True`` if the simulator object is immutable, e.g. a Verilog parameter or VHDL constant or generic."""
+        return self._handle.get_const()
+
+    @abstractmethod
+    def _set_value(
+        self,
+        value: ValueSetT,
+        action: _GPISetAction,
+    ) -> None:
+        """Schedule a write of the given value to a simulator object.
+
+        Conversion from multiple Python types into a type understood by the simulator is expected.
+        This is used to implement the :attr:`value` property setter, :meth:`setimmediatevalue`, and :meth:`set`.
+        Implementations can assume that handle isn't :meth:`const <is_const>`
+        and the Scheduler is not in the :data:`ReadOnly <cocotb.SimPhase.READ_ONLY>` phase.
 
-    def __int__(self):
-        return int(self.value)
+        Args:
+            value: A value used to set the handle.
+            action: Whether to deposit, force, or release the value on the handle.
+        """
 
-    def __float__(self):
-        return float(self.value)
 
-    @NonHierarchyObject.value.getter
-    def value(self):
-        """The value of this simulation object."""
-        return self._value
+#: Type of value of each element in an :class:`ArrayObject`.
+ElemValueT = TypeVar("ElemValueT")
 
-    def __str__(self):
-        if isinstance(self.value, bytes):
-            StringObject._emit_str_warning(self)
-            return self.value.decode("ascii")
-        else:
-            ModifiableObject._emit_str_warning(self)
-            return str(self.value)
+#: Subtype of :class:`ValueObjectBase` returned when iterating or indexing a :class:`ArrayObject`.
+ChildObjectT = TypeVar("ChildObjectT", bound=ValueObjectBase[Any, Any])
 
 
-class NonHierarchyIndexableObject(NonHierarchyObject):
-    """A non-hierarchy indexable object.
+class ArrayObject(
+    ValueObjectBase[Array[ElemValueT], Union[Array[ElemValueT], Sequence[ElemValueT]]],
+    _RangeableObjectMixin,
+    Generic[ElemValueT, ChildObjectT],
+):
+    """A simulation object that is an array of value-having simulation objects.
 
-    Getting and setting the current value of an array is done
-    by iterating through sub-handles in left-to-right order.
+    Inherits from :class:`SimHandleBase` and :class:`ValueObjectBase`.
 
-    Given an HDL array ``arr``:
+    With Verilog simulation objects, unpacked vectors are mapped to this type.
+    Packed vectors are typically mapped to :class:`LogicArrayObject`.
 
-    +--------------+---------------------+--------------------------------------------------------------+
-    | Verilog      | VHDL                | ``arr.value`` is equivalent to                               |
-    +==============+=====================+==============================================================+
-    | ``arr[4:7]`` | ``arr(4 to 7)``     | ``[arr[4].value, arr[5].value, arr[6].value, arr[7].value]`` |
-    +--------------+---------------------+--------------------------------------------------------------+
-    | ``arr[7:4]`` | ``arr(7 downto 4)`` | ``[arr[7].value, arr[6].value, arr[5].value, arr[4].value]`` |
-    +--------------+---------------------+--------------------------------------------------------------+
+    With VHDL simulation objects, all arrayed objects that aren't ``std_(u)logic``,
+    ``sfixed``, ``ufixed``, ``unsigned``, ``signed``, and ``string`` are mapped to this type.
 
-    When setting the signal as in ``arr.value = ...``, the same index equivalence as noted in the table holds.
+    These objects can be iterated over to yield child objects:
 
-    .. warning::
-        Assigning a value to a sub-handle:
+    .. code-block:: python
 
-        - **Wrong**: ``dut.some_array.value[0] = 1`` (gets value as a list then updates index 0)
-        - **Correct**: ``dut.some_array[0].value = 1``
-    """
+        for child in dut.array_object:
+            print(child._path)
 
-    def __init__(self, handle, path):
-        NonHierarchyObject.__init__(self, handle, path)
-        self._range = self._handle.get_range()
-
-    def __setitem__(self, index, value):
-        """Provide transparent assignment to indexed array handles."""
-        warnings.warn(
-            "Setting values on handles using the ``dut.handle[i] = value`` syntax is deprecated. "
-            "Instead use the ``handle[i].value = value`` syntax",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        self[index].value = value
+    A particular child can be retrieved using its index:
 
-    def __getitem__(self, index):
-        if isinstance(index, slice):
-            raise IndexError("Slice indexing is not supported")
-        if self._range is None:
-            raise IndexError(
-                "%s is not indexable.  Unable to get object at index %d"
-                % (self._fullname, index)
-            )
-        if index in self._sub_handles:
-            return self._sub_handles[index]
-        new_handle = self._handle.get_handle_by_index(index)
-        if not new_handle:
-            raise IndexError(
-                "%s contains no object at index %d" % (self._fullname, index)
-            )
-        path = self._path + "[" + str(index) + "]"
-        self._sub_handles[index] = SimHandle(new_handle, path)
-        return self._sub_handles[index]
+    .. code-block:: python
 
-    def __iter__(self):
-        if self._range is None:
-            return
+        child = dut.array_object[0]
 
-        self._log.debug("Iterating with range [%d:%d]", self._range[0], self._range[1])
-        for i in self._range_iter(self._range[0], self._range[1]):
-            try:
-                result = self[i]
-                yield result
-            except IndexError:
-                continue
+        # reversed iteration over children
+        for child_idx in reversed(dut.array_object.range):
+            dut.array_object[child_idx]
+    """
 
-    def _range_iter(self, left, right):
-        if left > right:
-            while left >= right:
-                yield left
-                left = left - 1
-        else:
-            while left <= right:
-                yield left
-                left = left + 1
+    def __init__(self, handle: simulator.gpi_sim_hdl, path: Optional[str]) -> None:
+        super().__init__(handle, path)
+        self._sub_handles: Dict[int, ChildObjectT] = {}
 
-    @NonHierarchyObject.value.getter
-    def value(self) -> list:
-        # Don't use self.__iter__, because it has an unwanted `except IndexError`
-        return [self[i].value for i in self._range_iter(self._range[0], self._range[1])]
+    def get(self) -> Array[ElemValueT]:
+        """Return the current value as an :class:`~cocotb.types.Array`.
 
-    def _set_value(self, value, call_sim):
-        """Assign value from a list of same length to an array in left-to-right order.
-        Index 0 of the list maps to the left-most index in the array.
+        Given the HDL array ``arr``, getting the value is equivalent to:
 
-        See the docstring for this class.
+        +--------------+---------------------+--------------------------------------------------------------------------------------------------+
+        | Verilog      | VHDL                | ``arr.get()`` is equivalent to                                                                   |
+        +==============+=====================+==================================================================================================+
+        | ``arr[4:7]`` | ``arr(4 to 7)``     | ``Array([arr[4].value, arr[5].value, arr[6].value, arr[7].value], range=Range(4, 'to', 7))``     |
+        +--------------+---------------------+--------------------------------------------------------------------------------------------------+
+        | ``arr[7:4]`` | ``arr(7 downto 4)`` | ``Array([arr[7].value, arr[6].value, arr[5].value, arr[4].value], range=Range(7, 'downto', 4))`` |
+        +--------------+---------------------+--------------------------------------------------------------------------------------------------+
         """
-        if type(value) is not list:
-            raise TypeError(
-                "Assigning non-list value to object {} of type {}".format(
-                    self._name, type(self)
-                )
-            )
-        if len(value) != len(self):
-            raise ValueError(
-                "Assigning list of length %d to object %s of length %d"
-                % (len(value), self._name, len(self))
-            )
-        for val_idx, self_idx in enumerate(
-            self._range_iter(self._range[0], self._range[1])
-        ):
-            self[self_idx]._set_value(value[val_idx], call_sim)
+        r = self.range
+        return Array._from_handle(
+            value=[self[i].value for i in r],
+            range=r,
+            warn_indexing=indexing_changed(r) if do_indexing_changed_warning else False,
+        )
 
+    def set(
+        self,
+        value: Union[
+            Union[Array[ElemValueT], Sequence[ElemValueT]],
+            Deposit[Union[Array[ElemValueT], Sequence[ElemValueT]]],
+            Force[Union[Array[ElemValueT], Sequence[ElemValueT]]],
+            Freeze,
+            Release,
+            Immediate[Union[Array[ElemValueT], Sequence[ElemValueT]]],
+        ],
+    ) -> None:
+        """Set the value using an :class:`.Array`-like value.
 
-class NonConstantObject(NonHierarchyIndexableObject):
-    """A non-constant object"""
+        The simulation object is set, element-by-element, left-to-right, using the corresponding element of *value*.
+        The indexes of *value* and the simulation object are not taken into account, only position.
 
-    # FIXME: what is the difference to ModifiableObject? Explain in docstring.
+        .. warning::
+            Assigning a value to a sub-handle:
 
-    def drivers(self):
-        """An iterator for gathering all drivers for a signal.
+            - **Wrong**: ``dut.some_array.value[0] = 1`` (gets value as an Array, updates index 0, then throws it away)
+            - **Correct**: ``dut.some_array[0].value = 1``
 
-        This is currently only available for VPI.
-        Also, only a few simulators implement this.
-        """
-        return self._handle.iterate(simulator.DRIVERS)
+        Args:
+            value: The value to set the signal to. This may include type conversion.
 
-    def loads(self):
-        """An iterator for gathering all loads on a signal.
+        Raises:
+            TypeError: If *value* is of a type that can't be assigned to the simulation object.
 
-        This is currently only available for VPI.
-        Also, only a few simulators implement this.
+        .. warning::
+            Exceptions from array element :meth:`.ValueObjectBase.set` calls will be propagated up,
+            so the actual set of exceptions possible is greater than this list.
         """
-        return self._handle.iterate(simulator.LOADS)
+        super().set(value)
 
+    def _set_value(
+        self,
+        value: Union[Array[ElemValueT], Sequence[ElemValueT]],
+        action: _GPISetAction,
+    ) -> None:
+        if len(value) != len(self):
+            raise ValueError(
+                f"Assigning list of length {len(value)} to object {self._name} of length {len(self)}"
+            )
+        for elem, self_idx in zip(value, self.range):
+            self[self_idx]._set_value(elem, action)
 
-class _SetAction:
-    """Base class representing the type of action used while write-accessing a handle."""
-
-    pass
+    def __getitem__(self, index: int) -> ChildObjectT:
+        if isinstance(index, slice):
+            raise TypeError("Slicing is not supported")
+        if index in self._sub_handles:
+            return self._sub_handles[index]
+        new_handle = self._handle.get_handle_by_index(index)
+        if not new_handle:
+            raise IndexError(f"{self._path} contains no object at index {index}")
+        path = self._path + "[" + str(index) + "]"
+        self._sub_handles[index] = cast(
+            "ChildObjectT", _make_sim_object(new_handle, path)
+        )
+        return self._sub_handles[index]
 
+    def __iter__(self) -> Iterable[ChildObjectT]:
+        for i in self.range:
+            yield self[i]
 
-class _SetValueAction(_SetAction):
-    __slots__ = ("value",)
-    """Base class representing the type of action used while write-accessing a handle with a value."""
 
-    def __init__(self, value):
-        self.value = value
+class _NonIndexableValueObjectBase(ValueObjectBase[ValueGetT, ValueSetT]):
+    """ValueObject that is treated as a single object in the GPI.
 
+    NonArrayValueObjects support :meth:`value_change` triggers.
+    """
 
-class Deposit(_SetValueAction):
-    """Action used for placing a value into a given handle."""
+    @cached_property
+    def value_change(self) -> ValueChange:
+        """A trigger which fires whenever the value changes."""
+        if self.is_const:
+            raise TypeError("Can't get ValueChange on immutable signal.")
+        return ValueChange._make(self)
 
-    def _as_gpi_args_for(self, hdl):
-        return self.value, 0  # GPI_DEPOSIT
+    @cached_property
+    def _edge(self) -> Edge:
+        if self.is_const:
+            raise TypeError("Can't get Edge on immutable signal.")
+        return Edge._make(self)
 
 
-class Force(_SetValueAction):
-    """Action used to force a handle to a given value until a release is applied."""
+class LogicObject(_NonIndexableValueObjectBase[Logic, Union[Logic, int, str]]):
+    """A scalar logic simulation object.
 
-    def _as_gpi_args_for(self, hdl):
-        return self.value, 1  # GPI_FORCE
+    Inherits from :class:`SimHandleBase` and :class:`ValueObjectBase`.
 
+    Verilog data types that map to this object:
 
-class Freeze(_SetAction):
-    """Action used to make a handle keep its current value until a release is used."""
+        * ``logic``
+        * ``bit``
 
-    def _as_gpi_args_for(self, hdl):
-        return hdl.value, 1  # GPI_FORCE
+    VHDL types that map to this object:
 
+        * ``std_logic``
+        * ``std_ulogic``
+        * ``bit``
+    """
 
-class Release(_SetAction):
-    """Action used to stop the effects of a previously applied force/freeze action."""
+    def __init__(self, handle: simulator.gpi_sim_hdl, path: Optional[str]) -> None:
+        super().__init__(handle, path)
 
-    def _as_gpi_args_for(self, hdl):
-        return 0, 2  # GPI_RELEASE
+    def _set_value(
+        self,
+        value: Union[Logic, int, str],
+        action: _GPISetAction,
+    ) -> None:
+        value_: str
+        if isinstance(value, (int, str)):
+            value_ = str(Logic(value))
 
+        elif isinstance(value, LogicArray):
+            if len(value) != 1:
+                raise ValueError(
+                    f"Cannot assign value of length {len(value)} to handle of length 1"
+                )
+            value_ = str(value)
 
-class ModifiableObject(NonConstantObject):
-    """Base class for simulator objects whose values can be modified."""
+        elif isinstance(value, Logic):
+            value_ = str(value)
 
-    def _set_value(self, value, call_sim):
-        """Set the value of the underlying simulation object to *value*.
+        else:
+            raise TypeError(
+                f"Unsupported type for value assignment: {type(value)} ({value!r})"
+            )
 
-        This operation will fail unless the handle refers to a modifiable
-        object, e.g. net, signal or variable.
+        _schedule_write(self, self._handle.set_signal_val_binstr, action, value_)
 
-        We determine the library call to make based on the type of the value
-        because assigning integers less than 32 bits is faster.
+    def get(self) -> Logic:
+        """Return the current value of the simulation object as a :class:`.Logic`."""
+        binstr = self._handle.get_signal_val_binstr()
+        return Logic(binstr)
+
+    def set(
+        self,
+        value: Union[
+            Union[Logic, int, str],
+            Deposit[Union[Logic, int, str]],
+            Force[Union[Logic, int, str]],
+            Freeze,
+            Release,
+            Immediate[Union[Logic, int, str]],
+        ],
+    ) -> None:
+        """Set the value of the simulation object using a :class:`.Logic`-like value.
 
         Args:
-            value (cocotb.binary.BinaryValue, int):
-                The value to drive onto the simulator object.
+            value: The value to set the simulation object to.
 
         Raises:
-            TypeError: If target has an unsupported type for value assignment.
+            TypeError: If *value* is of a type that can't be assigned to the simulation object, or readily converted into a type that can.
+            ValueError: If *value* would not fit in the bounds of the simulation object.
+        """
+        super().set(value)
+
+    @cached_property
+    def rising_edge(self) -> RisingEdge:
+        """A trigger which fires whenever the value changes to a ``1``."""
+        if self.is_const:
+            raise TypeError("Can't get RisingEdge on immutable signal")
+        return RisingEdge._make(self)
+
+    @cached_property
+    def falling_edge(self) -> FallingEdge:
+        """A trigger which fires whenever the value changes to a ``0``."""
+        if self.is_const:
+            raise TypeError("Can't get FallingEdge on immutable signal")
+        return FallingEdge._make(self)
+
+    def __len__(self) -> int:
+        return 1
+
+    @deprecated(
+        "`int(handle)` casts have been deprecated. Use `int(handle.value)` instead."
+    )
+    def __int__(self) -> int:
+        return int(self.value)
 
-            OverflowError: If int value is out of the range that can be represented
-                by the target. -2**(Nbits - 1) <= value <= 2**Nbits - 1
+    @deprecated(
+        "`str(handle)` casts have been deprecated. Use `str(handle.value)` instead."
+    )
+    def __str__(self) -> str:
+        return str(self.value)
 
-        .. deprecated:: 1.5
-            :class:`ctypes.Structure` objects are no longer accepted as values for assignment.
-            Convert the struct object to a :class:`~cocotb.binary.BinaryValue` before assignment using
-            ``BinaryValue(value=bytes(struct_obj), n_bits=len(signal))`` instead.
 
-        .. deprecated:: 1.5
-            :class:`dict` objects are no longer accepted as values for assignment.
-            Convert the dictionary to an integer before assignment using
-            ``sum(v << (d['bits'] * i) for i, v in enumerate(d['values']))``.
-        """
-        value, set_action = self._check_for_set_action(value)
+class LogicArrayObject(
+    _NonIndexableValueObjectBase[LogicArray, Union[LogicArray, Logic, int, str]],
+    _RangeableObjectMixin,
+):
+    """A logic array simulation object.
+
+    Inherits from :class:`SimHandleBase` and :class:`ValueObjectBase`.
+
+    Verilog types that map to this object:
+
+        * packed any-dimensional vectors of ``logic`` or ``bit``
+        * packed any-dimensional vectors of packed structures
+
+    VHDL types that map to this object:
+
+        * ``std_logic_vector`` and ``std_ulogic_vector``
+        * ``unsigned``
+        * ``signed``
+        * ``ufixed``
+        * ``sfixed``
+        * ``float``
+    """
 
+    def __init__(self, handle: simulator.gpi_sim_hdl, path: Optional[str]) -> None:
+        super().__init__(handle, path)
+
+    def _set_value(
+        self,
+        value: Union[LogicArray, Logic, int, str],
+        action: _GPISetAction,
+    ) -> None:
+        value_: str
         if isinstance(value, int):
             min_val, max_val = _value_limits(len(self), _Limits.VECTOR_NBIT)
             if min_val <= value <= max_val:
                 if len(self) <= 32:
-                    call_sim(self, self._handle.set_signal_val_int, set_action, value)
+                    _schedule_write(
+                        self, self._handle.set_signal_val_int, action, value
+                    )
                     return
 
+                # LogicArray used for checking
                 if value < 0:
-                    value = BinaryValue(
-                        value=value,
-                        n_bits=len(self),
-                        bigEndian=False,
-                        binaryRepresentation=BinaryRepresentation.TWOS_COMPLEMENT,
+                    value_ = str(
+                        LogicArray.from_signed(
+                            value,
+                            Range(len(self) - 1, "downto", 0),
+                        )
                     )
                 else:
-                    value = BinaryValue(
-                        value=value,
-                        n_bits=len(self),
-                        bigEndian=False,
-                        binaryRepresentation=BinaryRepresentation.UNSIGNED,
+                    value_ = str(
+                        LogicArray.from_unsigned(
+                            value,
+                            Range(len(self) - 1, "downto", 0),
+                        )
                     )
             else:
-                raise OverflowError(
-                    "Int value ({!r}) out of range for assignment of {!r}-bit signal ({!r})".format(
-                        value, len(self), self._name
-                    )
-                )
-
-        if isinstance(value, ctypes.Structure):
-            warnings.warn(
-                "`ctypes.Structure` values are no longer accepted for value assignment. "
-                "Use `BinaryValue(value=bytes(struct_obj), n_bits=len(signal))` instead",
-                DeprecationWarning,
-                stacklevel=3,
-            )
-            value = BinaryValue(value=cocotb.utils.pack(value), n_bits=len(self))
-
-        elif isinstance(value, dict):
-            warnings.warn(
-                "dict values are no longer accepted for value assignment. "
-                "Use `sum(v << (d['bits'] * i) for i, v in enumerate(d['values']))` "
-                "to convert the dict to an int before assignment.",
-                DeprecationWarning,
-                stacklevel=3,
-            )
-            # We're given a dictionary with a list of values and a bit size...
-            num = 0
-            vallist = list(value["values"])
-            vallist.reverse()
-            if len(vallist) * value["bits"] != len(self):
-                raise TypeError(
-                    "Unable to set with array length %d of %d bit entries = %d total, target is only %d bits long"
-                    % (
-                        len(value["values"]),
-                        value["bits"],
-                        len(value["values"]) * value["bits"],
-                        len(self),
-                    )
+                raise ValueError(
+                    f"Int value ({value!r}) out of range for assignment of {len(self)!r}-bit signal ({self._name!r})"
                 )
 
-            for val in vallist:
-                num = (num << value["bits"]) + val
-            value = BinaryValue(value=num, n_bits=len(self), bigEndian=False)
+        elif isinstance(value, str):
+            # LogicArray used for checking
+            value_ = str(LogicArray(value, self.range))
 
         elif isinstance(value, LogicArray):
             if len(self) != len(value):
                 raise ValueError(
                     f"cannot assign value of length {len(value)} to handle of length {len(self)}"
                 )
-            value = value.to_BinaryValue()
+            value_ = str(value)
 
         elif isinstance(value, Logic):
             if len(self) != 1:
                 raise ValueError(
                     f"cannot assign value of length 1 to handle of length {len(self)}"
                 )
-            value = BinaryValue(str(value))
-
-        elif isinstance(value, BinaryValue):
-            if len(value) != len(self):
-                raise ValueError(
-                    f"cannot assign value of length {len(value)} to handle of length {len(self)}"
-                )
+            value_ = str(value)
 
         else:
             raise TypeError(
-                "Unsupported type for value assignment: {} ({!r})".format(
-                    type(value), value
-                )
+                f"Unsupported type for value assignment: {type(value)} ({value!r})"
             )
 
-        call_sim(self, self._handle.set_signal_val_binstr, set_action, value.binstr)
-
-    def _check_for_set_action(self, value):
-        if not isinstance(value, _SetAction):
-            return value, 0  # GPI_DEPOSIT
-        return value._as_gpi_args_for(self)
+        _schedule_write(self, self._handle.set_signal_val_binstr, action, value_)
 
-    @NonConstantObject.value.getter
-    def value(self) -> BinaryValue:
+    def get(self) -> LogicArray:
+        """Return the current value of the simulation object as a :class:`.LogicArray`."""
         binstr = self._handle.get_signal_val_binstr()
-        # Skip BinaryValue.assign() as we know we are using a binstr
-        result = BinaryValue(n_bits=len(binstr))
-        # Skip the permitted characters check as we trust the simulator
-        result._set_trusted_binstr(binstr)
-        return result
+        return LogicArray._from_handle(
+            value=binstr,
+            warn_indexing=indexing_changed(self.range)
+            if do_indexing_changed_warning
+            else False,
+        )
 
-    def __int__(self):
-        return int(self.value)
+    def set(
+        self,
+        value: Union[
+            Union[LogicArray, Logic, int, str],
+            Deposit[Union[LogicArray, Logic, int, str]],
+            Force[Union[LogicArray, Logic, int, str]],
+            Freeze,
+            Release,
+            Immediate[Union[LogicArray, Logic, int, str]],
+        ],
+    ) -> None:
+        """Set the value of the simulation object using a :class:`.LogicArray`-like value.
 
-    def _emit_str_warning(self):
-        warnings.warn(
-            "`str({t})` is deprecated, and in future will return `{t}._path`. "
-            "To get a string representation of the value, use `str({t}.value)`.".format(
-                t=type(self).__qualname__
-            ),
-            FutureWarning,
-            stacklevel=3,
-        )
+        Args:
+            value: The value to set the simulation object to.
+
+        Raises:
+            TypeError: If *value* is of a type that can't be assigned to the simulation object, or readily converted into a type that can.
+            ValueError: If *value* would not fit in the bounds of the simulation object.
+
+        .. versionchanged:: 2.0
+            Using :class:`ctypes.Structure` objects to set values was removed.
+            Convert the struct object to a :class:`~cocotb.types.LogicArray` before assignment using
+            ``LogicArray("".join(format(int(byte), "08b") for byte in bytes(struct_obj)))`` instead.
+
+        .. versionchanged:: 2.0
+            Using :class:`dict` objects to set values was removed.
+            Convert the dictionary to an integer before assignment using
+            ``sum(v << (d['bits'] * i) for i, v in enumerate(d['values']))`` instead.
 
-    def __str__(self):
-        self._emit_str_warning()
+        .. versionchanged:: 2.0
+            Supplying too large of an :class:`int` value results in raising a :exc:`ValueError` instead of an :exc:`OverflowError`.
+        """
+        super().set(value)
+
+    @deprecated(
+        "`int(handle)` casts have been deprecated. Use `int(handle.value)` instead."
+    )
+    def __int__(self) -> int:
+        return int(self.value)
+
+    @deprecated(
+        "`str(handle)` casts have been deprecated. Use `str(handle.value)` instead."
+    )
+    def __str__(self) -> str:
         return str(self.value)
 
+    def __len__(self) -> int:
+        # can't use `range` to get length because `range` is for outer-most dimension only
+        # and this object needs to support multi-dimensional packed arrays.
+        return self._len
 
-class RealObject(ModifiableObject):
-    """Specific object handle for Real signals and variables."""
+    @cached_property
+    def _len(self) -> int:
+        return self._handle.get_num_elems()
 
-    def _set_value(self, value, call_sim):
-        """Set the value of the underlying simulation object to value.
+    def __getitem__(self, _: object) -> NoReturn:
+        raise TypeError(
+            "Packed objects, either arrays or structs, cannot be indexed.\n"
+            "Try instead reading the whole value and slicing: `t = handle.value; t[0:3]`.\n"
+            "If you need to use an element in an Edge Trigger, consider making the array or struct unpacked.\n"
+            "Alternatively, use `ValueChange` on the whole object and check the bit(s) you care about for changes afterwards."
+        )
 
-        This operation will fail unless the handle refers to a modifiable
-        object, e.g. net, signal or variable.
 
-        Args:
-            value (float): The value to drive onto the simulator object.
+class RealObject(_NonIndexableValueObjectBase[float, float]):
+    """A floating point simulation object.
 
-        Raises:
-            TypeError: If target has an unsupported type for
-                real value assignment.
-        """
-        value, set_action = self._check_for_set_action(value)
+    Inherits from :class:`SimHandleBase` and :class:`ValueObjectBase`.
 
-        try:
-            value = float(value)
-        except ValueError:
+    This type is used when a ``real`` object in VHDL or ``float`` object in Verilog is seen.
+    """
+
+    def __init__(self, handle: simulator.gpi_sim_hdl, path: Optional[str]) -> None:
+        super().__init__(handle, path)
+
+    def _set_value(
+        self,
+        value: float,
+        action: _GPISetAction,
+    ) -> None:
+        if not isinstance(value, (float, int)):
             raise TypeError(
-                "Unsupported type for real value assignment: {} ({!r})".format(
-                    type(value), value
-                )
+                f"Unsupported type for real value assignment: {type(value)} ({value!r})"
             )
 
-        call_sim(self, self._handle.set_signal_val_real, set_action, value)
+        _schedule_write(self, self._handle.set_signal_val_real, action, value)
 
-    @ModifiableObject.value.getter
-    def value(self) -> float:
+    def get(self) -> float:
+        """Return the current value of the simulation object as a :class:`float`."""
         return self._handle.get_signal_val_real()
 
-    def __float__(self):
-        return float(self.value)
+    def set(
+        self,
+        value: Union[
+            float,
+            Deposit[float],
+            Force[float],
+            Freeze,
+            Release,
+            Immediate[float],
+        ],
+    ) -> None:
+        """Set the value of the simulation object using a :class:`float` value.
 
+        Args:
+            value: The value to set the simulation object to.
 
-class EnumObject(ModifiableObject):
-    """Specific object handle for enumeration signals and variables."""
+        Raises:
+            TypeError: If *value* is any type other than :class:`float`.
+        """
+        super().set(value)
 
-    def _set_value(self, value, call_sim):
-        """Set the value of the underlying simulation object to *value*.
+    @deprecated(
+        "`float(handle)` casts have been deprecated. Use `float(handle.value)` instead."
+    )
+    def __float__(self) -> float:
+        return self.value
 
-        This operation will fail unless the handle refers to a modifiable
-        object, e.g. net, signal or variable.
 
-        Args:
-            value (int): The value to drive onto the simulator object.
+class EnumObject(_NonIndexableValueObjectBase[int, int]):
+    """An enumeration simulation object.
 
-        Raises:
-            TypeError: If target has an unsupported type for
-                 integer value assignment.
-        """
-        value, set_action = self._check_for_set_action(value)
+    Inherits from :class:`SimHandleBase` and :class:`ValueObjectBase`.
+
+    This type is used when an enumerated-type simulation object is seen that aren't a "logic" or similar type.
+    The value of this object is represented with an :class:`int`.
+
+    For VHDL objects, the value being represented is the enumeration value at the integer index into the original ``type`` declaration,
+    as if it were a 1-based array.
+
+    For Verilog objects, enumerations are little more than named integer values.
+    There may be many enumeration values that a given :class:`int` value represents.
+    """
+
+    def __init__(self, handle: simulator.gpi_sim_hdl, path: Optional[str]) -> None:
+        super().__init__(handle, path)
 
-        if isinstance(value, BinaryValue):
-            value = int(value)
-        elif not isinstance(value, int):
+    def _set_value(
+        self,
+        value: int,
+        action: _GPISetAction,
+    ) -> None:
+        if not isinstance(value, int):
             raise TypeError(
-                "Unsupported type for enum value assignment: {} ({!r})".format(
-                    type(value), value
-                )
+                f"Unsupported type for enum value assignment: {type(value)} ({value!r})"
             )
 
         min_val, max_val = _value_limits(32, _Limits.UNSIGNED_NBIT)
         if min_val <= value <= max_val:
-            call_sim(self, self._handle.set_signal_val_int, set_action, value)
+            _schedule_write(self, self._handle.set_signal_val_int, action, value)
         else:
-            raise OverflowError(
-                "Int value ({!r}) out of range for assignment of enum signal ({!r})".format(
-                    value, self._name
-                )
+            raise ValueError(
+                f"Int value ({value!r}) out of range for assignment of enum signal ({self._name!r})"
             )
 
-    @ModifiableObject.value.getter
-    def value(self) -> int:
-        return self._handle.get_signal_val_long()
+    def get(self) -> int:
+        """Return the current value of the simulation object as an :class:`int`.
 
+        See :class:`EnumObject` for details on what :class:`int` values correspond to which enumeration values.
+        """
+        return self._handle.get_signal_val_long()
 
-class IntegerObject(ModifiableObject):
-    """Specific object handle for integer and enumeration signals and variables."""
-
-    def _set_value(self, value, call_sim):
-        """Set the value of the underlying simulation object to *value*.
-
-        This operation will fail unless the handle refers to a modifiable
-        object, e.g. net, signal or variable.
+    def set(
+        self,
+        value: Union[
+            int,
+            Deposit[int],
+            Force[int],
+            Freeze,
+            Release,
+            Immediate[int],
+        ],
+    ) -> None:
+        """Set the value of the simulation object using an :class:`int`.
+
+        See :class:`EnumObject` for details on what :class:`int` values correspond to which enumeration values.
 
         Args:
-            value (int): The value to drive onto the simulator object.
+            value: The value to set the simulation object to.
 
         Raises:
-            TypeError: If target has an unsupported type for
-                 integer value assignment.
+            TypeError: If *value* is any type other than :class:`int`.
+            ValueError: If *value* would not fit in a 32-bit signed integer.
 
-            OverflowError: If value is out of range for assignment
-                 of 32-bit IntegerObject.
+        .. versionchanged:: 2.0
+            Supplying too large of a value results in raising a :exc:`ValueError` instead of an :exc:`OverflowError`.
         """
-        value, set_action = self._check_for_set_action(value)
+        super().set(value)
+
+    @deprecated(
+        "`int(handle)` casts have been deprecated. Use `int(handle.value)` instead."
+    )
+    def __int__(self) -> int:
+        return int(self.value)
+
+
+class IntegerObject(_NonIndexableValueObjectBase[int, int]):
+    """An integer simulation object.
+
+    Inherits from :class:`SimHandleBase` and :class:`ValueObjectBase`.
 
-        if isinstance(value, BinaryValue):
-            value = int(value)
-        elif not isinstance(value, int):
+    Verilog types that map to this object:
+
+        * ``byte``
+        * ``shortint``
+        * ``int``
+        * ``longint``
+
+    This type should not be used for the 4-state integer types ``integer`` and ``time``.
+
+    VHDL types that map to this object:
+
+        * ``integer``
+        * ``natural``
+        * ``positive``
+
+    Objects that use this type are assumed to be two's complement 32-bit integers with 2-state (``0`` and ``1``) bits.
+    """
+
+    def __init__(self, handle: simulator.gpi_sim_hdl, path: Optional[str]) -> None:
+        super().__init__(handle, path)
+
+    def _set_value(
+        self,
+        value: int,
+        action: _GPISetAction,
+    ) -> None:
+        if not isinstance(value, int):
             raise TypeError(
-                "Unsupported type for integer value assignment: {} ({!r})".format(
-                    type(value), value
-                )
+                f"Unsupported type for integer value assignment: {type(value)} ({value!r})"
             )
 
         min_val, max_val = _value_limits(32, _Limits.SIGNED_NBIT)
         if min_val <= value <= max_val:
-            call_sim(self, self._handle.set_signal_val_int, set_action, value)
+            _schedule_write(self, self._handle.set_signal_val_int, action, value)
         else:
-            raise OverflowError(
-                "Int value ({!r}) out of range for assignment of integer signal ({!r})".format(
-                    value, self._name
-                )
+            raise ValueError(
+                f"Int value ({value!r}) out of range for assignment of integer signal ({self._name!r})"
             )
 
-    @ModifiableObject.value.getter
-    def value(self) -> int:
+    def get(self) -> int:
+        """Return the current value of the simulation object as an :class:`int`."""
         return self._handle.get_signal_val_long()
 
+    def set(
+        self,
+        value: Union[
+            int,
+            Deposit[int],
+            Force[int],
+            Freeze,
+            Release,
+            Immediate[int],
+        ],
+    ) -> None:
+        """Set the the value of the simulation object using an :class:`int` value.
 
-class StringObject(ModifiableObject):
-    """Specific object handle for String variables."""
+        Args:
+            value: The value to set the simulation object to.
 
-    def _set_value(self, value, call_sim):
-        """Set the value of the underlying simulation object to *value*.
+        Raises:
+            TypeError: If *value* is any type other than :class:`int`.
+            ValueError: If *value* would not fit in a 32-bit signed integer.
 
-        This operation will fail unless the handle refers to a modifiable
-        object, e.g. net, signal or variable.
+        .. versionchanged:: 2.0
+            Supplying too large of a value results in raising a :exc:`ValueError` instead of an :exc:`OverflowError`.
+        """
+        super().set(value)
 
-        Args:
-            value (bytes): The value to drive onto the simulator object.
+    @deprecated(
+        "`int(handle)` casts have been deprecated. Use `int(handle.value)` instead."
+    )
+    def __int__(self) -> int:
+        return self.value
 
-        Raises:
-            TypeError: If target has an unsupported type for
-                 string value assignment.
 
-        .. versionchanged:: 1.4
-            Takes :class:`bytes` instead of :class:`str`.
-            Users are now expected to choose an encoding when using these objects.
-            As a convenience, when assigning :class:`str` values, ASCII encoding will be used as a safe default.
+class StringObject(
+    _NonIndexableValueObjectBase[bytes, bytes],
+    _RangeableObjectMixin,
+):
+    """A string simulation object.
 
-        """
-        value, set_action = self._check_for_set_action(value)
-
-        if isinstance(value, str):
-            warnings.warn(
-                "Handles on string objects will soon not accept `str` objects. "
-                "Please use a bytes object by encoding the string as you see fit. "
-                "`str.encode('ascii')` is typically sufficient.",
-                DeprecationWarning,
-                stacklevel=2,
-            )
-            value = value.encode("ascii")  # may throw UnicodeEncodeError
+    Inherits from :class:`SimHandleBase` and :class:`ValueObjectBase`.
+
+    This type is used when a ``string`` (VHDL or Verilog) simulation object is seen.
+    """
 
-        if not isinstance(value, bytes):
+    def __init__(self, handle: simulator.gpi_sim_hdl, path: Optional[str]) -> None:
+        super().__init__(handle, path)
+
+    def _set_value(
+        self,
+        value: bytes,
+        action: _GPISetAction,
+    ) -> None:
+        if not isinstance(value, (bytes, bytearray)):
             raise TypeError(
-                "Unsupported type for string value assignment: {} ({!r})".format(
-                    type(value), value
-                )
+                f"Unsupported type for string value assignment: {type(value)} ({value!r})"
             )
+        _schedule_write(self, self._handle.set_signal_val_str, action, value)
 
-        call_sim(self, self._handle.set_signal_val_str, set_action, value)
-
-    @ModifiableObject.value.getter
-    def value(self) -> bytes:
+    def get(self) -> bytes:
+        """Return the current value of the simulation object as a :class:`bytes`."""
         return self._handle.get_signal_val_str()
 
-    def _emit_str_warning(self):
-        warnings.warn(
-            "`str({t})` is deprecated, and in future will return `{t}._path`. "
-            "To access the `bytes` value of this handle, use `{t}.value`.".format(
-                t=type(self).__qualname__
-            ),
-            FutureWarning,
-            stacklevel=3,
-        )
+    def set(
+        self,
+        value: Union[
+            bytes,
+            Deposit[bytes],
+            Force[bytes],
+            Freeze,
+            Release,
+            Immediate[bytes],
+        ],
+    ) -> None:
+        """Set the value of the simulation object with a :class:`bytes` or :class:`bytearray` value.
+
+        When *value*'s length is less than the simulation object's,
+        the value is padded with NUL (``'\0'``) characters up to the appropriate length.
+        When the value's length is greater than the simulation object's,
+        the value is truncated without a NUL terminator to the appropriate length,
+        without warning.
+
+        Strings in both Verilog and VHDL are byte arrays without any particular encoding.
+        Encoding must be done to turn Python strings into byte arrays.
+        Because `there are many encodings <https://docs.python.org/3/library/codecs.html#standard-encodings>`_,
+        this step is left up to the user.
+
+        An example of how encoding and decoding could be accomplished using an ASCII string.
+
+        .. code-block:: python
+
+            # lowercase a string
+            value = dut.string_handle.value.decode("ascii")
+            value = value.lower()
+            dut.string_handle.value = value.encode("ascii")
 
-    def __str__(self):
-        self._emit_str_warning()
-        return self.value.decode("ascii")
+        Args:
+            value: The value to set the simulation object to.
 
+        Raises:
+            TypeError: If *value* is any type other than :class:`bytes`.
+
+        .. versionchanged:: 1.4
+            Takes :class:`bytes` instead of :class:`str`.
+            Users are now expected to choose an encoding when using these objects.
+        """
+        super().set(value)
 
-_handle2obj = {}
+    @deprecated(
+        '`str(handle)` casts have been deprecated. Use `handle.value.decode("ascii")` instead.'
+    )
+    def __str__(self) -> str:
+        return self.value.decode("ascii")
 
 
-def SimHandle(handle, path=None):
+_ConcreteHandleTypes = Union[
+    HierarchyObject,
+    HierarchyArrayObject[SimHandleBase],
+    LogicObject,
+    LogicArrayObject,
+    ArrayObject[Any, ValueObjectBase[Any, Any]],
+    RealObject,
+    IntegerObject,
+    EnumObject,
+    StringObject,
+]
+
+
+_handle2obj: Dict[
+    simulator.gpi_sim_hdl,
+    _ConcreteHandleTypes,
+] = {}
+
+_type2cls: Dict[int, Type[_ConcreteHandleTypes]] = {
+    simulator.MODULE: HierarchyObject,
+    simulator.STRUCTURE: HierarchyObject,
+    simulator.PACKED_STRUCTURE: LogicArrayObject,
+    simulator.LOGIC: LogicObject,
+    simulator.LOGIC_ARRAY: LogicArrayObject,
+    simulator.NETARRAY: ArrayObject[Any, ValueObjectBase[Any, Any]],
+    simulator.REAL: RealObject,
+    simulator.INTEGER: IntegerObject,
+    simulator.ENUM: EnumObject,
+    simulator.STRING: StringObject,
+    simulator.GENARRAY: HierarchyArrayObject[SimHandleBase],
+    simulator.PACKAGE: HierarchyObject,
+}
+
+
+def _make_sim_object(
+    handle: simulator.gpi_sim_hdl, path: Optional[str] = None
+) -> SimHandleBase:
     """Factory function to create the correct type of `SimHandle` object.
 
     Args:
-        handle (int): The GPI handle to the simulator object.
-        path (str): Path to this handle, ``None`` if root.
+        handle: The GPI handle to the simulator object.
+        path: Path to this handle.
 
     Returns:
-        The `SimHandle` object.
+        An appropriate :class:`SimHandleBase` object.
 
     Raises:
         NotImplementedError: If no matching object for GPI type could be found.
     """
-    _type2cls = {
-        simulator.MODULE: HierarchyObject,
-        simulator.STRUCTURE: HierarchyObject,
-        simulator.REG: ModifiableObject,
-        simulator.NET: ModifiableObject,
-        simulator.NETARRAY: NonHierarchyIndexableObject,
-        simulator.REAL: RealObject,
-        simulator.INTEGER: IntegerObject,
-        simulator.ENUM: EnumObject,
-        simulator.STRING: StringObject,
-        simulator.GENARRAY: HierarchyArrayObject,
-    }
 
     # Enforce singletons since it's possible to retrieve handles avoiding
     # the hierarchy by getting driver/load information
-    global _handle2obj
     try:
         return _handle2obj[handle]
     except KeyError:
         pass
 
     t = handle.get_type()
-
-    # Special case for constants
-    if handle.get_const() and t not in [
-        simulator.MODULE,
-        simulator.STRUCTURE,
-        simulator.NETARRAY,
-        simulator.GENARRAY,
-    ]:
-        obj = ConstantObject(handle, path, t)
-        _handle2obj[handle] = obj
-        return obj
-
     if t not in _type2cls:
         raise NotImplementedError(
-            "Couldn't find a matching object for GPI type %s(%d) (path=%s)"
-            % (handle.get_type_string(), t, path)
+            f"Couldn't find a matching object for GPI type {handle.get_type_string()}({t}) (path={path})"
         )
     obj = _type2cls[t](handle, path)
     _handle2obj[handle] = obj