docs(pubsub): add a subscriber quickstart

google/cloud/pubsub/README.md

@@ -32,6 +32,7 @@ int main(int argc, char* argv[]) try {
 
   // Create a namespace alias to make the code easier to read.
   namespace pubsub = ::google::cloud::pubsub;
+
   auto publisher = pubsub::Publisher(
       pubsub::MakePublisherConnection(pubsub::Topic(project_id, topic_id)));
   auto id =

google/cloud/pubsub/quickstart/BUILD.bazel

@@ -25,3 +25,13 @@ cc_binary(
         "@google_cloud_cpp//:pubsub",
     ],
 )
+
+cc_binary(
+    name = "subscriber_quickstart",
+    srcs = [
+        "subscriber_quickstart.cc",
+    ],
+    deps = [
+        "@google_cloud_cpp//:pubsub",
+    ],
+)

google/cloud/pubsub/quickstart/CMakeLists.txt

@@ -27,6 +27,9 @@ else ()
     set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>DLL")
 endif ()
 
-# Once the pubsub_client package is found, define new targets.
+# Once the pubsub_client package is found, define new targets and the
+# dependencies they link.
 add_executable(quickstart quickstart.cc)
 target_link_libraries(quickstart google-cloud-cpp::pubsub)
+add_executable(subscriber_quickstart subscriber_quickstart.cc)
+target_link_libraries(subscriber_quickstart google-cloud-cpp::pubsub)

google/cloud/pubsub/quickstart/Makefile

@@ -22,7 +22,7 @@ CXXFLAGS=
 CXXLD=$(CXX)
 BIN=.
 
-all: $(BIN)/quickstart
+all: $(BIN)/quickstart $(BIN)/subscriber_quickstart
 
 # Configuration variables to compile and link against the Cloud Pub/Sub C++
 # client library.
@@ -31,6 +31,9 @@ PUBSUB_CXXFLAGS   := $(shell pkg-config $(PUBSUB_DEPS) --cflags)
 PUBSUB_CXXLDFLAGS := $(shell pkg-config $(PUBSUB_DEPS) --libs-only-L)
 PUBSUB_LIBS       := $(shell pkg-config $(PUBSUB_DEPS) --libs-only-l)
 
-# A target using the Cloud Pub/Sub C++ client library.
+# Define 2 targets, one for the publisher and one for the subscriber, using the Cloud Pub/Sub C++ client library.
 $(BIN)/quickstart: quickstart.cc
 	$(CXXLD) $(CXXFLAGS) $(PUBSUB_CXXFLAGS) $(PUBSUB_CXXLDFLAGS) -o $@ $^ $(PUBSUB_LIBS)
+
+$(BIN)/subscriber_quickstart: subscriber_quickstart.cc
+	$(CXXLD) $(CXXFLAGS) $(PUBSUB_CXXFLAGS) $(PUBSUB_CXXLDFLAGS) -o $@ $^ $(PUBSUB_LIBS)

google/cloud/pubsub/quickstart/README.md

@@ -50,8 +50,7 @@ Setting this environment variable is the recommended way to configure the
 authentication preferences, though if the environment variable is not set, the
 library searches for a credentials file in the same location as the [Cloud
 SDK](https://cloud.google.com/sdk/). For more information about *Application
-Default Credentials*, see
-https://cloud.google.com/docs/authentication/production
+Default Credentials*, see https://cloud.google.com/docs/authentication/production
 
 ## Using with Bazel
 
@@ -71,12 +70,18 @@ https://cloud.google.com/docs/authentication/production
    Note that, as it is often the case with C++ libraries, compiling these
    dependencies may take several minutes.
 
-1. Run the example, changing the placeholder(s) to appropriate values:
+1. Publish messages by running the example, changing the placeholder(s) to appropriate values:
 
    ```bash
    bazel run :quickstart -- [GCP PROJECT ID] [PUB/SUB TOPIC ID]
    ```
 
+1. Subscribe to messages by running the example, changing the placeholder(s) to appropriate values:
+
+   ```bash
+   bazel run :subscriber_quickstart -- [GCP PROJECT ID] [PUB/SUB SUBSCRIPTION ID]
+   ```
+
 ## Using with CMake
 
 > :warning: If you are using Windows or macOS there are additional instructions
@@ -108,10 +113,16 @@ https://cloud.google.com/docs/authentication/production
    cmake --build .build
    ```
 
-1. Run the example, changing the placeholder(s) to appropriate values:
+1. Publish messages by running the example, changing the placeholder(s) to appropriate values:
+
+   ```bash
+      .build/quickstart [GCP PROJECT ID] [PUB/SUB TOPIC ID]
+   ```
+
+1. Subscribe to messages by running the example, changing the placeholder(s) to appropriate values:
 
    ```bash
-   .build/quickstart [GCP PROJECT ID] [PUB/SUB TOPIC ID]
+      .build/subscriber_quickstart [GCP PROJECT ID] [PUB/SUB SUBSCRIPTION ID]
    ```
 
 ## Platform Specific Notes
@@ -152,4 +163,4 @@ set GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=%cd%\roots.pem
 [grpc-roots-pem-bug]: https://github.com/grpc/grpc/issues/16571
 [homebrew-cmake-link]: https://formulae.brew.sh/formula/cmake
 [howto-setup-dev-workstation]: /doc/contributor/howto-guide-setup-development-workstation.md
-[pubsub-quickstart-link]: https://cloud.google.com/pubsub/docs/quickstart-console
+[pubsub-quickstart-link]: https://cloud.google.com/pubsub/docs/publish-receive-messages-client-library

google/cloud/pubsub/quickstart/quickstart.cc

@@ -27,6 +27,7 @@ int main(int argc, char* argv[]) try {
 
   // Create a namespace alias to make the code easier to read.
   namespace pubsub = ::google::cloud::pubsub;
+
   auto publisher = pubsub::Publisher(
       pubsub::MakePublisherConnection(pubsub::Topic(project_id, topic_id)));
   auto id =

google/cloud/pubsub/quickstart/subscriber_quickstart.cc

@@ -0,0 +1,57 @@
+// Copyright 2023 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! [START pubsub_quickstart_subscriber] [all]
+#include "google/cloud/pubsub/message.h"
+#include "google/cloud/pubsub/subscriber.h"
+#include <iostream>
+
+int main(int argc, char* argv[]) try {
+  if (argc != 3) {
+    std::cerr << "Usage: " << argv[0] << " <project-id> <subscription-id>\n";
+    return 1;
+  }
+
+  std::string const project_id = argv[1];
+  std::string const subscription_id = argv[2];
+
+  auto constexpr kWaitTimeout = std::chrono::seconds(30);
+
+  // Create a namespace alias to make the code easier to read.
+  namespace pubsub = ::google::cloud::pubsub;
+
+  auto subscriber = pubsub::Subscriber(pubsub::MakeSubscriberConnection(
+      pubsub::Subscription(project_id, subscription_id)));
+
+  auto session =
+      subscriber.Subscribe([&](pubsub::Message const& m, pubsub::AckHandler h) {
+        std::cout << "Received message " << m << "\n";
+        std::move(h).ack();
+      });
+
+  std::cout << "Waiting for messages on " + subscription_id + "...\n";
+
+  // Blocks until the timeout is reached.
+  auto result = session.wait_for(kWaitTimeout);
+  if (result == std::future_status::timeout) {
+    std::cout << "timeout reached, ending session\n";
+    session.cancel();
+  }
+
+  return 0;
+} catch (google::cloud::Status const& status) {
+  std::cerr << "google::cloud::Status thrown: " << status << "\n";
+  return 1;
+}
+//! [END pubsub_quickstart_subscriber] [all]