8.2 Caching with RWDBInserter

Caching features in DBTools.h++ are provided by the classes RWDBReader and RWDBInserter. To enable the caching features when producing an RWDBInserter, we pass a cache size of n > 1 to its constructor. The following example shows how to use an inserter with a cache size of 5.

RWDBConnection aConn = aDb.connection();
RWDBInserter inserter = myTable.inserter(5);                // 1
inserter << 0;                                              // 2
inserter.execute(aConn);                                    // 3
inserter << 1;                                              // 4
inserter.execute(aConn);                                    // 5
inserter << 2;                                              // 6
inserter.execute(aConn);                                    // 7
inserter << 3;                                              // 8
inserter.execute(aConn);                                    // 9
inserter << 4;                                              //10
inserter.execute(aConn);                                    //11
inserter.flush();                                           //12

In //1, we produce an inserter, with a cache size of 5, from an existing RWDBTable object.

In //2-//11, we execute the inserter, inserting a new value between each execution as we would with an inserter that does no caching. The only differences between coding this example and coding an example that does not use a cached inserter is in //1, where we set the cache size, and in //12, where we flush the contents of the cache.

Now let us look at what happens to the inserter internally. In //1, when we create the inserter with a cache size of 5, the inserter creates an internal buffer big enough to hold five rows of data. In //2, we shift a row of data into the inserter. This row is stored in the first location in the inserter's internal buffers, and the inserter notes that it has cached 1 row.

When we execute in //3, the inserter doesn't send the row that was just shifted into itself to the database. Instead, the inserter compares the number of rows already cached to the cache size it was assigned at construction. Since the cache is not at capacity--in fact, it holds only one row at this point--the inserter returns immediately to the application.

In //6-//7, the value of 2 is shifted into the inserter, and the inserter is executed again. The inserter notes that it has now cached 2 rows, and returns to the application. This pattern is repeated in //8-//11. By the time we reach //11, the inserter has cached five rows. At this point, the number of rows cached is equal to the cache size, and the inserter sends all five cached rows to the database server at once. By using the inserter in this way, the application saves the cost of four network round trips.

As we mentioned previously, the inserter's flush() method is invoked in //12. Actually, the flush operation was performed in //11 because the method is invoked automatically whenever the cache reaches its assigned capacity. In this example, the cache reached capacity in //11. But what if it didn't? Or what if the cache size in //1 was 10? We invoke flush() in //12 because we recommend explicit invocation as good programming practice. Explicit invocation ensures that all data is sent to the server.