Asynchronous Calls in the DB Interface Module
In the DB Interface Module, the calls listed in
Table 14 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 14 – Potentially asynchronous functions in the DB Interface Module
Class | Functions |
| RWDBResult execute();
RWDBReader reader(); |
| RWDBStatus beginTransaction();
RWDBStatus commitTransaction();
RWDBResult executeSQL();
RWDBStatus isolation();
RWDBStatus rollbackTransaction(); |
| RWDBStatus deleteRow();
RWDBStatus fetchRow();
RWDBStatus insertRow();
RWDBStatus unbind();
RWDBStatus updateRow(); |
| RWDBStatus createProcedure();
RWDBStatus createTable();
RWDBStatus createView();
RWDBCursor cursor();
RWDBTable dbStoredProcedures();
RWDBTable dbTables();
RWDBStatus dropView(); |
| RWDBResult execute(); |
| RWDBResult execute(); |
| RWDBOSql& cancel();
void execute();
RWDBOSql& fetch();
RWDBOSql& fetchReturnParams();
RWDBValue returnValue(); |
| void* operator()(); |
| RWDBTable table(); |
| RWDBCursor cursor();
RWDBResult execute();
RWDBReader reader(); |
| RWDBStatus drop();
RWDBResult execute();
RWDBStatus fetchReturnParams(); |
| RWDBStatus addColumn();
RWDBStatus createIndex();
RWDBCursor cursor();
RWDBStatus drop();
RWDBStatus dropColumn();
RWDBStatus dropIndex();
RWDBStatus grant();
RWDBReader reader();
RWDBStatus revoke(); |
| 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.
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.
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.