Google Cloud Bigtable C++ Client  1.32.1
A C++ Client Library for Google Cloud Bigtable
Classes | Public Member Functions | Protected Member Functions | List of all members
google::cloud::bigtable::v1::MutationBatcher Class Reference

Objects of this class pack single row mutations into bulk mutations. More...

#include <google/cloud/bigtable/mutation_batcher.h>

Classes

struct  Options
 Configuration for MutationBatcher. More...
 

Public Member Functions

 MutationBatcher (Table table, Options options=Options())
 
virtual ~MutationBatcher ()=default
 
std::pair< future< void >, future< Status > > AsyncApply (CompletionQueue &cq, SingleRowMutation mut)
 Asynchronously apply mutation. More...
 
future< void > AsyncWaitForNoPendingRequests ()
 Asynchronously wait until all submitted mutations complete. More...
 

Protected Member Functions

virtual future< std::vector< FailedMutation > > AsyncBulkApplyImpl (Table &table, BulkMutation &&mut)
 

Detailed Description

Objects of this class pack single row mutations into bulk mutations.

In order to maximize throughput when applying a lot of mutations to Cloud Bigtable, one should pack the mutations in BulkMutations. This class helps in doing so. Create a MutationBatcher and use MutationBatcher::AsyncApply() to apply a large stream of mutations to the same Table. Objects of this class will efficiently create batches of SingleRowMutations and maintain multiple batches "in flight".

This class also offers an easy-to-use flow control mechanism to avoid unbounded growth in its internal buffers.

Applications must provide a CompletionQueue to (asynchronously) execute these operations. The application is responsible of executing the CompletionQueue event loop in one or more threads.

Thread-safety
Instances of this class are guaranteed to work when accessed concurrently from multiple threads.

Definition at line 57 of file mutation_batcher.h.

Constructor & Destructor Documentation

◆ MutationBatcher()

google::cloud::bigtable::v1::MutationBatcher::MutationBatcher ( Table  table,
Options  options = Options() 
)
inlineexplicit

Definition at line 94 of file mutation_batcher.h.

◆ ~MutationBatcher()

virtual google::cloud::bigtable::v1::MutationBatcher::~MutationBatcher ( )
virtualdefault

Member Function Documentation

◆ AsyncApply()

std::pair< future< void >, future< Status > > google::cloud::bigtable::v1::MutationBatcher::AsyncApply ( CompletionQueue &  cq,
SingleRowMutation  mut 
)

Asynchronously apply mutation.

The mutation will most likely be batched together with others to optimize for throughput. As a result, latency is likely to be worse than Table::AsyncApply.

Parameters
mutthe mutation. Note that this function takes ownership (and then discards) the data in the mutation. In general, a SingleRowMutation can be used to modify and/or delete multiple cells, across different columns and column families.
cqthe completion queue that will execute the asynchronous calls, the application must ensure that one or more threads are blocked on cq.Run().
Returns
admission and completion futures

The completion future will report the mutation's status once it completes.

The admission future should be used for flow control. In order to bound the memory usage used by MutationBatcher, one should not submit more mutations before the admission future is satisfied. Note that while the future is often already satisfied when the function returns, applications should not assume that this is always the case.

One should not make assumptions on which future will be satisfied first.

This quasi-synchronous example shows the intended use:

bigtable::MutationBatcher batcher(bigtable::Table(...args...));
bigtable::CompletionQueue cq;
std::thread cq_runner([]() { cq.Run(); });
while (HasMoreMutations()) {
auto admission_completion = batcher.AsyncApply(cq, GenerateMutation());
auto& admission_future = admission_completion.first;
auto& completion_future = admission_completion.second;
completion_future.then([](future<Status> completion_status) {
// handle mutation completion asynchronously
});
// Potentially slow down submission not to make buffers in
// MutationBatcher grow unbounded.
admission_future.get();
}
// Wait for all mutations to complete
batcher.AsyncWaitForNoPendingRequests().get();
cq.Shutdown();
cq_runner.join();

Definition at line 60 of file mutation_batcher.cc.

◆ AsyncBulkApplyImpl()

future< std::vector< FailedMutation > > google::cloud::bigtable::v1::MutationBatcher::AsyncBulkApplyImpl ( Table table,
BulkMutation &&  mut 
)
protectedvirtual

Definition at line 161 of file mutation_batcher.cc.

◆ AsyncWaitForNoPendingRequests()

future< void > google::cloud::bigtable::v1::MutationBatcher::AsyncWaitForNoPendingRequests ( )

Asynchronously wait until all submitted mutations complete.

Returns
a future which will be satisfied once all mutations submitted before calling this function finish; if there are no such operations, the returned future is already satisfied.

Definition at line 99 of file mutation_batcher.cc.