GODRIVER-2495 Undeprecate legacy timeouts. (#1026)

Uses NOTEs to suggest that users use Timeout instead of legacy timeout options as opposed to deprecating legacy timeout options.
mongodb · Jul 19, 2022 · e095f2d · e095f2d
1 parent 18da11c
commit e095f2d
Show file tree

Hide file tree

Showing 11 changed files with 108 additions and 106 deletions.
diff --git a/mongo/options/aggregateoptions.go b/mongo/options/aggregateoptions.go
@@ -35,9 +35,9 @@ type AggregateOptions struct {
 	// The maximum amount of time that the query can run on the server. The default value is nil, meaning that there
 	// is no time limit for query execution.
 	//
-	// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
-	// Timeout option should be used in its place to control the amount of time that the Aggregate operation can run before
-	// returning an error. MaxTime is still usable through the deprecated setter.
+	// NOTE(benjirewis): MaxTime will be deprecated in a future release. The more general Timeout option may be used
+	// in its place to control the amount of time that a single operation can run before returning an error. MaxTime
+	// is ignored if Timeout is set on the client.
 	MaxTime *time.Duration
 
 	// The maximum amount of time that the server should wait for new documents to satisfy a tailable cursor query.
@@ -96,9 +96,9 @@ func (ao *AggregateOptions) SetCollation(c *Collation) *AggregateOptions {
 
 // SetMaxTime sets the value for the MaxTime field.
 //
-// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver.
-// The more general Timeout option should be used in its place to control the amount of time that the
-// Aggregate operation can run before returning an error.
+// NOTE(benjirewis): MaxTime will be deprecated in a future release. The more general Timeout
+// option may be used in its place to control the amount of time that a single operation can
+// run before returning an error. MaxTime is ignored if Timeout is set on the client.
 func (ao *AggregateOptions) SetMaxTime(d time.Duration) *AggregateOptions {
 	ao.MaxTime = &d
 	return ao

diff --git a/mongo/options/clientoptions.go b/mongo/options/clientoptions.go
@@ -154,9 +154,9 @@ type ClientOptions struct {
 
 	// SocketTimeout specifies the timeout to be used for the Client's socket reads and writes.
 	//
-	// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
-	// Timeout option should be used in its place to control the amount of time that a single operation can run on the Client
-	// before returning an error. SocketTimeout is still usable through the deprecated setter.
+	// NOTE(benjirewis): SocketTimeout will be deprecated in a future release. The more general Timeout option
+	// may be used in its place to control the amount of time that a single operation can run before returning
+	// an error. Setting SocketTimeout and Timeout on a single client will result in undefined behavior.
 	SocketTimeout *time.Duration
 }
 
@@ -715,9 +715,9 @@ func (c *ClientOptions) SetServerSelectionTimeout(d time.Duration) *ClientOption
 // network error. This can also be set through the "socketTimeoutMS" URI option (e.g. "socketTimeoutMS=1000"). The
 // default value is 0, meaning no timeout is used and socket operations can block indefinitely.
 //
-// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
-// Timeout option should be used in its place to control the amount of time that a single operation can run on the Client
-// before returning an error.
+// NOTE(benjirewis): SocketTimeout will be deprecated in a future release. The more general Timeout option may be used
+// in its place to control the amount of time that a single operation can run before returning an error. Setting
+// SocketTimeout and Timeout on a single client will result in undefined behavior.
 func (c *ClientOptions) SetSocketTimeout(d time.Duration) *ClientOptions {
 	c.SocketTimeout = &d
 	return c
@@ -728,8 +728,9 @@ func (c *ClientOptions) SetSocketTimeout(d time.Duration) *ClientOptions {
 // be honored if there is no deadline on the operation Context. Timeout can also be set through the "timeoutMS" URI option
 // (e.g. "timeoutMS=1000"). The default value is nil, meaning operations do not inherit a timeout from the Client.
 //
-// If any Timeout is set (even 0) on the Client, the values of other, deprecated timeout-related options will be ignored.
-// In particular: ClientOptions.SocketTimeout, WriteConcern.wTimeout, MaxTime on operations, and TransactionOptions.MaxCommitTime.
+// If any Timeout is set (even 0) on the Client, the values of MaxTime on operations, TransactionOptions.MaxCommitTime and
+// SessionOptions.DefaultMaxCommitTime will be ignored. Setting Timeout and ClientOptions.SocketTimeout or WriteConcern.wTimeout
+// will result in undefined behavior.
 //
 // NOTE(benjirewis): SetTimeout represents unstable, provisional API. The behavior of the driver when a Timeout is specified is
 // subject to change.

diff --git a/mongo/options/countoptions.go b/mongo/options/countoptions.go
@@ -34,9 +34,9 @@ type CountOptions struct {
 	// The maximum amount of time that the query can run on the server. The default value is nil, meaning that there is
 	// no time limit for query execution.
 	//
-	// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
-	// Timeout option should be used in its place to control the amount of time that the count operation can run before
-	// returning an error. MaxTime is still usable through the deprecated setter.
+	// NOTE(benjirewis): MaxTime will be deprecated in a future release. The more general Timeout option may be used in
+	// its place to control the amount of time that a single operation can run before returning an error. MaxTime is
+	// ignored if Timeout is set on the client.
 	MaxTime *time.Duration
 
 	// The number of documents to skip before counting. The default value is 0.
@@ -74,9 +74,9 @@ func (co *CountOptions) SetLimit(i int64) *CountOptions {
 
 // SetMaxTime sets the value for the MaxTime field.
 //
-// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
-// Timeout option should be used in its place to control the amount of time that the count operation can run before
-// returning an error.
+// NOTE(benjirewis): MaxTime will be deprecated in a future release. The more general Timeout
+// option may be used in its place to control the amount of time that a single operation can
+// run before returning an error. MaxTime is ignored if Timeout is set on the client.
 func (co *CountOptions) SetMaxTime(d time.Duration) *CountOptions {
 	co.MaxTime = &d
 	return co

diff --git a/mongo/options/distinctoptions.go b/mongo/options/distinctoptions.go
@@ -22,9 +22,9 @@ type DistinctOptions struct {
 	// The maximum amount of time that the query can run on the server. The default value is nil, meaning that there
 	// is no time limit for query execution.
 	//
-	// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
-	// Timeout option should be used in its place to control the amount of time that the Distinct operation can run before
-	// returning an error. MaxTime is still usable through the deprecated setter.
+	// NOTE(benjirewis): MaxTime will be deprecated in a future release. The more general Timeout option may be
+	// used in its place to control the amount of time that a single operation can run before returning an error.
+	// MaxTime is ignored if Timeout is set on the client.
 	MaxTime *time.Duration
 }
 
@@ -47,9 +47,9 @@ func (do *DistinctOptions) SetComment(comment interface{}) *DistinctOptions {
 
 // SetMaxTime sets the value for the MaxTime field.
 //
-// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
-// Timeout option should be used in its place to control the amount of time that the Distinct operation can run before
-// returning an error.
+// NOTE(benjirewis): MaxTime will be deprecated in a future release. The more general Timeout
+// option may be used in its place to control the amount of time that a single operation can
+// run before returning an error. MaxTime is ignored if Timeout is set on the client.
 func (do *DistinctOptions) SetMaxTime(d time.Duration) *DistinctOptions {
 	do.MaxTime = &d
 	return do

diff --git a/mongo/options/estimatedcountoptions.go b/mongo/options/estimatedcountoptions.go
@@ -17,9 +17,9 @@ type EstimatedDocumentCountOptions struct {
 	// The maximum amount of time that the query can run on the server. The default value is nil, meaning that there
 	// is no time limit for query execution.
 	//
-	// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
-	// Timeout option should be used in its place to control the amount of time that the EstimatedDocumentCount operation
-	// can run before returning an error. MaxTime is still usable through the deprecated setter.
+	// NOTE(benjirewis): MaxTime will be deprecated in a future release. The more general Timeout option may be used
+	// in its place to control the amount of time that a single operation can run before returning an error. MaxTime
+	// is ignored if Timeout is set on the client.
 	MaxTime *time.Duration
 }
 
@@ -36,9 +36,9 @@ func (eco *EstimatedDocumentCountOptions) SetComment(comment interface{}) *Estim
 
 // SetMaxTime sets the value for the MaxTime field.
 //
-// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
-// Timeout option should be used in its place to control the amount of time that the EstimatedDocumentCount operation
-// can run before returning an error.
+// NOTE(benjirewis): MaxTime will be deprecated in a future release. The more general Timeout option
+// may be used in its place to control the amount of time that a single operation can run before
+// returning an error. MaxTime is ignored if Timeout is set on the client.
 func (eco *EstimatedDocumentCountOptions) SetMaxTime(d time.Duration) *EstimatedDocumentCountOptions {
 	eco.MaxTime = &d
 	return eco

diff --git a/mongo/options/findoptions.go b/mongo/options/findoptions.go
@@ -60,9 +60,9 @@ type FindOptions struct {
 	// MaxTime is the maximum amount of time that the query can run on the server. The default value is nil, meaning that there
 	// is no time limit for query execution.
 	//
-	// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
-	// Timeout option should be used in its place to control the amount of time that the Find operation can run before
-	// returning an error. MaxTime is still usable through the deprecated setter.
+	// NOTE(benjirewis): MaxTime will be deprecated in a future release. The more general Timeout option may be used in its
+	// place to control the amount of time that a single operation can run before returning an error. MaxTime is ignored if
+	// Timeout is set on the client.
 	MaxTime *time.Duration
 
 	// Min is a document specifying the inclusive lower bound for a specific index. The default value is 0, which means that
@@ -184,9 +184,9 @@ func (f *FindOptions) SetMaxAwaitTime(d time.Duration) *FindOptions {
 
 // SetMaxTime specifies the max time to allow the query to run.
 //
-// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver.
-// The more general Timeout option should be used in its place to control the amount of time that the
-// Find operation can run before returning an error.
+// NOTE(benjirewis): MaxTime will be deprecated in a future release. The more general Timeout
+// option may be used used in its place to control the amount of time that a single operation
+// can run before returning an error. MaxTime is ignored if Timeout is set on the client.
 func (f *FindOptions) SetMaxTime(d time.Duration) *FindOptions {
 	f.MaxTime = &d
 	return f
@@ -370,9 +370,9 @@ type FindOneOptions struct {
 	// The maximum amount of time that the query can run on the server. The default value is nil, meaning that there
 	// is no time limit for query execution.
 	//
-	// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
-	// Timeout option should be used in its place to control the amount of time that the FindOne operation can run before
-	// returning an error. MaxTime is still usable through the deprecated setter.
+	// NOTE(benjirewis): MaxTime will be deprecated in a future release. The more general Timeout option may be used
+	// in its place to control the amount of time that a single operation can run before returning an error. MaxTime
+	// is ignored if Timeout is set on the client.
 	MaxTime *time.Duration
 
 	// A document specifying the inclusive lower bound for a specific index. The default value is 0, which means that
@@ -478,9 +478,9 @@ func (f *FindOneOptions) SetMaxAwaitTime(d time.Duration) *FindOneOptions {
 
 // SetMaxTime sets the value for the MaxTime field.
 //
-// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
-// Timeout option should be used in its place to control the amount of time that the FindOne operation can run before
-// returning an error.
+// NOTE(benjirewis): MaxTime will be deprecated in a future release. The more general Timeout
+// option may be used in its place to control the amount of time that a single operation can
+// run before returning an error. MaxTime is ignored if Timeout is set on the client.
 func (f *FindOneOptions) SetMaxTime(d time.Duration) *FindOneOptions {
 	f.MaxTime = &d
 	return f
@@ -634,9 +634,9 @@ type FindOneAndReplaceOptions struct {
 	// The maximum amount of time that the query can run on the server. The default value is nil, meaning that there
 	// is no time limit for query execution.
 	//
-	// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
-	// Timeout option should be used in its place to control the amount of time that the FindOneAndReplace operation can
-	// run before returning an error. MaxTime is still usable through the deprecated setter.
+	// NOTE(benjirewis): MaxTime will be deprecated in a future release. The more general Timeout option may be used
+	// in its place to control the amount of time that a single operation can run before returning an error. MaxTime
+	// is ignored if Timeout is set on the client.
 	MaxTime *time.Duration
 
 	// A document describing which fields will be included in the document returned by the operation. The default value
@@ -696,9 +696,9 @@ func (f *FindOneAndReplaceOptions) SetComment(comment interface{}) *FindOneAndRe
 
 // SetMaxTime sets the value for the MaxTime field.
 //
-// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
-// Timeout option should be used in its place to control the amount of time that the FindOneAndReplace operation can
-// run before returning an error.
+// NOTE(benjirewis): MaxTime will be deprecated in a future release. The more general Timeout
+// option may be used in its place to control the amount of time that a single operation can
+// run before returning an error. MaxTime is ignored if Timeout is set on the client.
 func (f *FindOneAndReplaceOptions) SetMaxTime(d time.Duration) *FindOneAndReplaceOptions {
 	f.MaxTime = &d
 	return f
@@ -808,9 +808,9 @@ type FindOneAndUpdateOptions struct {
 	// The maximum amount of time that the query can run on the server. The default value is nil, meaning that there
 	// is no time limit for query execution.
 	//
-	// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
-	// Timeout option should be used in its place to control the amount of time that the FindOneAndUpdate operation can run
-	// before returning an error. MaxTime is still usable through the deprecated setter.
+	// NOTE(benjirewis): MaxTime will be deprecated in a future release. The more general Timeout option may be used
+	// in its place to control the amount of time that a single operation can run before returning an error. MaxTime is
+	// ignored if Timeout is set on the client.
 	MaxTime *time.Duration
 
 	// A document describing which fields will be included in the document returned by the operation. The default value
@@ -876,9 +876,9 @@ func (f *FindOneAndUpdateOptions) SetComment(comment interface{}) *FindOneAndUpd
 
 // SetMaxTime sets the value for the MaxTime field.
 //
-// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
-// Timeout option should be used in its place to control the amount of time that the FindOneAndUpdate operation can run
-// before returning an error.
+// NOTE(benjirewis): MaxTime will be deprecated in a future release. The more general Timeout
+// option may be used in its place to control the amount of time that a single operation can
+// run before returning an error. MaxTime is ignored if Timeout is set on the client.
 func (f *FindOneAndUpdateOptions) SetMaxTime(d time.Duration) *FindOneAndUpdateOptions {
 	f.MaxTime = &d
 	return f
@@ -980,9 +980,9 @@ type FindOneAndDeleteOptions struct {
 	// The maximum amount of time that the query can run on the server. The default value is nil, meaning that there
 	// is no time limit for query execution.
 	//
-	// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
-	// Timeout option should be used in its place to control the amount of time that the FindOneAndDelete operation can run
-	// before returning an error. MaxTime is still usable through the deprecated setter.
+	// NOTE(benjirewis): MaxTime will be deprecated in a future release. The more general Timeout option may be used
+	// in its place to control the amount of time that a single operation can run before returning an error. MaxTime
+	// is ignored if Timeout is set on the client.
 	MaxTime *time.Duration
 
 	// A document describing which fields will be included in the document returned by the operation. The default value
@@ -1028,9 +1028,9 @@ func (f *FindOneAndDeleteOptions) SetComment(comment interface{}) *FindOneAndDel
 
 // SetMaxTime sets the value for the MaxTime field.
 //
-// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
-// Timeout option should be used in its place to control the amount of time that the FindOneAndDelete operation can run
-// before returning an error.
+// NOTE(benjirewis): MaxTime will be deprecated in a future release. The more general Timeout
+// option may be used in its place to control the amount of time that a single operation can
+// run before returning an error. MaxTime is ignored if Timeout is set on the client.
 func (f *FindOneAndDeleteOptions) SetMaxTime(d time.Duration) *FindOneAndDeleteOptions {
 	f.MaxTime = &d
 	return f

diff --git a/mongo/options/gridfsoptions.go b/mongo/options/gridfsoptions.go
@@ -226,9 +226,9 @@ type GridFSFindOptions struct {
 	// The maximum amount of time that the query can run on the server. The default value is nil, meaning that there
 	// is no time limit for query execution.
 	//
-	// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver. The more general
-	// Timeout option should be used in its place to control the amount of time that GridFS operations can run before
-	// returning an error. MaxTime is still usable through the deprecated setter.
+	// NOTE(benjirewis): MaxTime will be deprecated in a future release. The more general Timeout option may be used
+	// in its place to control the amount of time that a single operation can run before returning an error. MaxTime
+	// is ignored if Timeout is set on the client.
 	MaxTime *time.Duration
 
 	// If true, the cursor created by the operation will not timeout after a period of inactivity. The default value
@@ -268,9 +268,9 @@ func (f *GridFSFindOptions) SetLimit(i int32) *GridFSFindOptions {
 
 // SetMaxTime sets the value for the MaxTime field.
 //
-// Deprecated: This option is deprecated and will eventually be removed in version 2.0 of the driver.
-// The more general Timeout option should be used in its place to control the amount of time that
-// GridFS operations can run before returning an error.
+// NOTE(benjirewis): MaxTime will be deprecated in a future release. The more general Timeout
+// option may be used in its place to control the amount of time that a single operation can
+// run before returning an error. MaxTime is ignored if Timeout is set on the client.
 func (f *GridFSFindOptions) SetMaxTime(d time.Duration) *GridFSFindOptions {
 	f.MaxTime = &d
 	return f