github.com/dolthub/dolt/go@v0.40.5-0.20240520175717-68db7794bea6/store/nbs/chunk_fetcher.go (about)

     1  // Copyright 2024 Dolthub, Inc.
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //     http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  package nbs
    16  
    17  import (
    18  	"context"
    19  
    20  	"github.com/dolthub/dolt/go/store/hash"
    21  )
    22  
    23  // A ChunkFetcher is a batching, stateful, potentially concurrent interface to
    24  // fetch lots of chunks from a ChunkStore. A caller is expected to call
    25  // `Get()` and `Recv()` concurrently. Unless there is an error, for every
    26  // single Hash passed to Get, a corresponding Recv() call will deliver the
    27  // contents of the chunk. When a caller is done with a ChunkFetcher, they
    28  // should call |CloseSend()|. After CloseSend, all requested hashes have been
    29  // delivered through Recv(), Recv() will return `io.EOF`.
    30  //
    31  // A ChunkFetcher should be Closed() when it is no longer needed. In non-error
    32  // cases, this will typically be after Recv() has delivererd io.EOF. If Close
    33  // is called before Recv() delivers io.EOF, there is no guarantee that all
    34  // requested chunks will be delivered through Recv().
    35  //
    36  // In contrast to interfaces to like GetManyCompressed on ChunkStore, if the
    37  // chunk is not in the underlying database, then Recv() will return an
    38  // nbs.CompressedChunk with its Hash set, but with empty contents.
    39  //
    40  // Other than an io.EOF from Recv(), any |error| returned from any method
    41  // indicates an underlying problem wtih fetching requested chunks from the
    42  // ChunkStore. A ChunkFetcher is single use and cannot be used effectively
    43  // after an error is returned.
    44  type ChunkFetcher interface {
    45  	Get(ctx context.Context, hashes hash.HashSet) error
    46  
    47  	CloseSend() error
    48  
    49  	Recv(context.Context) (CompressedChunk, error)
    50  
    51  	Close() error
    52  }