Google Cloud Pub/Sub C++ Client  2.1.0
A C++ Client Library for Google Cloud Pub/Sub
publisher_connection.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 // 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_PUBSUB_PUBLISHER_CONNECTION_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_PUBLISHER_CONNECTION_H
17 
18 #include "google/cloud/pubsub/backoff_policy.h"
19 #include "google/cloud/pubsub/connection_options.h"
20 #include "google/cloud/pubsub/internal/publisher_stub.h"
21 #include "google/cloud/pubsub/message.h"
22 #include "google/cloud/pubsub/publisher_options.h"
23 #include "google/cloud/pubsub/retry_policy.h"
24 #include "google/cloud/pubsub/topic.h"
25 #include "google/cloud/pubsub/version.h"
26 #include "google/cloud/future.h"
27 #include "google/cloud/internal/non_constructible.h"
28 #include "google/cloud/status_or.h"
29 #include <initializer_list>
30 #include <string>
31 #include <vector>
32 
33 namespace google {
34 namespace cloud {
35 namespace pubsub {
37 
38 /**
39  * A connection to the Cloud Pub/Sub service to publish events.
40  *
41  * This interface defines pure-virtual methods for each of the user-facing
42  * overload sets in `Publisher`. That is, all of `Publisher`'s overloads will
43  * forward to the one pure-virtual method declared in this interface. This
44  * allows users to inject custom behavior (e.g., with a Google Mock object) in a
45  * `Publisher` object for use in their own tests.
46  *
47  * To create a concrete instance that connects you to the real Cloud Pub/Sub
48  * service, see `MakePublisherConnection()`.
49  *
50  * @par The *Params nested classes
51  * Applications may define classes derived from `PublisherConnection`, for
52  * example, because they want to mock the class. To avoid breaking all such
53  * derived classes when we change the number or type of the arguments to the
54  * member functions we define lightweight structures to pass the arguments.
55  */
57  public:
58  virtual ~PublisherConnection() = 0;
59 
60  /// Wrap the arguments for `Publish()`
61  struct PublishParams {
63  };
64 
65  /// Wrap the arguments for `Flush()`
66  struct FlushParams {};
67 
68  /// Wrap the arguments for `ResumePublish()`
70  std::string ordering_key;
71  };
72 
73  /// Defines the interface for `Publisher::Publish()`
74  virtual future<StatusOr<std::string>> Publish(PublishParams p);
75 
76  /// Defines the interface for `Publisher::Flush()`
77  virtual void Flush(FlushParams);
78 
79  /// Defines the interface for `Publisher::ResumePublish()`
81 };
82 
83 /**
84  * Creates a new `PublisherConnection` object to work with `Publisher`.
85  *
86  * @note This function exists solely for backwards compatibility. It prevents
87  * existing code that calls `MakePublisherConnection(topic, {})` from
88  * breaking, due to ambiguity.
89  *
90  * @deprecated Please use `MakePublisherConnection(topic)` instead.
91  */
92 GOOGLE_CLOUD_CPP_DEPRECATED("use `MakePublisherConnection(topic)` instead")
94  Topic topic, std::initializer_list<internal::NonConstructible>);
95 
96 /**
97  * Creates a new `PublisherConnection` object to work with `Publisher`.
98  *
99  * The `PublisherConnection` class is provided for applications wanting to mock
100  * the `Publisher` behavior in their tests. It is not intended for direct use.
101  *
102  * @par Performance
103  * Creating a new `PublisherConnection` is relatively expensive. This typically
104  * initiates connections to the service, and therefore these objects should be
105  * shared and reused when possible. Note that gRPC reuses existing OS resources
106  * (sockets) whenever possible, so applications may experience better
107  * performance on the second (and subsequent) calls to this function with the
108  * same `Options` from `GrpcOptionList` and `CommonOptionList`. However, this
109  * behavior is not guaranteed and applications should not rely on it.
110  *
111  * @see `PublisherConnection`
112  *
113  * @param topic the Cloud Pub/Sub topic used by the returned
114  * `PublisherConnection`.
115  * @param opts The options to use for this call. Expected options are any of
116  * the types in the following option lists.
117  * - `google::cloud::CommonOptionList`
118  * - `google::cloud::GrpcOptionList`
119  * - `google::cloud::pubsub::PolicyOptionList`
120  * - `google::cloud::pubsub::PublisherOptionList`
121  */
123  Options opts = {});
124 
125 /**
126  * Creates a new `PublisherConnection` object to work with `Publisher`.
127  *
128  * The `PublisherConnection` class is not intended for direct use in
129  * applications, it is provided for applications wanting to mock the
130  * `Publisher` behavior in their tests.
131  *
132  * @par Performance
133  * Creating a new `PublisherConnection` is relatively expensive. This typically
134  * initiate connections to the service, and therefore these objects should be
135  * shared and reused when possible. Note that gRPC reuses existing OS resources
136  * (sockets) whenever possible, so applications may experience better
137  * performance on the second (and subsequent) calls to this function with the
138  * identical values for @p options. However, this behavior is not guaranteed
139  * and applications should not rely on it.
140  *
141  * @see `PublisherConnection`
142  *
143  * @param topic the Cloud Pub/Sub topic used by the returned
144  * `PublisherConnection`.
145  * @param options configure the batching policy and other parameters in the
146  * returned connection.
147  * @param connection_options (optional) general configuration for this
148  * connection, this type is also used to configure `pubsub::Subscriber`.
149  * @param retry_policy (optional) configure the retry loop.
150  * @param backoff_policy (optional) configure the backoff period between
151  * retries.
152  *
153  * @deprecated Please use the `MakePublisherConnection` method which accepts
154  * `google::cloud::Options` instead.
155  */
156 GOOGLE_CLOUD_CPP_DEPRECATED(
157  "use the overload consuming google::cloud::Options instead")
159  Topic topic, PublisherOptions options,
160  ConnectionOptions connection_options = {},
161  std::unique_ptr<RetryPolicy const> retry_policy = {},
162  std::unique_ptr<BackoffPolicy const> backoff_policy = {});
163 
165 } // namespace pubsub
166 
167 namespace pubsub_internal {
169 
170 std::shared_ptr<pubsub::PublisherConnection> MakeTestPublisherConnection(
171  pubsub::Topic topic, Options opts,
172  std::vector<std::shared_ptr<PublisherStub>> stubs);
173 
175 } // namespace pubsub_internal
176 } // namespace cloud
177 } // namespace google
178 
179 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_PUBLISHER_CONNECTION_H