Source code for jitx.proxy

"""Copy-on-Write / Proxy Utility Functions.

The JITX API uses a proxy concept to facilitate memoization, copy-on-write, and
for tracking object scene graph entries. It is used to identify objects that
are functionally the same, but created in different places of the design, such
as a port. A paramtric port is only possible to net to another port object if
they share an origin, which functionally means that they share the same
underlying instantiated object, and neither has been modified after they've
been created.

The proxy mechanism is transparent to normal use of JITX, if you find yourself
poking around here and you're not writing some kind of integration or export
plugin where you want to determine if two objects have a common base instance,
you should probably ask yourself if you're in the right place.

Note the type(proxy) will be reported as Proxy for a large set of JITX objects.
Use `typeof` from this module instead if you need the true type of an object.
"""

import jitx._structural




def origin[T](p: T) -> T:
    """Determine the origin of a given object.

    If a proxy has not been modified, its origin is the same as the origin of
    its parent. If a proxy object _has_ been modified, its origin is itself.

    This can be useful to check if multiple proxies share and are functionally
    equivalent to a common ancestor.

    If the object is not a proxy, the object itself will be returned, making
    the function safe to call on any object."""
    if isinstance(p, jitx._structural.Proxy):
        return jitx._structural.Proxy.forkbase(p)
    return p





def typeof(p) -> type:
    """Return the actual type of the underlying object. This can be called on
    any object, if it's a Proxy object, the underlying object type will be
    returned. Similarly if the object is not a proxy, its type will be
    returned, making the function safe to call on any object."""
    return jitx._structural.Proxy.type(p)