GODRIVER-2453 extend session function comments with thread/fork warnings (#995)

Author: prestonvasquez

mongo/client.go

@@ -278,6 +278,9 @@ func (c *Client) Ping(ctx context.Context, rp *readpref.ReadPref) error {
 // StartSession does not actually communicate with the server and will not error if the client is
 // disconnected.
 //
+// StartSession is safe to call from multiple goroutines concurrently. However, Sessions returned by StartSession are
+// not safe for concurrent use by multiple goroutines.
+//
 // If the DefaultReadConcern, DefaultWriteConcern, or DefaultReadPreference options are not set, the client's read
 // concern, write concern, or read preference will be used, respectively.
 func (c *Client) StartSession(opts ...*options.SessionOptions) (Session, error) {
@@ -1023,6 +1026,9 @@ func (c *Client) ListDatabaseNames(ctx context.Context, filter interface{}, opts
 // SessionContext must be used as the Context parameter for any operations in the fn callback that should be executed
 // under the session.
 //
+// WithSession is safe to call from multiple goroutines concurrently. However, the SessionContext passed to the
+// WithSession callback function is not safe for concurrent use by multiple goroutines.
+//
 // If the ctx parameter already contains a Session, that Session will be replaced with the one provided.
 //
 // Any error returned by the fn callback will be returned without any modifications.
@@ -1035,6 +1041,9 @@ func WithSession(ctx context.Context, sess Session, fn func(SessionContext) erro
 // be executed under a session. After the callback returns, the created Session is ended, meaning that any in-progress
 // transactions started by fn will be aborted even if fn returns an error.
 //
+// UseSession is safe to call from multiple goroutines concurrently. However, the SessionContext passed to the
+// UseSession callback function is not safe for concurrent use by multiple goroutines.
+//
 // If the ctx parameter already contains a Session, that Session will be replaced with the newly created one.
 //
 // Any error returned by the fn callback will be returned without any modifications.
@@ -1043,6 +1052,9 @@ func (c *Client) UseSession(ctx context.Context, fn func(SessionContext) error)
 }
 
 // UseSessionWithOptions operates like UseSession but uses the given SessionOptions to create the Session.
+//
+// UseSessionWithOptions is safe to call from multiple goroutines concurrently. However, the SessionContext passed to
+// the UseSessionWithOptions callback function is not safe for concurrent use by multiple goroutines.
 func (c *Client) UseSessionWithOptions(ctx context.Context, opts *options.SessionOptions, fn func(SessionContext) error) error {
 	defaultSess, err := c.StartSession(opts)
 	if err != nil {

mongo/session.go

@@ -29,8 +29,9 @@ var ErrWrongClient = errors.New("session was not created by this client")
 var withTransactionTimeout = 120 * time.Second
 
 // SessionContext combines the context.Context and mongo.Session interfaces. It should be used as the Context arguments
-// to operations that should be executed in a session. This type is not goroutine safe and must not be used concurrently
-// by multiple goroutines.
+// to operations that should be executed in a session.
+//
+// Implementations of SessionContext are not safe for concurrent use by multiple goroutines.
 //
 // There are two ways to create a SessionContext and use it in a session/transaction. The first is to use one of the
 // callback-based functions such as WithSession and UseSession. These functions create a SessionContext and pass it to
@@ -77,10 +78,13 @@ func SessionFromContext(ctx context.Context) Session {
 // for a group of operations or to execute operations in an ACID transaction. A new Session can be created from a Client
 // instance. A Session created from a Client must only be used to execute operations using that Client or a Database or
 // Collection created from that Client. Custom implementations of this interface should not be used in production. For
-// more information about sessions, and their use cases, see https://www.mongodb.com/docs/manual/reference/server-sessions/,
+// more information about sessions, and their use cases, see
+// https://www.mongodb.com/docs/manual/reference/server-sessions/,
 // https://www.mongodb.com/docs/manual/core/read-isolation-consistency-recency/#causal-consistency, and
 // https://www.mongodb.com/docs/manual/core/transactions/.
 //
+// Implementations of Session are not safe for concurrent use by multiple goroutines.
+//
 // StartTransaction starts a new transaction, configured with the given options, on this session. This method will
 // return an error if there is already a transaction in-progress for this session.
 //