Google Cloud Pub/Sub C++ Client  1.34.1
A C++ Client Library for Google Cloud Pub/Sub
publisher.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 // http://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_PUBSUB_PUBLISHER_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_PUBLISHER_H
17 
18 #include "google/cloud/pubsub/connection_options.h"
19 #include "google/cloud/pubsub/publisher_connection.h"
20 #include "google/cloud/pubsub/publisher_options.h"
21 #include "google/cloud/pubsub/version.h"
22 #include <string>
23 
24 namespace google {
25 namespace cloud {
26 namespace pubsub {
28 /**
29  * Publish messages to the Cloud Pub/Sub service.
30  *
31  * This class is used to publish message to a given topic, with a fixed
32  * configuration such as credentials, batching, background threads, etc.
33  * Applications that publish messages to multiple topics need to create separate
34  * instances of this class. Applications wanting to publish events with
35  * different batching configuration also need to create separate instances.
36  *
37  * @see https://cloud.google.com/pubsub for an overview of the Cloud Pub/Sub
38  * service.
39  *
40  * @par Example
41  * @snippet samples.cc publish
42  *
43  * @par Message Ordering
44  * A `Publisher` configured to preserve message ordering will sequence the
45  * messages that share a common ordering key (see
46  * `MessageBuilder::SetOrderingKey()`). Messages will be batched by ordering
47  * key, and new batches will wait until the status of the previous batch is
48  * known. On an error, all pending and queued messages are discarded, and the
49  * publisher rejects any new messages for the ordering key that experienced
50  * problems. The application must call `Publisher::ResumePublishing()` to
51  * to restore publishing.
52  *
53  * @par Performance
54  * `Publisher` objects are relatively cheap to create, copy, and move. However,
55  * each `Publisher` object must be created with a
56  * `std::shared_ptr<PublisherConnection>`, which itself is relatively expensive
57  * to create. Therefore, connection instances should be shared when possible.
58  * See the `MakePublisherConnection()` method and the `PublisherConnection`
59  * interface for more details.
60  *
61  * @par Thread Safety
62  * Instances of this class created via copy-construction or copy-assignment
63  * share the underlying pool of connections. Access to these copies via multiple
64  * threads is guaranteed to work. Two threads operating on the same instance of
65  * this class is not guaranteed to work.
66  *
67  * @par Background Threads
68  * This class uses the background threads configured via the `Options` from
69  * `GrpcOptionList`. Applications can create their own pool of background
70  * threads by (a) creating their own #google::cloud::CompletionQueue, (b)
71  * passing this completion queue as a `GrpcCompletionQueueOption`, and (c)
72  * attaching any number of threads to the completion queue.
73  *
74  * @par Example: using a custom thread pool
75  * @snippet samples.cc custom-thread-pool-publisher
76  *
77  * @par Asynchronous Functions
78  * Some of the member functions in this class return a `future<T>` (or
79  * `future<StatusOr<T>>`) object. Readers are probably familiar with
80  * [`std::future<T>`][std-future-link]. Our version adds a `.then()` function to
81  * attach a callback to the future, which is invoked when the future is
82  * satisfied. This function returns a `future<U>` where `U` is the return value
83  * of the attached function. More details in the #google::cloud::future
84  * documentation.
85  *
86  * @par Error Handling
87  * This class uses `StatusOr<T>` to report errors. When an operation fails to
88  * perform its work the returned `StatusOr<T>` contains the error details. If
89  * the `ok()` member function in the `StatusOr<T>` returns `true` then it
90  * contains the expected result. Please consult the #google::cloud::StatusOr
91  * documentation for more details.
92  *
93  * @par Batching Configuration Example
94  * @snippet samples.cc publisher-options
95  *
96  * [std-future-link]: https://en.cppreference.com/w/cpp/thread/future
97  */
98 class Publisher {
99  public:
100  explicit Publisher(std::shared_ptr<PublisherConnection> connection,
101  PublisherOptions const& options = {});
102 
103  //@{
104  Publisher(Publisher const&) = default;
105  Publisher& operator=(Publisher const&) = default;
106  Publisher(Publisher&&) = default;
107  Publisher& operator=(Publisher&&) = default;
108  //@}
109 
110  //@{
111  friend bool operator==(Publisher const& a, Publisher const& b) {
112  return a.connection_ == b.connection_;
113  }
114  friend bool operator!=(Publisher const& a, Publisher const& b) {
115  return !(a == b);
116  }
117  //@}
118 
119  /**
120  * Publishes a message to this publisher's topic
121  *
122  * Note that the message may be batched, depending on the Publisher's
123  * configuration. It could be delayed until the batch has enough messages,
124  * or enough data, or enough time has elapsed. See the `PublisherOptionList`
125  * documentation for more details.
126  *
127  * @par Idempotency
128  * This is a non-idempotent operation, but the client library will
129  * automatically retry RPCs that fail with transient errors. As Cloud Pub/Sub
130  * has "at least once" delivery semantics applications are expected to handle
131  * duplicate messages without problems. The application can disable retries
132  * by changing the retry policy, please see the example below.
133  *
134  * @par Example
135  * @snippet samples.cc publish
136  *
137  * @par Disabling Retries Example
138  * @snippet samples.cc publisher-disable-retries
139  *
140  * @par Changing Retry Parameters Example
141  * @snippet samples.cc publisher-retry-settings
142  *
143  * @return a future that becomes satisfied when the message is published or on
144  * a unrecoverable error.
145  */
146  future<StatusOr<std::string>> Publish(Message m) {
147  return connection_->Publish({std::move(m)});
148  }
149 
150  /**
151  * Forcibly publishes any batched messages.
152  *
153  * As applications can configure a `Publisher` to buffer messages, it is
154  * sometimes useful to flush them before any of the normal criteria to send
155  * the RPCs is met.
156  *
157  * @par Idempotency
158  * See the description in `Publish()`.
159  *
160  * @par Example
161  * @snippet samples.cc publish-custom-attributes
162  *
163  * @note This function does not return any status or error codes, the
164  * application can use the `future<StatusOr<std::string>>` returned in
165  * each `Publish()` call to find out what the results are.
166  */
167  void Flush() { connection_->Flush({}); }
168 
169  /**
170  * Resumes publishing after an error.
171  *
172  * If the publisher options have message ordering enabled (see
173  * `MessageOrderingOption`) all messages for a key that experience failure
174  * will be rejected until the application calls this function.
175  *
176  * @par Idempotency
177  * This function never initiates a remote RPC, so there are no considerations
178  * around retrying it. Note, however, that more than one `Publish()` request
179  * may fail for the same ordering key. The application needs to call this
180  * function after **each** error before it can resume publishing messages
181  * with the same ordering key.
182  *
183  * @par Example
184  * @snippet samples.cc resume-publish
185  */
186  void ResumePublish(std::string ordering_key) {
187  connection_->ResumePublish({std::move(ordering_key)});
188  }
189 
190  private:
191  std::shared_ptr<PublisherConnection> connection_;
192 };
193 
195 } // namespace pubsub
196 } // namespace cloud
197 } // namespace google
198 
199 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_PUBLISHER_H