Package io.deephaven.engine.table.impl.util

Class FunctionGeneratedTableFactory

java.lang.Object
io.deephaven.engine.table.impl.util.FunctionGeneratedTableFactory
public class FunctionGeneratedTableFactory extends Object
An abstract table that represents the result of a function.

The table will run by regenerating the full values (using the tableGenerator Function passed in). Whenever the generator produces a table, the result table takes on those new values and fires an appropriate update for a full-replacement (all previous rows removed, all new rows added, with no modifications or shifts), even when the generated data is identical to the previous cycle's. When a retaining-last supplier declines to produce a table, a non-blink result is retained with no update.

When copying data (the default), the generated rows are copied into a flat, contiguous RowSet. When copying is disabled (see FunctionGeneratedTableSpec.copyData()), the output instead delegates to the generated table's column sources via SwitchColumnSource, adopting the generated table's RowSet: the added rows of each update are exactly the generated table's RowSet, and the removed rows are the previous cycle's RowSet. Because the generated table's RowSet and ColumnSources are used directly, a refreshing generated table's column sources must be immutable.

When FunctionGeneratedTableSpec.blinkTable() is set, the result is presented as a blink table: each refresh removes the previous rows and adds the newly generated rows (also a full replacement), and a cycle that produces no rows clears the result. Rows generated in one update cycle are removed on the next cycle whether or not the generator runs again, so the result honors the blink contract that rows are visible for exactly one cycle.

The generator function must produce a V2 table, and the table definition must not change between invocations.

If you are transforming a table, you should generally prefer to use the regular table operations as opposed to this factory, because they are capable of performing some operations incrementally. However, for small tables this might prove to require less development effort.

  • Method Details

    • create

      public static Table create(@NotNull @NotNull Supplier<Table> tableGenerator, int refreshIntervalMs)
      Create a table that refreshes based on the value of your function, automatically called every refreshIntervalMs.
      Parameters:
      tableGenerator - a function returning a table to copy into the output table
      Returns:
      a ticking table (assuming refreshIntervalMs is > 0) generated by tableGenerator

    • create

      public static Table create(@NotNull @NotNull Supplier<Table> tableGenerator, @NotNull @NotNull Table... sourceTables)
      Create a table that refreshes based on the value of your function, automatically called in a dependency-respecting way when at least one of the sourceTables tick.

      Note that the tableGenerator may access data in the sourceTables but should not perform further table operations on them without careful handling. Table operations may be memoized, and it is possible that a table operation will return a table created by a previous invocation of the same operation. Since that result will not have been included in the sourceTables, it's not automatically treated as a dependency for purposes of determining when it's safe to invoke tableGenerator, allowing races to exist between accessing the operation result and that result's own update processing. It's best to include all dependencies directly in sourceTables, or only compute on-demand inputs under a LivenessScope.

      Parameters:
      tableGenerator - a function returning a table to copy into the output table
      sourceTables - The query engine does not know the details of your function inputs. If you are dependent on a ticking table tables in your tableGenerator function, you can add it to this list so that the function will be recomputed on each tick.
      Returns:
      a ticking table (assuming sourceTables have been specified) generated by tableGenerator

    • create

      public static Table create(@NotNull @NotNull FunctionGeneratedTableSpec spec)
      Create a table according to the supplied FunctionGeneratedTableSpec.
      Parameters:
      spec - the specification describing how the table is generated and refreshed
      Returns:
      a table generated by the spec's supplier