deephaven.liveness_scope¶

This module gives the users a finer degree of control over when to clean up unreferenced nodes in the query update graph instead of solely relying on garbage collection.

Examples

Use the liveness_scope() function to produce a simple liveness scope that will be used only within a with expression or as a decorator.

with liveness_scope() as scope:
    ticking_table = some_ticking_source()
    table = ticking_table.snapshot().join(table=other_ticking_table, on=...)
    scope.preserve(table)
return table

@liveness_scope
def get_values():
    ticking_table = some_ticking_source().last_by("Sym")
    return dhnp.to_numpy(ticking_table)

Use the LivenessScope type for greater control, allowing a scope to be opened more than once, and to release the resources that it manages when the scope will no longer be used.

def make_table_and_scope(a: int):
    scope = LivenessScope()
    with scope.open():
        ticking_table = some_ticking_source().where(f"A={a}")
        return some_ticking_table, scope

t1, s1 = make_table_and_scope(1)
# .. wait for a while
s1.release()
t2, s2 = make_table_and_scope(2)
# etc

In both cases, the scope object has a few methods that can be used to more directly manage liveness referents:

scope.preserve(obj) will preserve the given instance in the next scope outside the specified scope instance
scope.manange(obj) will directly manage the given instance in the specified scope. Take care not to double-manage objects when using in conjunction with a with block or function decorator.
scope.unmanage(obj) will stop managing the given instance. This can be used regardless of how the instance was managed to begin with.

class LivenessScope[source]¶

Bases: _BaseLivenessScope

A LivenessScope automatically manages reference counting of tables and other query resources that are created in it. Any created instances must have release() called on them to correctly free resources that have been managed.

j_object_type¶: alias of LivenessScope

manage(referent)¶

Explicitly manage the given java object in this scope. Must only be passed a Java LivenessReferent, or a Python wrapper around a LivenessReferent

Parameters:: referent (Union[JObjectWrapper, jpy.JType]) – the object to manage by this scope
Return type:: None

Returns: None

Raises:: DHError if the referent isn't a LivenessReferent, or if it is no longer live –

open()[source]¶

Uses this scope for the duration of a with block, automatically managing all resources created in the block.

Returns: None, to allow changes in the future.

Return type:: Iterator[None]

preserve(referent)¶

Preserves a query graph node (usually a Table) to keep it live for the outer scope.

Parameters:: referent (Union[JObjectWrapper, jpy.JType]) – an object to preserve in the next outer liveness scope
Raises:: DHError if the object isn't a liveness node, or this instance isn't currently at the stop of the stack –
Return type:: None

release()[source]¶

Closes the LivenessScope and releases all the managed resources.

Raises:: DHError if this instance has been released too many times –
Return type:: None

unmanage(referent)¶

Explicitly unmanage the given java object from this scope. Must only be passed a Java LivenessReferent, or a Python wrapper around a LivenessReferent

Parameters:: referent (Union[JObjectWrapper, jpy.JType]) – the object to unmanage from this scope
Return type:: None

Returns: None

Raises:: DHError if the referent isn't a LivenessReferent, or if it is no longer live –

class SimpleLivenessScope[source]¶

Bases: _BaseLivenessScope

A SimpleLivenessScope automatically manages reference counting of tables and other query resources that are created in it. Instances are created through calling liveness_scope() in a with block or as a function decorator, and will be disposed of automatically.

j_object_type¶: alias of LivenessScope

manage(referent)¶

Explicitly manage the given java object in this scope. Must only be passed a Java LivenessReferent, or a Python wrapper around a LivenessReferent

Parameters:: referent (Union[JObjectWrapper, jpy.JType]) – the object to manage by this scope
Return type:: None

Returns: None

Raises:: DHError if the referent isn't a LivenessReferent, or if it is no longer live –

preserve(referent)¶

Preserves a query graph node (usually a Table) to keep it live for the outer scope.

Parameters:: referent (Union[JObjectWrapper, jpy.JType]) – an object to preserve in the next outer liveness scope
Raises:: DHError if the object isn't a liveness node, or this instance isn't currently at the stop of the stack –
Return type:: None

unmanage(referent)¶

Explicitly unmanage the given java object from this scope. Must only be passed a Java LivenessReferent, or a Python wrapper around a LivenessReferent

Parameters:: referent (Union[JObjectWrapper, jpy.JType]) – the object to unmanage from this scope
Return type:: None

Returns: None

Raises:: DHError if the referent isn't a LivenessReferent, or if it is no longer live –

is_liveness_referent(referent)[source]¶

Returns True if the provided object is a LivenessReferent, and so can be managed by a LivenessScope. :type referent: Union[JObjectWrapper, JType] :param referent: the object that may be a LivenessReferent

Return type:: bool
Returns:: True if the object is a LivenessReferent, False otherwise.

liveness_scope()[source]¶

Creates and opens a LivenessScope for running a block of code. Use this function to wrap a block of code using a with statement.

For the duration of the with block, the liveness scope will be open and any liveness referents created will be manged by it automatically.

Yields:: a SimpleLivenessScope
Return type:: Iterator[SimpleLivenessScope]