Google Cloud Pub/Sub C++ Client  1.34.1
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 // 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_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/non_constructible.h"
21 #include "google/cloud/pubsub/internal/publisher_stub.h"
22 #include "google/cloud/pubsub/message.h"
23 #include "google/cloud/pubsub/publisher_options.h"
24 #include "google/cloud/pubsub/retry_policy.h"
25 #include "google/cloud/pubsub/topic.h"
26 #include "google/cloud/pubsub/version.h"
27 #include "google/cloud/future.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  */
93  Topic topic, std::initializer_list<pubsub_internal::NonConstructible>);
94 
95 /**
96  * Creates a new `PublisherConnection` object to work with `Publisher`.
97  *
98  * The `PublisherConnection` class is provided for applications wanting to mock
99  * the `Publisher` behavior in their tests. It is not intended for direct use.
100  *
101  * @par Performance
102  * Creating a new `PublisherConnection` is relatively expensive. This typically
103  * initiates connections to the service, and therefore these objects should be
104  * shared and reused when possible. Note that gRPC reuses existing OS resources
105  * (sockets) whenever possible, so applications may experience better
106  * performance on the second (and subsequent) calls to this function with the
107  * same `Options` from `GrpcOptionList` and `CommonOptionList`. However, this
108  * behavior is not guaranteed and applications should not rely on it.
109  *
110  * @see `PublisherConnection`
111  *
112  * @param topic the Cloud Pub/Sub topic used by the returned
113  * `PublisherConnection`.
114  * @param opts The options to use for this call. Expected options are any of
115  * the types in the following option lists.
116  * - `google::cloud::CommonOptionList`
117  * - `google::cloud::GrpcOptionList`
118  * - `google::cloud::pubsub::PolicyOptionList`
119  * - `google::cloud::pubsub::PublisherOptionList`
120  */
122  Options opts = {});
123 
124 /**
125  * Creates a new `PublisherConnection` object to work with `Publisher`.
126  *
127  * The `PublisherConnection` class is not intended for direct use in
128  * applications, it is provided for applications wanting to mock the
129  * `Publisher` behavior in their tests.
130  *
131  * @par Performance
132  * Creating a new `PublisherConnection` is relatively expensive. This typically
133  * initiate connections to the service, and therefore these objects should be
134  * shared and reused when possible. Note that gRPC reuses existing OS resources
135  * (sockets) whenever possible, so applications may experience better
136  * performance on the second (and subsequent) calls to this function with the
137  * same `ConnectionOptions` parameters. However, this behavior is not guaranteed
138  * and applications should not rely on it.
139  *
140  * @see `PublisherConnection`
141  *
142  * @param topic the Cloud Pub/Sub topic used by the returned
143  * `PublisherConnection`.
144  * @param options configure the batching policy and other parameters in the
145  * returned connection.
146  * @param connection_options (optional) general configuration for this
147  * connection, this type is also used to configure `pubsub::Subscriber`.
148  * @param retry_policy (optional) configure the retry loop.
149  * @param backoff_policy (optional) configure the backoff period between
150  * retries.
151  *
152  * @deprecated Please use the `MakePublisherConnection` method which accepts
153  * `google::cloud::Options` instead.
154  */
156  Topic topic, PublisherOptions options,
157  ConnectionOptions connection_options = {},
158  std::unique_ptr<RetryPolicy const> retry_policy = {},
159  std::unique_ptr<BackoffPolicy const> backoff_policy = {});
160 
162 } // namespace pubsub
163 
164 namespace pubsub_internal {
166 
167 std::shared_ptr<pubsub::PublisherConnection> MakeTestPublisherConnection(
168  pubsub::Topic topic, Options opts,
169  std::vector<std::shared_ptr<PublisherStub>> stubs);
170 
172 } // namespace pubsub_internal
173 } // namespace cloud
174 } // namespace google
175 
176 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_PUBLISHER_CONNECTION_H