Documentation
¶
Overview ¶
Package session is intended for internal use only. It is made available to facilitate use cases that require access to internal MongoDB driver functionality and state. The API of this package is not stable and there is no backward compatibility guarantee.
WARNING: THIS PACKAGE IS EXPERIMENTAL AND MAY BE MODIFIED OR REMOVED WITHOUT NOTICE! USE WITH EXTREME CAUTION!
Index ¶
- Constants
- Variables
- func MaxClusterTime(ct1, ct2 bson.Raw) bson.Raw
- type Client
- func (c *Client) AbortTransaction() error
- func (c *Client) AdvanceClusterTime(clusterTime bson.Raw) error
- func (c *Client) AdvanceOperationTime(opTime *primitive.Timestamp) error
- func (c *Client) ApplyCommand(desc description.Server) error
- func (c *Client) CheckAbortTransaction() error
- func (c *Client) CheckCommitTransaction() error
- func (c *Client) CheckStartTransaction() error
- func (c *Client) ClearPinnedResources() error
- func (c *Client) CommitTransaction() error
- func (c *Client) EndSession()
- func (c *Client) SetServer() error
- func (c *Client) StartCommand() error
- func (c *Client) StartTransaction(opts *TransactionOptions) error
- func (c *Client) TransactionCommitted() bool
- func (c *Client) TransactionInProgress() bool
- func (c *Client) TransactionRunning() bool
- func (c *Client) TransactionStarting() bool
- func (c *Client) UpdateCommitTransactionWriteConcern()
- func (c *Client) UpdateRecoveryToken(response bson.Raw)
- func (c *Client) UpdateSnapshotTime(response bsoncore.Document)
- func (c *Client) UpdateUseTime() error
- type ClientOptions
- type ClusterClock
- type LoadBalancedTransactionConnection
- type Node
- type Pool
- type Server
- type TransactionOptions
- type TransactionState
Constants ¶
const UUIDSubtype byte = 4
UUIDSubtype is the BSON binary subtype that a UUID should be encoded as
Variables ¶
var ErrAbortAfterCommit = errors.New("cannot call abortTransaction after calling commitTransaction")
ErrAbortAfterCommit is returned when abort is called after a commit.
var ErrAbortTwice = errors.New("cannot call abortTransaction twice")
ErrAbortTwice is returned if abort is called after transaction is already aborted.
var ErrCommitAfterAbort = errors.New("cannot call commitTransaction after calling abortTransaction")
ErrCommitAfterAbort is returned if commit is called after an abort.
var ErrNoTransactStarted = errors.New("no transaction started")
ErrNoTransactStarted is returned if a transaction operation is called when no transaction has started.
var ErrSessionEnded = errors.New("ended session was used")
ErrSessionEnded is returned when a client session is used after a call to endSession().
var ErrSnapshotTransaction = errors.New("transactions are not supported in snapshot sessions")
ErrSnapshotTransaction is returned if an transaction is started on a snapshot session.
var ErrTransactInProgress = errors.New("transaction already in progress")
ErrTransactInProgress is returned if startTransaction() is called when a transaction is in progress.
var ErrUnackWCUnsupported = errors.New("transactions do not support unacknowledged write concerns")
ErrUnackWCUnsupported is returned if an unacknowledged write concern is supported for a transaction.
Functions ¶
Types ¶
type Client ¶
type Client struct {
*Server
ClientID uuid.UUID
ClusterTime bson.Raw
Consistent bool // causal consistency
OperationTime *primitive.Timestamp
IsImplicit bool
Terminated bool
RetryingCommit bool
Committing bool
Aborting bool
RetryWrite bool
RetryRead bool
Snapshot bool
// options for the current transaction
// most recently set by transactionopt
CurrentRc *readconcern.ReadConcern
CurrentRp *readpref.ReadPref
CurrentWc *writeconcern.WriteConcern
CurrentMct *time.Duration
TransactionState TransactionState
PinnedServer *description.Server
RecoveryToken bson.Raw
PinnedConnection LoadBalancedTransactionConnection
SnapshotTime *primitive.Timestamp
// contains filtered or unexported fields
}
Client is a session for clients to run commands.
func NewClientSession ¶
NewClientSession creates a new explicit client-side session.
func NewImplicitClientSession ¶ added in v1.11.2
NewImplicitClientSession creates a new implicit client-side session.
func (*Client) AbortTransaction ¶
AbortTransaction updates the state for a successfully aborted transaction and returns an error if not permissible. It does not actually perform the abort.
func (*Client) AdvanceClusterTime ¶
AdvanceClusterTime updates the session's cluster time.
func (*Client) AdvanceOperationTime ¶
AdvanceOperationTime updates the session's operation time.
func (*Client) ApplyCommand ¶
func (c *Client) ApplyCommand(desc description.Server) error
ApplyCommand advances the state machine upon command execution. This must be called after server selection is complete.
func (*Client) CheckAbortTransaction ¶
CheckAbortTransaction checks to see if allowed to abort transaction and returns an error if not allowed.
func (*Client) CheckCommitTransaction ¶
CheckCommitTransaction checks to see if allowed to commit transaction and returns an error if not allowed.
func (*Client) CheckStartTransaction ¶
CheckStartTransaction checks to see if allowed to start transaction and returns an error if not allowed
func (*Client) ClearPinnedResources ¶ added in v1.6.0
ClearPinnedResources clears the pinned server and/or connection associated with the session.
func (*Client) CommitTransaction ¶
CommitTransaction updates the state for a successfully committed transaction and returns an error if not permissible. It does not actually perform the commit.
func (*Client) SetServer ¶ added in v1.11.0
SetServer will check out a session from the client session pool.
func (*Client) StartCommand ¶ added in v1.6.0
StartCommand updates the session's internal state at the beginning of an operation. This must be called before server selection is done for the operation as the session's state can impact the result of that process.
func (*Client) StartTransaction ¶
func (c *Client) StartTransaction(opts *TransactionOptions) error
StartTransaction initializes the transaction options and advances the state machine. It does not contact the server to start the transaction.
func (*Client) TransactionCommitted ¶
TransactionCommitted returns true of the client session just committed a transaction.
func (*Client) TransactionInProgress ¶
TransactionInProgress returns true if the client session is in an active transaction.
func (*Client) TransactionRunning ¶
TransactionRunning returns true if the client session has started the transaction and it hasn't been committed or aborted
func (*Client) TransactionStarting ¶
TransactionStarting returns true if the client session is starting a transaction.
func (*Client) UpdateCommitTransactionWriteConcern ¶ added in v1.1.0
func (c *Client) UpdateCommitTransactionWriteConcern()
UpdateCommitTransactionWriteConcern will set the write concern to majority and potentially set a w timeout of 10 seconds. This should be called after a commit transaction operation fails with a retryable error or after a successful commit transaction operation.
func (*Client) UpdateRecoveryToken ¶ added in v1.1.0
UpdateRecoveryToken updates the session's recovery token from the server response.
func (*Client) UpdateSnapshotTime ¶ added in v1.7.0
UpdateSnapshotTime updates the session's value for the atClusterTime field of ReadConcern.
func (*Client) UpdateUseTime ¶
UpdateUseTime sets the session's last used time to the current time. This must be called whenever the session is used to send a command to the server to ensure that the session is not prematurely marked expired in the driver's session pool. If the session has already been ended, this method will return ErrSessionEnded.
type ClientOptions ¶
type ClientOptions struct {
CausalConsistency *bool
DefaultReadConcern *readconcern.ReadConcern
DefaultWriteConcern *writeconcern.WriteConcern
DefaultReadPreference *readpref.ReadPref
DefaultMaxCommitTime *time.Duration
Snapshot *bool
}
ClientOptions represents all possible options for creating a client session.
type ClusterClock ¶
type ClusterClock struct {
// contains filtered or unexported fields
}
ClusterClock represents a logical clock for keeping track of cluster time.
func (*ClusterClock) AdvanceClusterTime ¶
func (cc *ClusterClock) AdvanceClusterTime(clusterTime bson.Raw)
AdvanceClusterTime updates the cluster's current time.
func (*ClusterClock) GetClusterTime ¶
func (cc *ClusterClock) GetClusterTime() bson.Raw
GetClusterTime returns the cluster's current time.
type LoadBalancedTransactionConnection ¶ added in v1.6.0
type LoadBalancedTransactionConnection interface {
// Functions copied over from driver.Connection.
WriteWireMessage(context.Context, []byte) error
ReadWireMessage(ctx context.Context) ([]byte, error)
Description() description.Server
Close() error
ID() string
ServerConnectionID() *int64
DriverConnectionID() uint64 // TODO(GODRIVER-2824): change type to int64.
Address() address.Address
Stale() bool
OIDCTokenGenID() uint64
SetOIDCTokenGenID(uint64)
// Functions copied over from driver.PinnedConnection that are not part of Connection or Expirable.
PinToCursor() error
PinToTransaction() error
UnpinFromCursor() error
UnpinFromTransaction() error
}
LoadBalancedTransactionConnection represents a connection that's pinned by a ClientSession because it's being used to execute a transaction when running against a load balancer. This interface is a copy of driver.PinnedConnection and exists to be able to pin transactions to a connection without causing an import cycle.
type Node ¶
type Node struct {
*Server
// contains filtered or unexported fields
}
Node represents a server session in a linked list
type Pool ¶
type Pool struct {
// contains filtered or unexported fields
}
Pool is a pool of server sessions that can be reused.
func NewPool ¶
func NewPool(descChan <-chan description.Topology) *Pool
NewPool creates a new server session pool
func (*Pool) CheckedOut ¶
CheckedOut returns number of sessions checked out from pool.
func (*Pool) GetSession ¶
GetSession retrieves an unexpired session from the pool.
func (*Pool) ReturnSession ¶
ReturnSession returns a session to the pool if it has not expired.
type Server ¶
Server is an open session with the server.
func (*Server) IncrementTxnNumber ¶
func (ss *Server) IncrementTxnNumber()
IncrementTxnNumber increments the transaction number.
type TransactionOptions ¶
type TransactionOptions struct {
ReadConcern *readconcern.ReadConcern
WriteConcern *writeconcern.WriteConcern
ReadPreference *readpref.ReadPref
MaxCommitTime *time.Duration
}
TransactionOptions represents all possible options for starting a transaction in a session.
type TransactionState ¶ added in v1.5.0
type TransactionState uint8
TransactionState indicates the state of the transactions FSM.
const ( None TransactionState = iota Starting InProgress Committed Aborted )
Client Session states
func (TransactionState) String ¶ added in v1.5.0
func (s TransactionState) String() string
String implements the fmt.Stringer interface.