proxystore.store.ref

proxystore/store/ref.py

Object ownership and borrowing with proxies.

This module implements Rust-like ownership and borrowing rules for Python objects in shared memory using transparent object proxies. Thus, these proxy reference types are similar to the type returned by Store.proxy()---they will resolve to an object in the global store. However, these proxy references enforce additional rules.

1. Each target object of type T in the global store has an associated OwnedProxy[T].
2. There can only be one OwnedProxy[T] for any target in the global store.
3. When an OwnedProxy[T] goes out of scope (e.g., gets garbage collected), the associated target is removed from the global store.

Tip

The docstrings often use T to refer to both the target object in the global store and the type of the target object.

An OwnedProxy[T] can be borrowed without relinquishing ownership. This requires two additional rules.

1. At any given time, you can have either one mutable reference to the target, a RefMutProxy[T], or any number of immutable references, a RefProxy[T].
2. References must always be valid. I.e., you cannot delete an OwnedProxy[T] while it has been borrowed via a RefProxy[T] or RefMutProxy[T].

All three reference types (OwnedProxy[T], RefProxy[T], and RefMutProxy[T]) behave like an instance of T, forwarding operations on themselves to a locally cached instance of T.

BaseRefProxyError

Bases: Exception

Base exception type for proxy references.

MutableBorrowError

Bases: BaseRefProxyError

Exception raised when violating borrowing rules.

ReferenceNotOwnedError

Bases: BaseRefProxyError

Exception raised when invoking an operation on a non-owned reference.

ReferenceInvalidError

Bases: BaseRefProxyError

Exception raised when a reference instance has been invalidated.

ReferenceBorrowedError

Bases: BaseRefProxyError

Exception raised when moving an owned reference that is borrowed.

BaseRefProxy

BaseRefProxy(
    factory: FactoryType[T],
    *,
    cache_defaults: bool = False,
    target: T | None = None,
)

Bases: Proxy[T]

Base reference proxy type.

This base type adds some features to Proxy that are shared by all the reference types:

1. Valid flag. When invalidated, the proxy will raise a ReferenceInvalidError when accessing the wrapped target object.
2. Disable copy() and deepcopy() support to prevent misuse of the API. Generally, borrow() or clone() should be used instead.

Source code in proxystore/store/ref.py

def __init__(
    self,
    factory: FactoryType[T],
    *,
    cache_defaults: bool = False,
    target: T | None = None,
) -> None:
    object.__setattr__(self, '__proxy_valid__', True)
    super().__init__(factory, cache_defaults=cache_defaults, target=target)

OwnedProxy

OwnedProxy(
    factory: FactoryType[T],
    *,
    cache_defaults: bool = False,
    target: T | None = None,
)

Bases: BaseRefProxy[T]

Represents ownership over an object in a global store.

This class maintains reference counts of the number of immutable and mutable borrows of this proxy. The target object will be evicted from the store by a background thread shortly after this proxy goes out of scope (this is handled via __del__ and an atexit handler). Store.close() and the exit of the program wait for these evictions.

Pickling this proxy moves ownership to the pickled copy and invalidates this proxy, so an owned proxy can only be pickled once. Use borrow() or clone() to send the object to more than one place.

Parameters:

• factory (FactoryType[T]) –

  StoreFactory used to resolve the target object from the store.

• cache_defaults (bool, default: False ) –

  Precompute and cache the __proxy_default_class__ and __proxy_default_hash__ attributes of the proxy instance from target. Ignored if target is not provided.

• target (T | None, default: None ) –

  Optionally preset the target object.

Source code in proxystore/store/ref.py

def __init__(
    self,
    factory: FactoryType[T],
    *,
    cache_defaults: bool = False,
    target: T | None = None,
) -> None:
    object.__setattr__(self, '__proxy_ref_count__', 0)
    object.__setattr__(self, '__proxy_ref_mut_count__', 0)
    super().__init__(factory, cache_defaults=cache_defaults, target=target)
    _track_ref(self)
    # Started here because __del__ cannot start a thread.
    evictions.start()

RefProxy

RefProxy(
    factory: FactoryType[T],
    *,
    cache_defaults: bool = False,
    owner: OwnedProxy[T] | None = None,
    target: T | None = None,
)

Bases: BaseRefProxy[T]

Represents a borrowed reference to an object in the global store.

Parameters:

• factory (FactoryType[T]) –

  StoreFactory used to resolve the target object from the store.

• cache_defaults (bool, default: False ) –

  Precompute and cache the __proxy_default_class__ and __proxy_default_hash__ attributes of the proxy instance from target. Ignored if target is not provided.

• owner (OwnedProxy[T] | None, default: None ) –

  Proxy which has ownership over the target object. This reference will keep the owner alive while this borrowed reference is alive. In the event this borrowed reference was initialized in a different address space from the proxy with ownership, then owner will be None.

• target (T | None, default: None ) –

  Optionally preset the target object.

Source code in proxystore/store/ref.py

def __init__(
    self,
    factory: FactoryType[T],
    *,
    cache_defaults: bool = False,
    owner: OwnedProxy[T] | None = None,
    target: T | None = None,
) -> None:
    object.__setattr__(self, '__proxy_owner__', owner)
    super().__init__(factory, cache_defaults=cache_defaults, target=target)
    _track_ref(self)

RefMutProxy

RefMutProxy(
    factory: FactoryType[T],
    *,
    cache_defaults: bool = False,
    owner: OwnedProxy[T] | None = None,
    target: T | None = None,
)

Bases: BaseRefProxy[T]

Represents a borrowed mutable reference to an object in the global store.

Parameters:

• factory (FactoryType[T]) –

  StoreFactory used to resolve the target object from the store.

• cache_defaults (bool, default: False ) –

  Precompute and cache the __proxy_default_class__ and __proxy_default_hash__ attributes of the proxy instance from target. Ignored if target is not provided.

• owner (OwnedProxy[T] | None, default: None ) –

  Proxy which has ownership over the target object. This reference will keep the owner alive while this borrowed reference is alive. In the event this borrowed reference was initialized in a different address space from the proxy with ownership, then owner will be None.

• target (T | None, default: None ) –

  Optionally preset the target object.

Source code in proxystore/store/ref.py

def __init__(
    self,
    factory: FactoryType[T],
    *,
    cache_defaults: bool = False,
    owner: OwnedProxy[T] | None = None,
    target: T | None = None,
) -> None:
    object.__setattr__(self, '__proxy_owner__', owner)
    super().__init__(factory, cache_defaults=cache_defaults, target=target)
    _track_ref(self)

borrow

borrow(
    proxy: OwnedProxy[T], *, populate_target: bool = True
) -> RefProxy[T]

Borrow T by creating an immutable reference of T.

Note

This mutates proxy.

Parameters:

• proxy (OwnedProxy[T]) –

  Proxy reference to borrow.

• populate_target (bool, default: True ) –

  If the target of proxy has already been resolved, copy the reference to the target into the returned proxy such that the returned proxy is already resolved.

Raises:

• ReferenceNotOwnedError –

  if proxy is not an OwnedProxy instance.

• MutableBorrowError –

  if proxy has already been mutably borrowed.

Source code in proxystore/store/ref.py

def borrow(
    proxy: OwnedProxy[T],
    *,
    populate_target: bool = True,
) -> RefProxy[T]:
    """Borrow `T` by creating an immutable reference of `T`.

    Note:
        This mutates `proxy`.

    Args:
        proxy: Proxy reference to borrow.
        populate_target: If the target of `proxy` has already been resolved,
            copy the reference to the target into the returned proxy such that
            the returned proxy is already resolved.

    Raises:
        ReferenceNotOwnedError: if `proxy` is not an
            [`OwnedProxy`][proxystore.store.ref.OwnedProxy] instance.
        MutableBorrowError: if `proxy` has already been mutably borrowed.
    """
    if not isinstance(proxy, OwnedProxy):
        raise ReferenceNotOwnedError('Only owned references can be borrowed.')
    if object.__getattribute__(proxy, '__proxy_ref_mut_count__') > 0:
        raise MutableBorrowError('Proxy was already borrowed as mutable.')
    object.__setattr__(
        proxy,
        '__proxy_ref_count__',
        object.__getattribute__(proxy, '__proxy_ref_count__') + 1,
    )
    ref_proxy = RefProxy(proxy.__proxy_factory__, owner=proxy)
    if populate_target:
        _copy_attributes(proxy, ref_proxy)
    return ref_proxy

mut_borrow

mut_borrow(
    proxy: OwnedProxy[T], *, populate_target: bool = True
) -> RefMutProxy[T]

Mutably borrow T by creating a mutable reference of T.

Note

This mutates proxy.

Parameters:

• proxy (OwnedProxy[T]) –

  Proxy reference to borrow.

• populate_target (bool, default: True ) –

  If the target of proxy has already been resolved, copy the reference to the target into the returned proxy such that the returned proxy is already resolved.

Raises:

• ReferenceNotOwnedError –

  if proxy is not an OwnedProxy instance.

• MutableBorrowError –

  if proxy has already been borrowed (mutable/immutable).

Source code in proxystore/store/ref.py

def mut_borrow(
    proxy: OwnedProxy[T],
    *,
    populate_target: bool = True,
) -> RefMutProxy[T]:
    """Mutably borrow `T` by creating a mutable reference of `T`.

    Note:
        This mutates `proxy`.

    Args:
        proxy: Proxy reference to borrow.
        populate_target: If the target of `proxy` has already been resolved,
            copy the reference to the target into the returned proxy such that
            the returned proxy is already resolved.

    Raises:
        ReferenceNotOwnedError: if `proxy` is not an
            [`OwnedProxy`][proxystore.store.ref.OwnedProxy] instance.
        MutableBorrowError: if `proxy` has already been borrowed
            (mutable/immutable).
    """
    if not isinstance(proxy, OwnedProxy):
        raise ReferenceNotOwnedError('Only owned references can be borrowed.')
    if object.__getattribute__(proxy, '__proxy_ref_mut_count__') > 0:
        raise MutableBorrowError('Proxy was already borrowed as mutable.')
    if object.__getattribute__(proxy, '__proxy_ref_count__') > 0:
        raise MutableBorrowError('Proxy was already borrowed as immutable.')
    object.__setattr__(
        proxy,
        '__proxy_ref_mut_count__',
        object.__getattribute__(proxy, '__proxy_ref_mut_count__') + 1,
    )
    ref_proxy = RefMutProxy(proxy.__proxy_factory__, owner=proxy)
    if populate_target:
        _copy_attributes(proxy, ref_proxy)
    return ref_proxy

clone

clone(proxy: OwnedProxy[T]) -> OwnedProxy[T]

Clone the target object.

Creates a new copy of T in the global store by copying the stored object, and returns a new owner of the copy. The copy is made when clone() is called, so it does not change if proxy is updated or evicted later. The returned proxy is not resolved, even if proxy is, so it resolves its own copy from the store when first used.

Raises:

• ReferenceNotOwnedError –

  if proxy is not an OwnedProxy instance.

• MutableBorrowError –

  if proxy is mutably borrowed, because the changes of the borrow may not be written to the store yet.

• ProxyResolveMissingKeyError –

  if the object of proxy is not in the store.

Source code in proxystore/store/ref.py

def clone(proxy: OwnedProxy[T]) -> OwnedProxy[T]:
    """Clone the target object.

    Creates a new copy of `T` in the global store by copying the stored
    object, and returns a new owner of the copy. The copy is made when
    `clone()` is called, so it does not change if `proxy` is updated or
    evicted later. The returned proxy is not resolved, even if `proxy` is,
    so it resolves its own copy from the store when first used.

    Raises:
        ReferenceNotOwnedError: if `proxy` is not an
            [`OwnedProxy`][proxystore.store.ref.OwnedProxy] instance.
        MutableBorrowError: if `proxy` is mutably borrowed, because the
            changes of the borrow may not be written to the store yet.
        ProxyResolveMissingKeyError: if the object of `proxy` is not in the
            store.
    """
    if not isinstance(proxy, OwnedProxy):
        raise ReferenceNotOwnedError('Only owned references can be cloned.')
    if object.__getattribute__(proxy, '__proxy_ref_mut_count__') > 0:
        raise MutableBorrowError(
            'Cannot clone a proxy which is borrowed as mutable.',
        )
    factory = proxy.__proxy_factory__
    store = factory.get_store()
    new_factory: StoreFactory[Any, T] = StoreFactory(
        store._copy(factory.key),
        store_config=store.config(),
        evict=factory.evict,
    )
    owned = OwnedProxy(new_factory)
    # The default class and hash are copied so the clone can be used in
    # isinstance() and hash() without resolving it.
    _copy_attributes(proxy, owned, populate_target=False)
    return owned

into_owned

into_owned(
    proxy: Proxy[T], *, populate_target: bool = True
) -> OwnedProxy[T]

Convert a basic proxy into an owned proxy.

Warning

It is the caller's responsibility to ensure that proxy has not been copied already.

Note

This will unset the evict flag on the proxy.

Parameters:

• proxy (Proxy[T]) –

  Proxy to convert.

• populate_target (bool, default: True ) –

  If the target of proxy has already been resolved, copy the reference to the target into the returned proxy such that the returned proxy is already resolved.

Raises:

• ValueError –

  if proxy is already a BaseRefProxy instance.

• ProxyStoreFactoryError –

  If the proxy's factory is not an instance of StoreFactory.

Source code in proxystore/store/ref.py

def into_owned(
    proxy: Proxy[T],
    *,
    populate_target: bool = True,
) -> OwnedProxy[T]:
    """Convert a basic proxy into an owned proxy.

    Warning:
        It is the caller's responsibility to ensure that `proxy` has not been
        copied already.

    Note:
        This will unset the `evict` flag on the proxy.

    Args:
        proxy: Proxy to convert.
        populate_target: If the target of `proxy` has already been resolved,
            copy the reference to the target into the returned proxy such that
            the returned proxy is already resolved.

    Raises:
        ValueError: if `proxy` is already a
            [`BaseRefProxy`][proxystore.store.ref.BaseRefProxy] instance.
        ProxyStoreFactoryError: If the proxy's factory is not an instance of
            [`StoreFactory`][proxystore.store.factory.StoreFactory].
    """
    if type(proxy) in (OwnedProxy, RefProxy, RefMutProxy):
        # We don't use isinstance to prevent resolving the proxy.
        raise ValueError(
            'Only a base proxy can be converted into an owned proxy.',
        )
    factory = proxy.__proxy_factory__
    if not isinstance(factory, StoreFactory):
        raise ProxyStoreFactoryError(
            'The proxy must contain a factory with type '
            f'{StoreFactory.__name__}. {type(factory).__name__} '
            'is not supported.',
        )
    factory.evict = False
    owned_proxy = OwnedProxy(factory)
    if populate_target:
        _copy_attributes(proxy, owned_proxy)
    return owned_proxy

update

update(proxy: OwnedProxy[T] | RefMutProxy[T]) -> None

Update the global copy of the target.

Note

If the proxy has not been resolved, there is nothing to update and this function is a no-op.

Warning

This will not invalidate already cached copies of the global target.

Parameters:

• proxy (OwnedProxy[T] | RefMutProxy[T]) –

  Proxy containing a modified local copy of the target to use as the new global value.

Raises:

• MutableBorrowError –

  if proxy has been mutably borrowed.

• NotImplementedError –

  if the connector of the store used to create the proxy does not implement the DeferrableConnector protocol.

• ReferenceNotOwnedError –

  if proxy is not an OwnedProxy or RefMutProxy instance.

Source code in proxystore/store/ref.py

def update(proxy: OwnedProxy[T] | RefMutProxy[T]) -> None:
    """Update the global copy of the target.

    Note:
        If the proxy has not been resolved, there is nothing to update and
        this function is a no-op.

    Warning:
        This will not invalidate already cached copies of the global target.

    Args:
        proxy: Proxy containing a modified local copy of the target to use
            as the new global value.

    Raises:
        MutableBorrowError: if `proxy` has been mutably borrowed.
        NotImplementedError: if the `connector` of the `store` used to create
            the proxy does not implement the
            [`DeferrableConnector`][proxystore.connectors.protocols.DeferrableConnector]
            protocol.
        ReferenceNotOwnedError: if `proxy` is not an
            [`OwnedProxy`][proxystore.store.ref.OwnedProxy] or
            [`RefMutProxy`][proxystore.store.ref.RefMutProxy] instance.
    """
    if not isinstance(proxy, (OwnedProxy, RefMutProxy)):
        raise ReferenceNotOwnedError('Reference is an immutable borrow.')
    if isinstance(proxy, OwnedProxy) and (
        object.__getattribute__(proxy, '__proxy_ref_mut_count__') > 0
        or object.__getattribute__(proxy, '__proxy_ref_count__') > 0
    ):
        raise MutableBorrowError(
            'OwnedProxy has been borrowed. Cannot mutate.',
        )
    if not is_resolved(proxy):
        return

    store = proxy.__proxy_factory__.get_store()
    try:
        store._set(proxy.__proxy_factory__.key, proxy.__proxy_wrapped__)
    except NotImplementedError as e:  # pragma: no cover
        raise NotImplementedError(
            'Mutating the global copy of the value requires a connector '
            'type that supports set().',
        ) from e