Google Cloud C++ Client  1.42.0
C++ Client Library for Google Cloud Platform
idempotency.h
Go to the documentation of this file.
1 // Copyright 2022 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_IDEMPOTENCY_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_IDEMPOTENCY_H
17 
18 #include "google/cloud/status.h"
19 #include "google/cloud/version.h"
20 #include <chrono>
21 #include <memory>
22 
23 namespace google {
24 namespace cloud {
26 
27 /**
28  * Whether a request is [idempotent][wikipedia-idempotence].
29  *
30  * When a RPC fails with a retryable error, the `google-cloud-cpp` client
31  * libraries automatically retry the RPC **if** the RPC is
32  * [idempotent][wikipedia-idempotence]. For each service, the library define
33  * a policy that determines whether a given request is idempotent. In many
34  * cases this can be determined statically, for example, read-only operations
35  * are always idempotent. In some cases, the contents of the request may need to
36  * be examined to determine if the operation is idempotent. For example,
37  * performing operations with pre-conditions, such that the pre-conditions
38  * change when the operation succeed, is typically idempotent.
39  *
40  * Applications may override the default idempotency policy, though we
41  * anticipate that this would be needed only in very rare circumstances. A few
42  * examples include:
43  *
44  * - In some services deleting "the most recent" entry may be idempotent if the
45  * system has been configured to keep no history or versions, as the deletion
46  * may succeed only once. In contrast, deleting "the most recent entry" is
47  * **not** idempotent if the system keeps multiple versions. Google Cloud
48  * Storage or Bigtable can be configured either way.
49  * - In some applications, creating a duplicate entry may be acceptable as the
50  * system will deduplicate them later. In such systems it may be preferable
51  * to retry the operation even though it is not idempotent.
52  *
53  * [wikipedia-idempotence]: https://en.wikipedia.org/wiki/Idempotence
54  */
55 enum class Idempotency {
56  /// The operation is idempotent and can be retried after a transient failure.
58  /// The operation is not idempotent and should **not** be retried after a
59  /// transient failure.
61 };
62 
64 } // namespace cloud
65 } // namespace google
66 
67 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_IDEMPOTENCY_H