6.3. Invoking Stored Procedures Asynchronously

Documentation

VoltDB Home » Documentation » Using VoltDB
< previoustable of contentsnext >

6.3. Invoking Stored Procedures Asynchronously

Calling stored procedures synchronously simplifies the program logic because your client application waits for the procedure to complete before continuing. However, for high performance applications looking to maximize throughput, it is better to queue stored procedure invocations asynchronously.

Asynchronous Invocation

To invoke stored procedures asynchronously, use the callProcedure() method with an additional first argument, a callback that will be notified when the procedure completes (or an error occurs). For example, to invoke a NewCustomer() stored procedure asynchronously, the call to callProcedure() might look like the following:

client.callProcedure(new MyCallback(),
                     "NewCustomer",
                     firstname,
                     lastname,
                     custID};

The following are other important points to note when making asynchronous invocations of stored procedures:

  • Asynchronous calls to callProcedure() return control to the calling application as soon as the procedure call is queued.

  • If the database server queue is full, callProcedure() will block until it is able to queue the procedure call. This is a condition known as backpressure. This situation does not normally happen unless the database cluster is not scaled sufficiently for the workload or there are abnormal spikes in the workload. See Section 6.5.3, “Writing a Status Listener to Interpret Other Errors” for more information.

  • Once the procedure is queued, any subsequent errors (such as an exception in the stored procedure itself or loss of connection to the database) are returned as error conditions to the callback procedure.

Callback Implementation

The callback procedure (MyCallback() in this example) is invoked after the stored procedure completes on the server. The following is an example of a callback procedure implementation:

static class MyCallback implements ProcedureCallback {
  @Override
  public void clientCallback(ClientResponse clientResponse) {
    if (clientResponse.getStatus() != ClientResponse.SUCCESS) {
       System.err.println(clientResponse.getStatusString());
   } else {
       myEvaluateResultsProc(clientResponse.getResults());
    }
  }
}

The callback procedure is passed the same ClientResponse structure that is returned in a synchronous invocation. ClientResponse contains information about the results of execution. In particular, the methods getStatus() and getResults() let your callback procedure determine whether the stored procedure was successful and evaluate the results of the procedure.

The VoltDB Java client is single threaded, so callback procedures are processed one at a time. Consequently, it is a good practice to keep processing in the callback to a minimum, returning control to the main thread as soon as possible. If more complex processing is required by the callback, creating a separate thread pool and spawning worker methods on a separate thread from within the asynchronous callback is recommended.

< previoustable of contentsnext >