DOCSP-37046: csot in v2 #375
Conversation
| options. You can pass the connection options as parameters of the connection | ||
| URI to specify the behavior of the client. |
There was a problem hiding this comment.
S:
| options. You can pass the connection options as parameters of the connection | |
| URI to specify the behavior of the client. | |
| options. You can pass the connection options as parameters in the connection | |
| URI to specify the behavior of the client. |
| - Specifies the number of milliseconds to wait before timeout on a TCP | ||
| connection. |
There was a problem hiding this comment.
This might be out of scope of this PR, but what is a TCP connection? Should readers know this already?
There was a problem hiding this comment.
Rewrote the desc to leave the acronym out (simplify)
| You can set a single ``Timeout`` option on your ``Client`` instance to | ||
| specify the amount of time that a single operation can take to execute. |
There was a problem hiding this comment.
| You can set a single ``Timeout`` option on your ``Client`` instance to | |
| specify the amount of time that a single operation can take to execute. | |
| You can set a single ``Timeout`` option on your ``Client`` instance to | |
| specify the maximum amount of time that a single operation can take to execute. |
| Set a timeout by using the ``SetTimeout()`` method or specifying the | ||
| ``timeoutMS`` option in your connection URI string. ``Database``, ``Collection``, |
There was a problem hiding this comment.
| Set a timeout by using the ``SetTimeout()`` method or specifying the | |
| ``timeoutMS`` option in your connection URI string. ``Database``, ``Collection``, | |
| Set a timeout by calling the ``SetTimeout()`` method on a ``Client`` instance, or by specifying the | |
| ``timeoutMS`` option in your connection URI string. ``Database``, ``Collection``, |
| ``timeoutMS`` option in your connection URI string. ``Database``, ``Collection``, | ||
| ``Session``, ``ChangeStream``, and ``Bucket`` instances elsewhere in | ||
| your code inherit the ``Timeout`` option from ``Client`` if you do not | ||
| set a different timeout in a Context for specific operations. |
There was a problem hiding this comment.
S: This sentence was a little bit hard to make sense of at first. I think splitting and rearranging some might help. Something like this maybe?
| ``timeoutMS`` option in your connection URI string. ``Database``, ``Collection``, | |
| ``Session``, ``ChangeStream``, and ``Bucket`` instances elsewhere in | |
| your code inherit the ``Timeout`` option from ``Client`` if you do not | |
| set a different timeout in a Context for specific operations. | |
| ``timeoutMS`` option in your connection URI string. By default, all ``Database``, ``Collection``, | |
| ``Session``, ``ChangeStream``, and ``Bucket`` instances elsewhere in | |
| your code inherit the ``Timeout`` option from ``Client``. However, you can | |
| set a different timeout for specific operations in the operation's Context. |
| Single Timeout Setting | ||
| ---------------------- | ||
|
|
||
| You can set a single ``Timeout`` option on your ``Client`` instance to |
There was a problem hiding this comment.
Should "Timeout" be monospaced here? It seems like it's being used as a parameter/option name, but looking at the examples below it doesn't look like we actually have an option named "Timeout" that you can set.
There was a problem hiding this comment.
The SetTimeout() method sets the Timeout struct field of the Client options struct.
Do you think this should be clarified in the doc?
There was a problem hiding this comment.
Ahh I see, that makes more sense. I think it's probably okay then, people more familiar with Go will likely understand that
| If you pass a Context into an operation with a deadline, the driver uses | ||
| that Context deadline for the operation. If the context does not have a | ||
| deadline, the driver derives a new Context from the given Context by using | ||
| the ``Timeout`` option set on the ``Client``. |
There was a problem hiding this comment.
This might be due to me not being very familiar with Go, but this paragraph is confusing to me. It seems a bit jarring to be talking about setting timeouts, but then the next paragraph is talking about using Context deadlines. Is a "deadline" the same thing as a timeout? If so I think we should stick with that wording. Happy to workshop some ways to rephrase this once I have a better understanding of what it's trying to say.
There was a problem hiding this comment.
Will clean this up (old text)
| The following example shows how you can set a single timeout with the | ||
| URI option and execute an operation that inherits this setting: |
There was a problem hiding this comment.
| The following example shows how you can set a single timeout with the | |
| URI option and execute an operation that inherits this setting: | |
| The following example shows how to set a single timeout with the | |
| URI option. It then executes an operation that inherits this timeout. |
| The following example shows how you can set the ``Timeout`` option on a | ||
| ``Client`` instance, then set a different timeout for an insert option | ||
| within the Context passed to the ``InsertOne()`` method: |
There was a problem hiding this comment.
| The following example shows how you can set the ``Timeout`` option on a | |
| ``Client`` instance, then set a different timeout for an insert option | |
| within the Context passed to the ``InsertOne()`` method: | |
| The following example shows how to set the ``Timeout`` option on a | |
| ``Client`` instance. It then sets a different timeout | |
| within the Context passed to the ``InsertOne()`` method: |
| .. code-block:: go | ||
|
|
||
| uri := "mongodb://user:[email protected]:27017/?timeoutMS=5000" | ||
|
|
||
| client, err := mongo.Connect(options.Client().ApplyURI(uri)) | ||
|
|
||
| ... | ||
| coll.InsertOne(context.Background(), doc) |
There was a problem hiding this comment.
S: Highlight line 1. And maybe line 7?
| Single Timeout Setting | ||
| ---------------------- | ||
|
|
||
| You can set a single ``Timeout`` option on your ``Client`` instance to |
There was a problem hiding this comment.
Ahh I see, that makes more sense. I think it's probably okay then, people more familiar with Go will likely understand that
|
|
||
| .. note:: Retries under Timeout Specification | ||
|
|
||
| When using default settings, if you set a ``Timeout`` option on your ``Client`` |
There was a problem hiding this comment.
This behavior is true for a client-level or operation-level (context.Context) CSOT. I would also clarify that this only happens if the server returns a "retryable" error, such as a socket exception.
| opts := options.Client().SetTimeout(5 * time.Second) | ||
| client, err := mongo.Connect(opts) | ||
|
|
||
| Connection String Option |
There was a problem hiding this comment.
Suggest specifying that the timeoutMS query parameter is a client-level timeout.
| ... | ||
| coll.InsertOne(context.Background(), doc) | ||
|
|
||
| Multiple Timeouts |
There was a problem hiding this comment.
Suggest renaming this section to "Operation Timeout"
| opts := options.Client().SetTimeout(5 * time.Second) | ||
| client, err := mongo.Connect(opts) |
There was a problem hiding this comment.
I don't think it's necessary to show this. For an operation-level timeout, it doesn't matter if a client-timeout is set or not, the operation timeout takes priority. Suggest removing this line and updating the description of this example:
The following example shows how to set an operation-level timeout, which
takes priority over a client-level timeout if one is defined:
Pull Request Info
PR Reviewing Guidelines
JIRA - https://jira.mongodb.org/browse/DOCSP-37046
Staging:
Self-Review Checklist