Asynchronous Calls in the DB Interface Module

DB Interface Module User's Guide
Rogue Wave web site: Home Page | Main Documentation Page

12.7 Asynchronous Calls in the DB Interface Module

In the DB Interface Module, the calls listed in Table 13 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 13: Potentially asynchronous functions in the DB Interface Module

Class	Functions
*RWDBCompoundSelector*	`RWDBResult execute();` `RWDBReader reader();`
*RWDBConnection*	`RWDBStatus beginTransaction();` `RWDBStatus commitTransaction();` `RWDBResult executeSQL();` `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 dbStoredProcedures();` `RWDBTable dbTables();` `RWDBStatus dropView();`
*RWDBDeleter*	`RWDBResult execute();`
*RWDBInserter*	`RWDBResult execute();`
*RWDBOSql*	`RWDBOSql& cancel();` `void execute();` `RWDBOSql& fetch();` `RWDBOSql& fetchReturnParams();` `RWDBValue returnValue();`
*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();`
*RWDBUpdater*	`RWDBResult execute();`

Please note that although the table indicates all the possible asynchronous calls in the DB Interface Module, some DB Access Modules 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 doesn't have asynchronous support for transaction calls such as commit, rollback, and begin. The DB Interface Module doesn't attempt to simulate asynchronous behavior for any calls lacking direct native API support.

12.7.1 Running Many Asynchronous Calls on a Single RWDBConnection

The APIs of many database vendors do not permit use of a connection during an asynchronous call in that connection. The DB Interface Module 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 the DB Interface Module.

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

12.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 the DB Interface Module 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.

The Rogue Wave name and logo, and SourcePro, are registered trademarks of Rogue Wave Software. All other trademarks are the property of their respective owners.
Provide feedback to Rogue Wave about its documentation.