edit-icon download-icon

Asynchronous interface

Last Updated: Mar 20, 2018

Create a client

  • Create directly (use a Table Store endpoint to create a client)

    1. Endpoint ep("YourEndpoint", "YourInstance");
    2. Credential cr("AccessKeyId", "AccessKeySecret");
    3. ClientOptions opts;
    4. AsyncClient* client = NULL;
    5. Optional<OTSError> res = AsyncClient::create(client, ep, cr, opts);

    Note: Avoid using the AccessKey of your primary account to access Table Store. We recommend using a temporary token or the AccessKey of a sub-account. If you use a temporary STS token, the credential object in the aforementioned code must be changed to: Credential cr("AccessKeyId", "AccessKeySecret", "SecurityToken");.

    See Synchronous interfaces for more information on the configuration items.

  • Construct from SyncClient

    1. SyncClient& sync = ...;
    2. AsyncClient* async = AsyncClient::create(sync);

Table operations

A table operation is used as an example here to demonstrate how to use an asynchronous interface.

Preparations

Two functions must be ready:

  • Request object

    The function signature of listTable is as follows:

    1. void listTable(
    2. ListTableRequest&,
    3. const std::tr1::function<void(
    4. ListTableRequest&, util::Optional<OTSError>&, ListTableResponse&)>&);

    The first parameter is a mutable reference (in contrast, a synchronous interface is an immutable reference). After listTable() is returned (at this point, the list table operation has not yet been completed), the passed-in ListTableRequest object may be changed or destructed, opening the door for subtle errors that are difficult to investigate. To avoid issues of this sort, asynchronous clients transfer (not copy) the contents of the passed-in request object to internal storage. This means that after calling listTable(), passed-in objects can be changed.

  • Callback function

    The callback function does not return any value. The three types of receive parameters are as follows:

    • Request object. This is the request object that is passed in when the user calls listTable(). After callback, the asynchronous client no longer needs the request object and it is returned to the user’s callback function in the form of a mutable reference. This allows the user to transfer out the contents of the request object.

    • Error object wrapped in optional . If no errors exist, the present() method of this object returns false.

    • Response object. As with request objects, response objects are also returned to the callback function in the form of a mutable reference. If an error exists, the response object must be a valid object (one that can be destructed). However, the contents of the response object are undefined.

Note:

  • The asynchronous client makes sure that every request callback is only called one time.
  • Theoretically, a callback function can be called before the listTable() is returned.

Example

  1. void listTableCallback(
  2. ListTableRequest&,
  3. Optional<OTSError>& err,
  4. ListTableResponse& resp)
  5. {
  6. if (err.present()) {
  7. // Error in processing
  8. } else {
  9. const IVector<string>& xs = resp.tables();
  10. for(int64_t i = 0; i < xs.size(); ++i) {
  11. cout << xs[i] << endl;
  12. }
  13. }
  14. }
  15. void listTable(AsyncClient& client)
  16. {
  17. ListTableRequest req;
  18. client.listTable(req, listTableCallback);
  19. }
Thank you! We've received your feedback.