WiredTiger supports asynchronous operations; as an example of where this can be useful, a server application handling requests from a network as fast as possible may want its worker threads to initiate a unit of work and then immediately respond to the next request, rather than waiting for the results of the first request.
WiredTiger supports asynchronous operations through the WT_ASYNC_OP handle. The work unit represented by the WT_ASYNC_OP handle is queued by the application and performed by an internal WiredTiger worker thread. When the work unit completes, the WiredTiger thread makes a callback to notify the application the operation is finished, along with providing any results and error values.
The asynchronous operation handle operates in a manner similar to a WT_CURSOR handle. An asynchronous operation includes:
The WT_ASYNC_OP handle does not survive after the callback function returns into the WiredTiger library. When the application callback returns the handle is returned to the system pool. The application callback must copy out any key, value or other information that it needs before the callback function returns.
To perform asynchronous operations, the application must first include the async
configuration option when wiredtiger_open is called. Additional configuration parameters include the number of WiredTiger worker threads created to handle the incoming queue of operations and the maximum number of simultaneous asynchronous operations that are expected.
For example, the following configures an application for asynchronous operations, with a maximum of 10 asynchronous operations and 2 supporting threads:
If the number of requests exceeds the configured maximum number, a WT_ASYNC_OP handle won't immediately be available and an error will be returned to the application when it attempts to allocate a handle. If the number of configured worker threads are unable to keep up with the requests, requests will be forced to wait for worker threads to become available.
A WT_ASYNC_OP handle is allocated using the WT_CONNECTION::async_new_op method. This method takes an existing object URI and a callback. For example:
To aid the application in matching up an asynchronous operation with a subsequent call to the callback function, every handle contains a unique uint64_t
identifier and WT_ASYNC_OPTYPE type. The identifier
is assigned when the handle is allocated and the type
is assigned when the asynchronous operation is queued.
To retrieve the id, use the WT_ASYNC_OP::get_id method:
To retrieve the WT_ASYNC_OPTYPE type, use the WT_ASYNC_OP::get_type method:
WiredTiger only allows a limited number of method calls back into the library using the WT_ASYNC_OP handle, while in the callback function. The application is allowed to retrieve than handle's key, value, identifier and the operation type from the WT_ASYNC_OP handle.
Here is a complete example callback function implementation, from the example program ex_async.c:
The WT_ASYNC_OP handle behaves similarly to the WT_CURSOR handle, that is, the key and value are initialized and then an operation is performed.
For example, the following code does an asynchronous insert into the table:
For example, the following code does an asynchronous search of the table:
When a database contains multiple tables, it may be desired to compact several tables in parallel without having to manage separate threads to each call WT_SESSION::compact. Alternatively, compacting several tables serially may take much longer. The WT_ASYNC_OP::compact method allows the application to compact multiple objects asynchronously.
The WT_CONNECTION::async_flush method can be used to wait for all previous operations to complete. When that call returns, all previously queued operations are guaranteed to have been completed and their callback functions have returned.
Because WT_CONNECTION::close implicitly does a WT_CONNECTION::async_flush, the call is not required in all applications.
Each asynchronous worker thread operates in its own session, executing a single asynchronous operation with the context of the session's transaction. Therefore, there is no way to combine multiple, related updates into a single transaction when using asynchronous operations.
The transaction is committed if the operation was successful and the application callback returns success, otherwise the transaction is rolled back.