Google Cloud C++ Client  2.4.0
C++ Client Library for Google Cloud Platform
Namespaces | Classes | Typedefs | Enumerations | Functions
google::cloud Namespace Reference

Contains all the Google Cloud C++ Library APIs. More...

Namespaces

 mocks
 Contains helpers for testing the Google Cloud C++ Client Libraries.
 

Classes

struct  AsyncTimerResult
 The result of an async timer operation. More...
 
class  AsyncOperation
 Represents a pending asynchronous operation. More...
 
class  AsyncStreamingReadWriteRpc
 A streaming read-write RPC. More...
 
class  BackgroundThreads
 A object representing the background threads available to a Client. More...
 
struct  EndpointOption
 Change the endpoint. More...
 
struct  UserAgentProductsOption
 User-agent products to include with each request. More...
 
struct  TracingComponentsOption
 Return whether tracing is enabled for the given component. More...
 
struct  UserProjectOption
 Specifies a project for quota and billing purposes. More...
 
struct  AuthorityOption
 Configure the "authority" attribute. More...
 
class  CompletionQueue
 Call the functor associated with asynchronous operations when they complete. More...
 
class  ConnectionOptions
 The configuration parameters for client connections. More...
 
class  Credentials
 An opaque representation of the authentication configuration. More...
 
struct  UnifiedCredentialsOption
 A wrapper to store credentials into an options. More...
 
struct  DelegatesOption
 Configure the delegates for MakeImpersonateServiceAccountCredentials() More...
 
struct  ScopesOption
 Configure the scopes for MakeImpersonateServiceAccountCredentials() More...
 
struct  AccessTokenLifetimeOption
 Configure the access token lifetime. More...
 
struct  CARootsFilePathOption
 Configures a custom CA (Certificates Authority) certificates file. More...
 
struct  ExperimentalTag
 An argument type to indicate experimental functions. More...
 
class  future
 Implement ISO/IEC TS 19571:2016 future<T>. More...
 
class  promise
 Implement promise<T> as defined in ISO/IEC TS 19571:2016. More...
 
class  future< void >
 Implement ISO/IEC TS 19571:2016 future for void. More...
 
class  promise< void >
 Specialize promise as defined in ISO/IEC TS 19571:2016 for void. More...
 
struct  GrpcCredentialOption
 The gRPC credentials used by clients configured with this object. More...
 
struct  GrpcNumChannelsOption
 The number of transport channels to create. More...
 
struct  GrpcChannelArgumentsOption
 A string-string map of arguments for grpc::ChannelArguments::SetString. More...
 
struct  GrpcChannelArgumentsNativeOption
 The native grpc::ChannelArguments object. More...
 
struct  GrpcTracingOptionsOption
 The TracingOptions to use when printing grpc protocol buffer messages. More...
 
struct  GrpcBackgroundThreadPoolSizeOption
 The size of the background thread pool. More...
 
struct  GrpcCompletionQueueOption
 The CompletionQueue to use for background gRPC work. More...
 
struct  GrpcBackgroundThreadsFactoryOption
 Changes the BackgroundThreadsFactory. More...
 
class  KmsKeyName
 This class identifies a Google Cloud KMS Key. More...
 
struct  LogRecord
 Represents a single log message. More...
 
class  LogBackend
 The logging backend interface. More...
 
class  LogSink
 A sink to receive log records. More...
 
struct  NullStream
 Implements operator<< for all types, without any effect. More...
 
class  Logger
 Define the class to capture a log message. More...
 
class  Logger< false >
 Define the logger for a disabled log level. More...
 
class  Options
 A class that holds option structs indexed by their type. More...
 
class  PollingPolicy
 Control the Cloud C++ client library behavior with respect to polling on long running operations. More...
 
class  GenericPollingPolicy
 Construct a polling policy from existing Retry and Backoff policies. More...
 
class  Project
 This class identifies a Cloud Project. More...
 
class  ErrorInfo
 Describes the cause of the error with structured details. More...
 
class  Status
 Represents success or an error with info about the error. More...
 
class  RuntimeStatusError
 A runtime error that wraps a google::cloud::Status. More...
 
class  StatusOr
 Holds a value or a Status indicating why there is no value. More...
 
class  StreamRange
 A StreamRange<T> is a range of StatusOr<T> where the end-of-stream is indicated by a non-OK Status. More...
 
class  TracingOptions
 The configuration parameters for RPC/protobuf tracing. More...
 

Typedefs

using BackoffPolicy = ::google::cloud::internal::BackoffPolicy
 The base class for backoff policies. More...
 
using ExponentialBackoffPolicy = google::cloud::internal::ExponentialBackoffPolicy
 A truncated exponential backoff policy with randomized periods. More...
 
using CommonOptionList = OptionList< EndpointOption, UserAgentProductsOption, TracingComponentsOption, UserProjectOption, AuthorityOption >
 A list of all the common options. More...
 
using UnifiedCredentialsOptionList = OptionList< AccessTokenLifetimeOption, CARootsFilePathOption, DelegatesOption, ScopesOption, UnifiedCredentialsOption >
 A list of options related to authentication. More...
 
using BackgroundThreadsFactory = std::function< std::unique_ptr< BackgroundThreads >()>
 
using GrpcOptionList = OptionList< GrpcCredentialOption, GrpcNumChannelsOption, GrpcChannelArgumentsOption, GrpcChannelArgumentsNativeOption, GrpcTracingOptionsOption, GrpcBackgroundThreadPoolSizeOption, GrpcCompletionQueueOption, GrpcBackgroundThreadsFactoryOption >
 A list of all the gRPC options. More...
 
using IamUpdater = std::function< absl::optional< google::iam::v1::Policy >(google::iam::v1::Policy)>
 Used in the SetIamPolicy() read-modify-write cycles where an etag helps prevent simultaneous updates of a policy from overwriting each other. More...
 
template<typename T >
using optional = absl::optional< T >
 Alias template for google::cloud::optional. More...
 
template<typename... T>
using OptionList = internal::TypeList< T... >
 A template to hold a list of "option" types. More...
 

Enumerations

enum class  Idempotency { kIdempotent , kNonIdempotent }
 Whether a request is idempotent. More...
 
enum class  Severity : int {
  GCP_LS_TRACE , GCP_LS_DEBUG , GCP_LS_INFO , GCP_LS_NOTICE ,
  GCP_LS_WARNING , GCP_LS_ERROR , GCP_LS_CRITICAL , GCP_LS_ALERT ,
  GCP_LS_FATAL , GCP_LS_HIGHEST = GCP_LS_FATAL , GCP_LS_LOWEST = GCP_LS_TRACE , GCP_LS_LOWEST_ENABLED = GOOGLE_CLOUD_CPP_LOGGING_MIN_SEVERITY_ENABLED
}
 Define the severity levels for Google Cloud Platform C++ Libraries logging. More...
 
enum class  StatusCode {
  kOk = 0 , kCancelled = 1 , kUnknown = 2 , kInvalidArgument = 3 ,
  kDeadlineExceeded = 4 , kNotFound = 5 , kAlreadyExists = 6 , kPermissionDenied = 7 ,
  kUnauthenticated = 16 , kResourceExhausted = 8 , kFailedPrecondition = 9 , kAborted = 10 ,
  kOutOfRange = 11 , kUnimplemented = 12 , kInternal = 13 , kUnavailable = 14 ,
  kDataLoss = 15
}
 Well-known status codes with grpc::StatusCode-compatible values. More...
 

Functions

std::shared_ptr< CredentialsMakeInsecureCredentials ()
 Create insecure (aka anonymous, aka unauthenticated) credentials. More...
 
std::shared_ptr< CredentialsMakeGoogleDefaultCredentials ()
 Creates the default credentials. More...
 
std::shared_ptr< CredentialsMakeAccessTokenCredentials (std::string const &access_token, std::chrono::system_clock::time_point expiration)
 Creates credentials with a fixed access token. More...
 
std::shared_ptr< CredentialsMakeImpersonateServiceAccountCredentials (std::shared_ptr< Credentials > base_credentials, std::string target_service_account, Options opts={})
 Creates credentials for service account impersonation. More...
 
std::shared_ptr< CredentialsMakeServiceAccountCredentials (std::string json_object)
 Creates service account credentials from a service account key. More...
 
template<typename T >
future< typename internal::make_ready_return< T >::type > make_ready_future (T &&t)
 Create a future<void> that is immediately ready. More...
 
future< void > make_ready_future ()
 Create a future<void> that is immediately ready. More...
 
google::cloud::Status MakeStatusFromRpcError (grpc::Status const &status)
 Creates a google::cloud::Status from a grpc::Status. More...
 
google::cloud::Status MakeStatusFromRpcError (grpc::StatusCode code, std::string what)
 Creates a google::cloud::Status from a grpc::StatusCode and description. More...
 
google::cloud::Status MakeStatusFromRpcError (google::rpc::Status const &proto)
 Creates a google::cloud::Status from a google:rpc::Status proto. More...
 
StatusOr< KmsKeyNameMakeKmsKeyName (std::string const &full_name)
 Constructs a KmsKeyName from the given full_name. More...
 
std::ostream & operator<< (std::ostream &os, Severity x)
 Streaming operator, writes a human readable representation. More...
 
std::ostream & operator<< (std::ostream &os, LogRecord const &rhs)
 Default formatting of a LogRecord. More...
 
StatusOr< ProjectMakeProject (std::string const &full_name)
 Constructs a Project from the given full_name. More...
 
std::string StatusCodeToString (StatusCode code)
 
std::ostream & operator<< (std::ostream &os, StatusCode code)
 
template<typename T >
bool operator== (StatusOr< T > const &a, StatusOr< T > const &b)
 
template<typename T >
bool operator!= (StatusOr< T > const &a, StatusOr< T > const &b)
 
template<typename T >
StatusOr< T > make_status_or (T rhs)
 
constexpr int version_major ()
 The Google Cloud Storage C++ Client major version. More...
 
constexpr int version_minor ()
 The Google Cloud Storage C++ Client minor version. More...
 
constexpr int version_patch ()
 The Google Cloud Storage C++ Client patch version. More...
 
constexpr int version ()
 A single integer representing the Major/Minor/Patch version. More...
 
std::string version_string ()
 The version as a string, in MAJOR.MINOR.PATCH+gitrev format. More...
 

Control behaviour on unrecoverable errors.

The following APIs are google::cloud counterpart for std::{set,get}_terminate functions.

If exceptions are not enabled via GOOGLE_CLOUD_CPP_HAVE_EXCEPTIONS, calling any function from throw_delegate.h will result in calling the handler installed via this API. By default, a call to std::abort() is used.

using TerminateHandler = std::function< void(char const *msg)>
 Terminate handler. More...
 
TerminateHandler SetTerminateHandler (TerminateHandler f)
 Install terminate handler and get the old one atomically. More...
 
TerminateHandler GetTerminateHandler ()
 Get the currently installed handler. More...
 
void Terminate (char const *msg)
 Invoke the currently installed handler. More...
 

Detailed Description

Contains all the Google Cloud C++ Library APIs.

Typedef Documentation

◆ BackgroundThreadsFactory

using google::cloud::BackgroundThreadsFactory = typedef std::function<std::unique_ptr<BackgroundThreads>()>

Definition at line 134 of file grpc_options.h.

◆ BackoffPolicy

using google::cloud::BackoffPolicy = typedef ::google::cloud::internal::BackoffPolicy

The base class for backoff policies.

Definition at line 26 of file backoff_policy.h.

◆ CommonOptionList

A list of all the common options.

Definition at line 104 of file common_options.h.

◆ ExponentialBackoffPolicy

using google::cloud::ExponentialBackoffPolicy = typedef google::cloud::internal::ExponentialBackoffPolicy

A truncated exponential backoff policy with randomized periods.

Definition at line 29 of file backoff_policy.h.

◆ GrpcOptionList

A list of all the gRPC options.

Definition at line 160 of file grpc_options.h.

◆ IamUpdater

using google::cloud::IamUpdater = typedef std::function<absl::optional<google::iam::v1::Policy>( google::iam::v1::Policy)>

Used in the SetIamPolicy() read-modify-write cycles where an etag helps prevent simultaneous updates of a policy from overwriting each other.

The updater is called with a recently fetched policy, and should either return an empty optional if no changes are required, or return a new policy to be set. In the latter case the updater should either (1) set the etag of the returned policy to that of the recently fetched policy (strongly suggested), or (2) not set the etag at all.

In case (1) if the etag does not match the existing policy (i.e., there has been an intermediate update), this update is dropped and a new cycle is initiated. In case (2) the existing policy is overwritten blindly.

Definition at line 41 of file iam_updater.h.

◆ optional

template<typename T >
using google::cloud::optional = typedef absl::optional<T>

Alias template for google::cloud::optional.

Deprecated:
this alias is deprecated; use absl::optional<T> directly.

Definition at line 31 of file optional.h.

◆ OptionList

template<typename... T>
using google::cloud::OptionList = typedef internal::TypeList<T...>

A template to hold a list of "option" types.

This can be a useful way to create meaningful lists of options. For example, there could be a list containing all the gRPC options. Or a list of all ProductX options. This gives us a way to link to lists of options with doxygen, and to do some checking about what options a function may expect.

Definition at line 257 of file options.h.

◆ TerminateHandler

using google::cloud::TerminateHandler = typedef std::function<void(char const* msg)>

Terminate handler.

It should handle the error, whose description are given in msg and should never return.

Definition at line 41 of file terminate_handler.h.

◆ UnifiedCredentialsOptionList

A list of options related to authentication.

Definition at line 281 of file credentials.h.

Enumeration Type Documentation

◆ Idempotency

Whether a request is idempotent.

When a RPC fails with a retryable error, the google-cloud-cpp client libraries automatically retry the RPC if the RPC is idempotent. For each service, the library define a policy that determines whether a given request is idempotent. In many cases this can be determined statically, for example, read-only operations are always idempotent. In some cases, the contents of the request may need to be examined to determine if the operation is idempotent. For example, performing operations with pre-conditions, such that the pre-conditions change when the operation succeed, is typically idempotent.

Applications may override the default idempotency policy, though we anticipate that this would be needed only in very rare circumstances. A few examples include:

  • In some services deleting "the most recent" entry may be idempotent if the system has been configured to keep no history or versions, as the deletion may succeed only once. In contrast, deleting "the most recent entry" is not idempotent if the system keeps multiple versions. Google Cloud Storage or Bigtable can be configured either way.
  • In some applications, creating a duplicate entry may be acceptable as the system will deduplicate them later. In such systems it may be preferable to retry the operation even though it is not idempotent.
Enumerator
kIdempotent 

The operation is idempotent and can be retried after a transient failure.

kNonIdempotent 

The operation is not idempotent and should not be retried after a transient failure.

Definition at line 55 of file idempotency.h.

◆ Severity

enum google::cloud::Severity : int
strong

Define the severity levels for Google Cloud Platform C++ Libraries logging.

These are modelled after the severity level in syslog(1) and many derived tools.

We force the enum to be represented as an int because we will store the values in an std::atomic<> and the implementations usually optimize std::atomic<int> but not std::atomic<Foo>

Enumerator
GCP_LS_TRACE 

Use this level for messages that indicate the code is entering and leaving functions.

GCP_LS_DEBUG 

Use this level for debug messages that should not be present in production.

GCP_LS_INFO 

Informational messages, such as normal progress.

GCP_LS_NOTICE 

Informational messages, such as unusual, but expected conditions.

GCP_LS_WARNING 

An indication of problems, users may need to take action.

GCP_LS_ERROR 

An error has been detected.

Do not use for normal conditions, such as remote servers disconnecting.

GCP_LS_CRITICAL 

The system is in a critical state, such as running out of local resources.

GCP_LS_ALERT 

The system is at risk of immediate failure.

GCP_LS_FATAL 

The system is unusable. GCP_LOG(FATAL) will call std::abort().

GCP_LS_HIGHEST 

The highest possible severity level.

GCP_LS_LOWEST 

The lowest possible severity level.

GCP_LS_LOWEST_ENABLED 

The lowest level that is enabled at compile-time.

Definition at line 183 of file log.h.

◆ StatusCode

Well-known status codes with grpc::StatusCode-compatible values.

The semantics of these values are documented in: https://grpc.io/grpc/cpp/classgrpc_1_1_status.html

Enumerator
kOk 

Not an error; returned on success.

kCancelled 
kUnknown 
kInvalidArgument 
kDeadlineExceeded 
kNotFound 
kAlreadyExists 
kPermissionDenied 
kUnauthenticated 
kResourceExhausted 
kFailedPrecondition 
kAborted 
kOutOfRange 
kUnimplemented 
kInternal 
kUnavailable 
kDataLoss 

Definition at line 35 of file status.h.

Function Documentation

◆ GetTerminateHandler()

TerminateHandler google::cloud::GetTerminateHandler ( )

Get the currently installed handler.

Returns
The currently installed handler.

◆ make_ready_future() [1/2]

future<void> google::cloud::make_ready_future ( )
inline

Create a future<void> that is immediately ready.

Definition at line 207 of file future_void.h.

◆ make_ready_future() [2/2]

template<typename T >
future<typename internal::make_ready_return<T>::type> google::cloud::make_ready_future ( T &&  t)
inline

Create a future<void> that is immediately ready.

Definition at line 217 of file future_generic.h.

◆ make_status_or()

template<typename T >
StatusOr<T> google::cloud::make_status_or ( rhs)

Definition at line 294 of file status_or.h.

◆ MakeKmsKeyName()

StatusOr<KmsKeyName> google::cloud::MakeKmsKeyName ( std::string const &  full_name)

Constructs a KmsKeyName from the given full_name.

Returns a non-OK Status if full_name is improperly formed.

◆ MakeProject()

StatusOr<Project> google::cloud::MakeProject ( std::string const &  full_name)

Constructs a Project from the given full_name.

Returns a non-OK Status if full_name is improperly formed.

◆ MakeStatusFromRpcError() [1/3]

google::cloud::Status google::cloud::MakeStatusFromRpcError ( google::rpc::Status const &  proto)

Creates a google::cloud::Status from a google:rpc::Status proto.

Some gRPC services return the google::rpc::Status proto for errors. The libraries in google-cloud-cpp represent these errors using a google::cloud::Status.

◆ MakeStatusFromRpcError() [2/3]

google::cloud::Status google::cloud::MakeStatusFromRpcError ( grpc::Status const &  status)

Creates a google::cloud::Status from a grpc::Status.

◆ MakeStatusFromRpcError() [3/3]

google::cloud::Status google::cloud::MakeStatusFromRpcError ( grpc::StatusCode  code,
std::string  what 
)

Creates a google::cloud::Status from a grpc::StatusCode and description.

◆ operator!=()

template<typename T >
bool google::cloud::operator!= ( StatusOr< T > const &  a,
StatusOr< T > const &  b 
)

Definition at line 289 of file status_or.h.

◆ operator<<() [1/3]

std::ostream& google::cloud::operator<< ( std::ostream &  os,
LogRecord const &  rhs 
)

Default formatting of a LogRecord.

◆ operator<<() [2/3]

std::ostream& google::cloud::operator<< ( std::ostream &  os,
Severity  x 
)

Streaming operator, writes a human readable representation.

◆ operator<<() [3/3]

std::ostream& google::cloud::operator<< ( std::ostream &  os,
StatusCode  code 
)

◆ operator==()

template<typename T >
bool google::cloud::operator== ( StatusOr< T > const &  a,
StatusOr< T > const &  b 
)

Definition at line 281 of file status_or.h.

◆ SetTerminateHandler()

TerminateHandler google::cloud::SetTerminateHandler ( TerminateHandler  f)

Install terminate handler and get the old one atomically.

Parameters
fthe handler. It should never return, behaviour is undefined otherwise.
Returns
Previously set handler.

◆ StatusCodeToString()

std::string google::cloud::StatusCodeToString ( StatusCode  code)

◆ Terminate()

void google::cloud::Terminate ( char const *  msg)

Invoke the currently installed handler.

Parameters
msgDetails about the error.

This function should never return.

◆ version()

constexpr int google::cloud::version ( )
constexpr

A single integer representing the Major/Minor/Patch version.

Definition at line 86 of file version.h.

◆ version_major()

constexpr int google::cloud::version_major ( )
constexpr

The Google Cloud Storage C++ Client major version.

See also
https://semver.org/spec/v2.0.0.html for details.

Definition at line 64 of file version.h.

◆ version_minor()

constexpr int google::cloud::version_minor ( )
constexpr

The Google Cloud Storage C++ Client minor version.

See also
https://semver.org/spec/v2.0.0.html for details.

Definition at line 71 of file version.h.

◆ version_patch()

constexpr int google::cloud::version_patch ( )
constexpr

The Google Cloud Storage C++ Client patch version.

See also
https://semver.org/spec/v2.0.0.html for details.

Definition at line 78 of file version.h.

◆ version_string()

std::string google::cloud::version_string ( )

The version as a string, in MAJOR.MINOR.PATCH+gitrev format.