10.7 DBTools.h++ Asynchronous Calls

In DBTools.h++, the calls listed in Table 12 have been adapted to behave asynchronously when executed using an asynchronous connection. Note that the following list includes only the names of the supported functions without their full signatures. All the overloaded methods of the listed functions that take an RWDBConnection as one of their parameters can behave asynchronously.

Table 12 -- Potentially asynchronous functions in DBTools.h++

Class	Functions
*RWDBCompoundSelector*	`RWDBReader` `reader();`
*RWDBConnection*	`RWDBStatus` `beginTransaction();` `RWDBStatus` `commitTransaction();` `RWDBStatus` `isolation();` `RWDBStatus` `rollbackTransaction();`
*RWDBCursor*	`RWDBStatus` `deleteRow();` `RWDBStatus` `fetchRow();` `RWDBStatus` `insertRow();` `RWDBStatus` `unbind();` `RWDBStatus` `updateRow();`
*RWDBDatabase*	`RWDBStatus` `createProcedure();` `RWDBStatus` `createTable();` `RWDBStatus` `createView();` `RWDBCursor` `cursor();` `RWDBTable` `dbTables();` `RWDBStatus` `dropView();` `RWDBResult` `executeSql();`
*RWDBDeleter*	`RWDBResult` `execute();`
*RWDBInserter*	`RWDBResult` `execute()`
*RWDBMemTable*	`RWDBReader` `reader();`
*RWDBReader*	`void*` `operator();`
*RWDBResult*	`RWDBTable` `table();`
*RWDBSelector*	`RWDBCursor` `cursor();` `RWDBResult` `execute();` `RWDBReader` `reader();`
*RWDBStoredProc*	`RWDBStatus` `drop();` `RWDBResult` `execute();` `RWDBStatus` `fetchReturnParams();`
*RWDBTable*	`RWDBStatus` `addColumn();` `RWDBStatus` `createIndex();` `RWDBCursor` `cursor();` `RWDBStatus` `drop();` `RWDBStatus` `dropColumn();` `RWDBStatus` `dropIndex();` `RWDBStatus` `grant();` `RWDBReader` `reader();` `RWDBStatus` `revoke();`
*RWDBTPtrMemTable*	`RWDBReader` `reader();`
*RWDBUpdater*	`RWDBResult` `execute();`

Please note that although the table indicates all the possible asynchronous calls in DBTools.h++, some access libraries may not support asynchronous behavior for all these functions. This is because the corresponding database API may not include asynchronous support for some types of calls. For example, Oracle OCI 7.2 doesn't have asynchronous support for transaction calls such as commit, rollback, and begin. DBTools.h++ doesn't attempt to simulate asynchronous behavior for any calls lacking direct native API support.

10.7.1 Running Many Asynchronous Calls on a Single RWDBConnection

Many database vendors' APIs do not permit use of a connection during an asynchronous call in that connection. DBTools.h++ generally clears the connection of pending work before executing the next command, but it doesn't check the connection state. This combination of factors may result in unpredictable behavior for applications using the same connection for multiple asynchronous calls. When this behavior occurs, error messages returned by the server are fielded to the application using the standard error handling model of DBTools.h++.

We recommend that applications use a unique asynchronous connection for each database call when running many asynchronous calls simultaneously against a database.

10.7.2 Performance Issues

An asynchronous call typically executes more code than a corresponding synchronous call. However, the advantage of asynchronous calls derives from the fact that in any computation the majority of time is spent in I/O rather than actual computation. In a synchronous call, the thread waits for the I/O to complete; in the asynchronous call, the thread is free to do its next job.

An asynchronous call in DBTools.h++ can improve the performance of an application if and only if the application can make better use of the thread while the asynchronous call is in progress. Otherwise, a synchronous call may prove to be faster. The following example illustrates the problem.

int
main() {
  RWDBDatabase aDb = RWDBManager::database(
                               "SYBASE_CT",
                               "sybase_server",
                               "sybase_user",
                               "password",
                               "DEMO_DB"
                      );

RWDBConnection asyncConn =
          aDb.connection(RWDBConnection::Asynchronous);        //1
   
  RWDBResult result = 
       aSyncConn.executeSql("create table X(y int)");          //2

  assert(result.isValid());                                    //3
  return 0;
}

This example is similar to the previous asynchronous example, except that the code does no useful work after the asynchronous call in //2. Note that in //3, it accesses the ::isValid method of the returned object, which blocks the thread and completes the asynchronous call. No useful work is done between the asynchronous call in //2 and completion of the call in //3.