Skip to content

Commit 8ac4432

Browse files
authored
docs(pubsub): clarify NumGoroutines configures number of streams (#7874)
* docs(pubsub): clarify NumGoroutines configures number of streams * explicitly discourage setting a high number of streams * fix formatting in comment
1 parent d661fe9 commit 8ac4432

File tree

2 files changed

+14
-10
lines changed

2 files changed

+14
-10
lines changed

pubsub/doc.go

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -91,15 +91,20 @@ pull method.
9191
9292
# Streams Management
9393
94-
Streams used for streaming pull are configured by setting sub.ReceiveSettings.NumGoroutines.
95-
However, the total number of streams possible is capped by the gRPC connection pool setting.
96-
By default, the number of connections in the pool is min(4,GOMAXPROCS).
97-
98-
If you have 4 or more CPU cores, the default setting allows a maximum of 400 streams which is still a good default for most cases.
99-
If you want to have more open streams (such as for low CPU core machines), you should pass in the grpc option as described below:
94+
The number of StreamingPull connections can be configured by setting sub.ReceiveSettings.NumGoroutines.
95+
The default value of 10 means the client library will maintain 10 StreamingPull connections.
96+
This is more than sufficient for most use cases, as StreamingPull connections can handle up to
97+
10 MB/s https://cloud.google.com/pubsub/quotas#resource_limits. In some cases, using too many streams
98+
can lead to client library behaving poorly as the application becomes I/O bound.
99+
100+
By default, the number of connections in the gRPC conn pool is min(4,GOMAXPROCS). Each connection supports
101+
up to 100 streams. Thus, if you have 4 or more CPU cores, the default setting allows a maximum of 400 streams
102+
which is already excessive for most use cases.
103+
If you want to change the limits on the number of streams, you can change the number of connections
104+
in the gRPC connection pool as shown below:
100105
101106
opts := []option.ClientOption{
102-
option.WithGRPCConnectionPool(8),
107+
option.WithGRPCConnectionPool(2),
103108
}
104109
client, err := pubsub.NewClient(ctx, projID, opts...)
105110

pubsub/subscription.go

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -690,9 +690,8 @@ type ReceiveSettings struct {
690690
// The default is false.
691691
UseLegacyFlowControl bool
692692

693-
// NumGoroutines is the number of goroutines that each datastructure along
694-
// the Receive path will spawn. Adjusting this value adjusts concurrency
695-
// along the receive path.
693+
// NumGoroutines sets the number of StreamingPull streams to pull messages
694+
// from the subscription.
696695
//
697696
// NumGoroutines defaults to DefaultReceiveSettings.NumGoroutines.
698697
//

0 commit comments

Comments
 (0)