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.
To invoke stored procedures asynchronously, use the callProcedureAsync() method.
The procedure call will be queued internally for transmission. The immediate return value is a standard
Java CompletableFuture object, which will be "completed" when the procedure completes
(or an error occurs). For example, to invoke a
NewCustomer() stored procedure asynchronously, the call to callProcedureAsync() might look
like the following:
DocumentationCompletableFuture<ClientResponse> future =
client.callProcedureAsync("NewCustomer",
firstname,
lastname,
custID};To handle the eventual ClientResponse, you can use any of the features of CompletableFuture
that Java provides. These include awaiting completion with get(), declaring a handler for the
eventual completion with handle(), and so on.
The following are other important points to note when making asynchronous invocations of stored procedures:
Calls to callProcedureAsync() return control to the calling application as soon as the
procedure call is locally queued.
Errors that occur before the procedure call is queued may be reported via a Java exception. The calling application should include appropriate handling.
Once the procedure is queued, any subsequent error (such as an exception in the stored procedure itself or loss
of connection to the database) is returned via the CompletableFuture.
There is a limit on the local queue size, after which calls will be rejected. The default queue size
is 1000 calls, but this can be changed with Client2Config. Robust applications should
either ensure they can never exceed the local queue size, or implement appropriate handling. You can
configure a handler to receive notifications when the queue is approaching capacity; see the
requestBackpressureHandler() method of Client2Config.
If the database server queue is full, transmission is temporarily suspended. This condition,
known as network backpressure (distinct from request-queue backpressure), is handled internally
to the Client2 API. 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.6.3, “Writing Handlers to Interpret Other Errors” for more information.
The CompletableFuture is "completed normally" when the called procedure has been
executed on the cluster, and has returned a response. It can also be completed, in this case "exceptionally",
when an error or timeout occurs.
Normal completion allows access to a ClientResponse structure, the same structure
that is returned in a synchronous invocation. The ClientResponse contains information
about the results of execution. In particular, the methods getStatus() and getResults()
let you determine whether the stored procedure was successful and evaluate the results of the procedure.
Exceptional completion does not have a ClientResponse structure; the exception
itself conveys the error information.
Completions themselves can be processed synchronously or asynchronously, using the standard facilities of
CompletableFuture. The VoltDB Java client is single threaded, so synchronous completions are
processed one at a time. Consequently, it is good practice to keep synchronous completion processing to a minimum,
returning control to the main thread as soon as possible. If more complex processing is required, use one of
the available methods for handling the completion asynchronously.