Google Cloud C++ Client  2.2.1
C++ Client Library for Google Cloud Platform
async_operation.h
Go to the documentation of this file.
1 // Copyright 2020 Google LLC
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // https://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
15 #ifndef GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_ASYNC_OPERATION_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_ASYNC_OPERATION_H
17 
18 #include "google/cloud/version.h"
19 #include <grpcpp/grpcpp.h>
20 #include <chrono>
21 
22 namespace google {
23 namespace cloud {
25 
26 /**
27  * The result of an async timer operation.
28  *
29  * Callbacks for async timers will receive an object of this class.
30  */
32  std::chrono::system_clock::time_point deadline;
33  bool cancelled;
34 };
35 
36 /**
37  * Represents a pending asynchronous operation.
38  *
39  * It can either be a simple RPC, or a more complex operation involving
40  * potentially many RPCs, sleeping and processing.
41  */
43  public:
44  virtual ~AsyncOperation() = default;
45 
46  /**
47  * Requests that the operation be canceled.
48  */
49  virtual void Cancel() = 0;
50 };
51 
52 namespace internal {
53 
54 /**
55  * Represents an AsyncOperation which gRPC understands.
56  *
57  * When applications create an asynchronous operation with a `CompletionQueue`
58  * they provide a callback to be invoked when the operation completes
59  * (successfully or not). The completion queue type-erases the callback and
60  * hides it in a class derived from `AsyncOperation`. A shared pointer to the
61  * `AsyncOperation` is returned by the completion queue so library developers
62  * can cancel the operation if needed.
63  *
64  * @note Sub-classes of `AsyncGrpcOperation` should snapshot the prevailing
65  * `Options` during construction, and restore them using an `OptionsSpan`
66  * during `Notify()` and `Cancel()` callbacks.
67  */
68 class AsyncGrpcOperation : public AsyncOperation {
69  public:
70  /**
71  * Notifies the application that the operation completed.
72  *
73  * Derived classes wrap the callbacks provided by the application and invoke
74  * the callback when this virtual member function is called.
75  *
76  * @param ok opaque parameter returned by `grpc::CompletionQueue`. The
77  * semantics defined by gRPC depend on the type of operation, therefore the
78  * operation needs to interpret this parameter based on those semantics.
79  * @return Whether the operation is completed (e.g. in case of streaming
80  * response, it would return true only after the stream is finished).
81  */
82  virtual bool Notify(bool ok) = 0;
83 };
84 
85 } // namespace internal
87 } // namespace cloud
88 } // namespace google
89 
90 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_ASYNC_OPERATION_H