All Downloads are FREE. Search and download functionalities are using the official Maven repository.

io.deephaven.engine.table.ChunkSource Maven / Gradle / Ivy

//
// Copyright (c) 2016-2024 Deephaven Data Labs and Patent Pending
//
package io.deephaven.engine.table;

import io.deephaven.chunk.Chunk;
import io.deephaven.chunk.ChunkType;
import io.deephaven.chunk.WritableChunk;
import io.deephaven.chunk.attributes.Any;
import io.deephaven.util.datastructures.LongRangeConsumer;
import io.deephaven.engine.rowset.RowSequence;
import org.jetbrains.annotations.NotNull;

/**
 *
 * @param  the attribute describing what kind of chunks are produced by this source
 */
public interface ChunkSource extends FillContextMaker, GetContextMaker {

    ChunkSource[] ZERO_LENGTH_CHUNK_SOURCE_ARRAY = new ChunkSource[0];

    FillContext DEFAULT_FILL_INSTANCE = new FillContext() {
        @Override
        public boolean supportsUnboundedFill() {
            return true;
        }
    };

    /**
     * Get the most suitable {@link ChunkType} for use with this ChunkSource.
     *
     * @return The ChunkType
     */
    ChunkType getChunkType();

    /**
     * Returns a chunk of data corresponding to the keys from the given {@link RowSequence}.
     *
     * @param context A context containing all mutable/state related data used in retrieving the Chunk. In particular,
     *        the Context may be used to provide a Chunk data pool
     * @param rowSequence An {@link RowSequence} representing the keys to be fetched
     * @return A chunk of data corresponding to the keys from the given {@link RowSequence}
     *
     * @apiNote
     *          

* The returned chunk belongs to the ColumnSource and may be mutated as result of calling getChunk again * under the same context or as a result of the column source itself being mutated. The callee is not * supposed to keep references to the chunk beyond the scope of the call. *

*

* Post-condition: The retrieved values start at position 0 in the chunk. *

*

* Post-condition: destination.size() will be equal to rowSequence.size() *

*/ Chunk getChunk(@NotNull GetContext context, @NotNull RowSequence rowSequence); /** * Same as {@link #getChunk(GetContext, RowSequence)}, except that you pass in the begin and last keys representing * the begin and last (inclusive) keys of a single range rather than an {@link RowSequence}. Typically you want to * call this only if you don't have an {@link RowSequence}, such as during an * {@link RowSequence#forAllRowKeyRanges(LongRangeConsumer)} call. In this case, it allows you to avoid creating an * intermediary {@link RowSequence} object. * * @param context A context containing all mutable/state related data used in retrieving the Chunk. In particular, * the Context may be used to provide a Chunk data pool * @param firstKey The beginning key (inclusive) of the range to fetch in the chunk * @param lastKey The last key (inclusive) of the range to fetch in the chunk * * @apiNote *

* [beginKey,lastRowKey] must be a range that exists in this ChunkSource. This is unchecked. *

*

* Post-condition: The retrieved values start at position 0 in the chunk. *

*

* Post-condition: destination.size() will be equal to lastRowKey - beginKey + 1 *

*/ Chunk getChunk(@NotNull GetContext context, long firstKey, long lastKey); /** * Populates the given destination chunk with data corresponding to the keys from the given {@link RowSequence}. * * @param context A context containing all mutable/state related data used in retrieving the Chunk. * @param destination The chunk to be populated according to {@code rowSequence}. No assumptions shall be made about * the size of the chunk shall be made. The chunk will be populated from position [0,rowSequence.size()). * @param rowSequence An {@link RowSequence} representing the keys to be fetched * @apiNote *

* Post-condition: The retrieved values start at position 0 in the chunk. *

*

* Post-condition: destination.size() will be equal to rowSequence.size() *

*/ void fillChunk( @NotNull FillContext context, @NotNull WritableChunk destination, @NotNull RowSequence rowSequence); /** * Marker interface for {@link Context}s that are used in {@link #getChunk(GetContext, RowSequence)}. */ interface GetContext extends Context { } /** * Marker interface for {@link Context}s that are used in * {@link #fillChunk(FillContext, WritableChunk, RowSequence)}. */ interface FillContext extends Context { /** * Returns true if this Context contains internal state that limits its capacity to the originally requested * capacity. If false is returned, then fillChunk operations may be arbitrarily large. * * @return if this context has a limited capacity */ default boolean supportsUnboundedFill() { return false; } } /** * Sub-interface for ChunkSources that support previous value retrieval. * * @param */ interface WithPrev extends ChunkSource { WithPrev[] ZERO_LENGTH_CHUNK_SOURCE_WITH_PREV_ARRAY = new WithPrev[0]; // TODO: Deprecate or remove getPrevChunk and fillPrevChunk if/when we do away with getPrev methods /** * Returns a chunk of previous data corresponding to the keys from the given {@link RowSequence}. * * @param context A context containing all mutable/state related data used in retrieving the Chunk. In * particular, the Context may be used to provide a Chunk data pool * @param rowSequence An {@link RowSequence} representing the keys to be fetched * @return A chunk of data corresponding to the keys from the given {@link RowSequence} * @apiNote *

* The returned chunk belongs to the ColumnSource and may be mutated as result of calling getChunk * again under the same context or as a result of the column source itself being mutated. The callee is * not supposed to keep references to the chunk beyond the scope of the call. *

*

* Post-condition: The retrieved values start at position 0 in the chunk. *

* Post-condition: destination.size() will be equal to rowSequence.size() */ Chunk getPrevChunk(@NotNull GetContext context, @NotNull RowSequence rowSequence); /** * Same as {@link #getPrevChunk(GetContext, RowSequence)}, except that you pass in the begin and last keys * representing the begin and last (inclusive) keys of a single range rather than an {@link RowSequence}. */ Chunk getPrevChunk(@NotNull GetContext context, long firstKey, long lastKey); /** * Populates the given destination chunk with data corresponding to the keys from the given {@link RowSequence}. * * @param context A context containing all mutable/state related data used in retrieving the Chunk. * @param destination The chunk to be populated according to {@code rowSequence}. No assumptions shall be made * about the size of the chunk shall be made. The chunk will be populated from position * [0,rowSequence.size()). * @param rowSequence An {@link RowSequence} representing the keys to be fetched * @apiNote *

* Post-condition: The retrieved values start at position 0 in the chunk. *

*

* Post-condition: destination.size() will be equal to rowSequence.size() *

*/ void fillPrevChunk( @NotNull FillContext context, @NotNull WritableChunk destination, @NotNull RowSequence rowSequence); /** * @return a chunk source which accesses the previous values. */ ChunkSource getPrevSource(); } }




© 2015 - 2025 Weber Informatics LLC | Privacy Policy