Skip to content

Commit 0bb1206

Browse files
bshafferbshaffer
authored
feat: product neutral guides (#15865)
1 parent a6db008 commit 0bb1206

9 files changed

Lines changed: 696 additions & 3 deletions

File tree

‎cmake/GoogleCloudCppDoxygen.cmake‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,8 @@ function (google_cloud_cpp_doxygen_targets_impl library)
3232
return()
3333
endif ()
3434

35-
cmake_parse_arguments(opt "RECURSIVE;THREADED" "" "INPUTS;TAGFILES;DEPENDS"
36-
${ARGN})
35+
cmake_parse_arguments(opt "RECURSIVE;THREADED" ""
36+
"INPUTS;TAGFILES;DEPENDS;FILE_PATTERNS" ${ARGN})
3737

3838
# Options controlling the inputs into Doxygen
3939
set(GOOGLE_CLOUD_CPP_DOXYGEN_INPUTS ${_opt_INPUTS})
@@ -59,7 +59,11 @@ function (google_cloud_cpp_doxygen_targets_impl library)
5959
" using DOXYGEN_NUM_PROC_THREADS=${DOXYGEN_NUM_PROC_THREADS}")
6060
endif ()
6161

62-
set(DOXYGEN_FILE_PATTERNS "*.dox" "*.h")
62+
if (_opt_FILE_PATTERNS)
63+
set(DOXYGEN_FILE_PATTERNS ${_opt_FILE_PATTERNS})
64+
else ()
65+
set(DOXYGEN_FILE_PATTERNS "*.dox" "*.h")
66+
endif ()
6367
set(DOXYGEN_EXCLUDE_PATTERNS
6468
# We should skip internal directories to speed up the build. We do not
6569
# use "*/internal/*" because Doxygen breaks when we include

‎doc/product-neutral-guides/client-configuration.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Google Cloud Platform C++ Client Libraries: Client Configuration
2+
3+
The Google Cloud C++ Client Libraries allow you to configure client behavior via
4+
the `google::cloud::Options` class passed to the client constructor or the
5+
connection factory functions.
6+
7+
## 1. Common Configuration Options
8+
9+
The `google::cloud::Options` class is a type-safe map where you set specific
10+
option structs.
11+
12+
| Option Struct | Description |
13+
| ----------------------------------------- | ------------------------------------------------------------------- |
14+
| `google::cloud::EndpointOption` | The address of the API remote host. Used for Regional Endpoints. |
15+
| `google::cloud::UserProjectOption` | Quota project to use for the request. |
16+
| `google::cloud::AuthorityOption` | Sets the `:authority` pseudo-header (useful for testing/emulators). |
17+
| `google::cloud::UnifiedCredentialsOption` | Explicit credentials object (overrides default discovery). |
18+
| `google::cloud::TracingComponentsOption` | Controls client-side logging/tracing. |
19+
20+
## 2. Customizing the API Endpoint
21+
22+
You can modify the API endpoint to connect to a specific Google Cloud region or
23+
to a private endpoint.
24+
25+
### Connecting to a Regional Endpoint
26+
27+
<!-- code-include: ../../google/cloud/pubsub/samples/client_samples.cc#publisher-set-endpoint -->
28+
29+
## 3. Configuring a Proxy
30+
31+
### Proxy with gRPC
32+
33+
The C++ gRPC layer respects standard environment variables. You generally do not
34+
configure this in C++ code.
35+
36+
Set the following environment variables in your shell or Docker container:
37+
38+
```
39+
export http_proxy="http://proxy.example.com:3128"
40+
export https_proxy="http://proxy.example.com:3128"
41+
```
42+
43+
**Handling Self-Signed Certificates:** If your proxy uses a self-signed
44+
certificate, use the standard gRPC environment variable:
45+
46+
```
47+
export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH="/path/to/roots.pem"
48+
```
49+
50+
### Proxy with REST
51+
52+
If using a library that supports REST (like `google-cloud-storage`), it
53+
primarily relies on `libcurl`, which also respects the standard `http_proxy` and
54+
`https_proxy` environment variables.
55+
56+
## 4. Configuring Retries and Timeouts
57+
58+
In C++, retry policies are configured via `Options` or passed specifically to
59+
the connection factory.
60+
61+
### Configuring Retry Policies
62+
63+
You can set the `RetryPolicyOption` and `BackoffPolicyOption`.
64+
65+
<!-- code-include: ../../google/cloud/secretmanager/v1/samples/secret_manager_client_samples.cc#set-retry-policy -->
66+
67+
### Configuring Timeouts
68+
69+
There isn't a single "timeout" integer. Instead, you can configure the
70+
**Idempotency Policy** (to determine which RPCs are safe to retry) or use
71+
`google::cloud::Options` to set specific RPC timeouts if the library exposes a
72+
specific option, though usually, the `RetryPolicy` (Total Timeout) governs the
73+
duration of the call.
74+
75+
For per-call context (like deadlines), you can sometimes use
76+
`grpc::ClientContext` if dropping down to the raw stub level, but idiomatic
77+
Google Cloud C++ usage prefers the Policy approach.

‎doc/product-neutral-guides/core-concepts.md‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
# Google Cloud Platform C++ Client Libraries: Core Concepts
2+
3+
This documentation covers essential patterns and usage for the Google Cloud C++
4+
Client Library, focusing on performance, data handling (`StatusOr`), and flow
5+
control (Pagination, Futures, Streaming).
6+
7+
## 1. Installation & Setup
8+
9+
The C++ libraries are typically installed via **vcpkg** or **Conda**, or
10+
compiled from source using **CMake**.
11+
12+
**Example using vcpkg:**
13+
14+
```
15+
vcpkg install google-cloud-cpp
16+
```
17+
18+
**CMakeLists.txt:**
19+
20+
```c
21+
find_package(google_cloud_cpp_pubsub REQUIRED)
22+
add_executable(my_app main.cc)
23+
target_link_libraries(my_app google-cloud-cpp::pubsub)
24+
```
25+
26+
## 2. StatusOr\<T> and Error Handling
27+
28+
C++ does not use exceptions for API errors by default. Instead, it uses
29+
`google::cloud::StatusOr<T>`.
30+
31+
- **Success:** The object contains the requested value.
32+
- **Failure:** The object contains a `Status` (error code and message).
33+
34+
```c
35+
void HandleResponse(google::cloud::StatusOr<std::string> response) {
36+
if (!response) {
37+
// Handle error
38+
std::cerr << "RPC failed: " << response.status().message() << "\n";
39+
return;
40+
}
41+
// Access value
42+
std::cout << "Success: " << *response << "\n";
43+
}
44+
```
45+
46+
## 3. Pagination (StreamRange)
47+
48+
List methods in C++ return a `google::cloud::StreamRange<T>`. This works like
49+
standard C++ input iterator. The library automatically fetches new pages in the
50+
background as you iterate.
51+
52+
```c
53+
#include "google/cloud/secretmanager/secret_manager_client.h"
54+
55+
void ListSecrets(google::cloud::secretmanager::SecretManagerServiceClient client) {
56+
// Call the API
57+
// Returns StreamRange<google::cloud::secretmanager::v1::Secret>
58+
auto range = client.ListSecrets("projects/my-project");
59+
60+
for (auto const& secret : range) {
61+
if (!secret) {
62+
// StreamRange returns StatusOr<T> on dereference to handle failures mid-stream
63+
std::cerr << "Error listing secret: " << secret.status() << "\n";
64+
break;
65+
}
66+
std::cout << "Secret: " << secret->name() << "\n";
67+
}
68+
}
69+
```
70+
71+
## 4. Long Running Operations (LROs)
72+
73+
LROs in C++ return a `std::future<StatusOr<T>>`.
74+
75+
### Blocking Wait
76+
77+
```c
78+
#include "google/cloud/compute/instances_client.h"
79+
80+
void CreateInstance(google::cloud::compute::InstancesClient client) {
81+
google::cloud::compute::v1::InsertInstanceRequest request;
82+
// ... set request fields ...
83+
84+
// Start the operation
85+
// Returns future<StatusOr<Operation>>
86+
auto future = client.InsertInstance(request);
87+
88+
// Block until complete
89+
auto result = future.get();
90+
91+
if (!result) {
92+
std::cerr << "Creation failed: " << result.status() << "\n";
93+
} else {
94+
std::cout << "Instance created successfully\n";
95+
}
96+
}
97+
```
98+
99+
### Async / Non-Blocking
100+
101+
You can use standard C++ `future` capabilities, such as polling `wait_for` or
102+
attaching continuations (via `.then` if using the library's future extension,
103+
though standard `std::future` is strictly blocking/polling).
104+
105+
## 5. Update Masks
106+
107+
The C++ libraries use `google::protobuf::FieldMask`.
108+
109+
```c
110+
#include "google/cloud/secretmanager/secret_manager_client.h"
111+
#include <google/protobuf/field_mask.pb.h>
112+
113+
void UpdateSecret(google::cloud::secretmanager::SecretManagerServiceClient client) {
114+
namespace secretmanager = ::google::cloud::secretmanager::v1;
115+
116+
secretmanager::Secret secret;
117+
secret.set_name("projects/my-project/secrets/my-secret");
118+
(*secret.mutable_labels())["env"] = "production";
119+
120+
google::protobuf::FieldMask update_mask;
121+
update_mask.add_paths("labels");
122+
123+
secretmanager::UpdateSecretRequest request;
124+
*request.mutable_secret() = secret;
125+
*request.mutable_update_mask() = update_mask;
126+
127+
auto result = client.UpdateSecret(request);
128+
}
129+
```
130+
131+
## 6. gRPC Streaming
132+
133+
### Server-Side Streaming
134+
135+
Similar to pagination, Server-Side streaming usually returns a `StreamRange` or
136+
a specialized reader object.
137+
138+
```c
139+
#include "google/cloud/bigquery/storage/bigquery_read_client.h"
140+
141+
void ReadRows(google::cloud::bigquery_storage::BigQueryReadClient client) {
142+
google::cloud::bigquery::storage::v1::ReadRowsRequest request;
143+
request.set_read_stream("projects/.../streams/...");
144+
145+
// Returns a StreamRange of ReadRowsResponse
146+
auto stream = client.ReadRows(request);
147+
148+
for (auto const& response : stream) {
149+
if (!response) {
150+
std::cerr << "Error reading row: " << response.status() << "\n";
151+
break;
152+
}
153+
// Process response->avro_rows()
154+
}
155+
}
156+
```
157+
158+
### Bidirectional Streaming
159+
160+
Bidirectional streaming uses a `AsyncReaderWriter` pattern (or synchronous
161+
`ReaderWriter`).
162+
163+
```c
164+
#include "google/cloud/speech/speech_client.h"
165+
166+
void StreamingRecognize(google::cloud::speech::SpeechClient client) {
167+
// Start the stream
168+
auto stream = client.StreamingRecognize();
169+
170+
// 1. Send Config
171+
google::cloud::speech::v1::StreamingRecognizeRequest config_request;
172+
// ... configure ...
173+
stream->Write(config_request);
174+
175+
// 2. Send Audio
176+
google::cloud::speech::v1::StreamingRecognizeRequest audio_request;
177+
// ... load audio data ...
178+
stream->Write(audio_request);
179+
180+
// 3. Close writing to signal we are done sending
181+
stream->WritesDone();
182+
183+
// 4. Read responses
184+
google::cloud::speech::v1::StreamingRecognizeResponse response;
185+
while (stream->Read(&response)) {
186+
for (const auto& result : response.results()) {
187+
std::cout << "Transcript: " << result.alternatives(0).transcript() << "\n";
188+
}
189+
}
190+
191+
// Check final status
192+
auto status = stream->Finish();
193+
}
194+
```

0 commit comments

Comments
 (0)