diff options
Diffstat (limited to 'src/third_party/wiredtiger/src/docs/async.dox')
| -rw-r--r-- | src/third_party/wiredtiger/src/docs/async.dox | 135 |
1 files changed, 0 insertions, 135 deletions
diff --git a/src/third_party/wiredtiger/src/docs/async.dox b/src/third_party/wiredtiger/src/docs/async.dox deleted file mode 100644 index fcc0e590369..00000000000 --- a/src/third_party/wiredtiger/src/docs/async.dox +++ /dev/null @@ -1,135 +0,0 @@ -/*! @m_page{{c,java},async,Asynchronous operations} - -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: - -- getter/setters for key and value fields -- encoding of fields to store in the data source -- methods to modify and retrieve specific data (for example, insert and update) -- a method to compact a table - -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. - -@section async_config Configuring asynchronous operations - -To perform asynchronous operations, the application must first include -the \c 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: - -@snippet ex_async.c async example connection - -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. - -@section async_alloc Allocating an asynchronous operations handle - -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: - -@snippet ex_async.c async handle allocation - -To aid the application in matching up an asynchronous operation with a -subsequent call to the callback function, every handle contains a unique -\c uint64_t identifier and ::WT_ASYNC_OPTYPE type. The \c identifier is -assigned when the handle is allocated and the \c type is assigned when -the asynchronous operation is queued. - -To retrieve the id, use the WT_ASYNC_OP::get_id method: - -@snippet ex_async.c async get identifier - -To retrieve the ::WT_ASYNC_OPTYPE type, use the WT_ASYNC_OP::get_type method: - -@snippet ex_async.c async get type - -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_ref{ex_async.c}: - -@snippet ex_async.c async example callback implementation - -@m_if{java} -@snippet ex_async.c async example callback implementation part 2 -@m_endif - -@section async_operations Executing asynchronous operations - -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: - -@snippet ex_async.c async insert - -For example, the following code does an asynchronous search of the -table: - -@snippet ex_async.c async search - -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. - -@snippet ex_async.c async compaction - -@section async_flush Waiting for outstanding operations to complete - -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. - -@snippet ex_async.c async flush - -Because WT_CONNECTION::close implicitly does a WT_CONNECTION::async_flush, -the call is not required in all applications. - -@section async_transactions Asynchronous operations and transactions - -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. - -*/ |