session

package
v2.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 20, 2025 License: Apache-2.0 Imports: 13 Imported by: 4

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

View Source 
const UUIDSubtype byte = 4

UUIDSubtype is the BSON binary subtype that a UUID should be encoded as

Variables

View Source 
var ErrAbortAfterCommit = errors.New("cannot call abortTransaction after calling commitTransaction")

ErrAbortAfterCommit is returned when abort is called after a commit.

View Source 
var ErrAbortTwice = errors.New("cannot call abortTransaction twice")

ErrAbortTwice is returned if abort is called after transaction is already aborted.

View Source 
var ErrCommitAfterAbort = errors.New("cannot call commitTransaction after calling abortTransaction")

ErrCommitAfterAbort is returned if commit is called after an abort.

View Source 
var ErrNoTransactStarted = errors.New("no transaction started")

ErrNoTransactStarted is returned if a transaction operation is called when no transaction has started.

View Source 
var ErrSessionEnded = errors.New("ended session was used")

ErrSessionEnded is returned when a client session is used after a call to endSession().

View Source 
var ErrSnapshotTransaction = errors.New("transactions are not supported in snapshot sessions")

ErrSnapshotTransaction is returned if an transaction is started on a snapshot session.

View Source 
var ErrTransactInProgress = errors.New("transaction already in progress")

ErrTransactInProgress is returned if startTransaction() is called when a transaction is in progress.

View Source 
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

func MaxClusterTime 

func MaxClusterTime(ct1, ct2 bson.Raw) bson.Raw

MaxClusterTime compares 2 clusterTime documents and returns the document representing the highest cluster time.

Types

type Client 

type Client struct {
	*Server
	ClientID       uuid.UUID
	ClusterTime    bson.Raw
	Consistent     bool // causal consistency
	OperationTime  *bson.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
	CurrentWTimeout time.Duration

	TransactionState TransactionState
	PinnedServerAddr *address.Address
	RecoveryToken    bson.Raw
	PinnedConnection LoadBalancedTransactionConnection
	SnapshotTime     *bson.Timestamp
	// contains filtered or unexported fields
}

Client is a session for clients to run commands.

func NewClientSession 

func NewClientSession(pool *Pool, clientID uuid.UUID, opts ...*ClientOptions) (*Client, error)

NewClientSession creates a new explicit client-side session.

func NewImplicitClientSession 

func NewImplicitClientSession(pool *Pool, clientID uuid.UUID) *Client

NewImplicitClientSession creates a new implicit client-side session.

func (*Client) AbortTransaction 

func (c *Client) AbortTransaction() error

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 

func (c *Client) AdvanceClusterTime(clusterTime bson.Raw) error

AdvanceClusterTime updates the session's cluster time.

func (*Client) AdvanceOperationTime 

func (c *Client) AdvanceOperationTime(opTime *bson.Timestamp) error

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 

func (c *Client) CheckAbortTransaction() error

CheckAbortTransaction checks to see if allowed to abort transaction and returns an error if not allowed.

func (*Client) CheckCommitTransaction 

func (c *Client) CheckCommitTransaction() error

CheckCommitTransaction checks to see if allowed to commit transaction and returns an error if not allowed.

func (*Client) CheckStartTransaction 

func (c *Client) CheckStartTransaction() error

CheckStartTransaction checks to see if allowed to start transaction and returns an error if not allowed

func (*Client) ClearPinnedResources 

func (c *Client) ClearPinnedResources() error

ClearPinnedResources clears the pinned server and/or connection associated with the session.

func (*Client) CommitTransaction 

func (c *Client) CommitTransaction() error

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) EndSession 

func (c *Client) EndSession()

EndSession ends the session.

func (*Client) SetServer 

func (c *Client) SetServer() error

SetServer will check out a session from the client session pool.

func (*Client) StartCommand 

func (c *Client) StartCommand() error

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 

func (c *Client) TransactionCommitted() bool

TransactionCommitted returns true of the client session just committed a transaction.

func (*Client) TransactionInProgress 

func (c *Client) TransactionInProgress() bool

TransactionInProgress returns true if the client session is in an active transaction.

func (*Client) TransactionRunning 

func (c *Client) TransactionRunning() bool

TransactionRunning returns true if the client session has started the transaction and it hasn't been committed or aborted

func (*Client) TransactionStarting 

func (c *Client) TransactionStarting() bool

TransactionStarting returns true if the client session is starting a transaction.

func (*Client) UpdateCommitTransactionWriteConcern 

func (c *Client) UpdateCommitTransactionWriteConcern()

UpdateCommitTransactionWriteConcern will set the write concern to majority. This should be called after a commit transaction operation fails with a retryable error or after a successful commit transaction operation

Per the transaction specifications, when commitTransaction is retried, if the modified write concern does not include a "wtimeout" value, drivers MUST apply "wtimeout: 10000" to the write concern in order to avoid waiting forever (oruntil a socket timeout) if the majority write concern cannot be satisfied. This field abstracts that functionality. For more information, see SPEC-1185.

func (*Client) UpdateRecoveryToken 

func (c *Client) UpdateRecoveryToken(response bson.Raw)

UpdateRecoveryToken updates the session's recovery token from the server response.

func (*Client) UpdateSnapshotTime 

func (c *Client) UpdateSnapshotTime(response bsoncore.Document)

UpdateSnapshotTime updates the session's value for the atClusterTime field of ReadConcern.

func (*Client) UpdateUseTime 

func (c *Client) UpdateUseTime() error

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
	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 

type LoadBalancedTransactionConnection interface {
	mnet.ReadWriteCloser
	mnet.Describer
	mnet.Pinner
}

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 

func (p *Pool) CheckedOut() int64

CheckedOut returns number of sessions checked out from pool.

func (*Pool) GetSession 

func (p *Pool) GetSession() (*Server, error)

GetSession retrieves an unexpired session from the pool.

func (*Pool) IDSlice 

func (p *Pool) IDSlice() []bsoncore.Document

IDSlice returns a slice of session IDs for each session in the pool

func (*Pool) ReturnSession 

func (p *Pool) ReturnSession(ss *Server)

ReturnSession returns a session to the pool if it has not expired.

func (*Pool) String 

func (p *Pool) String() string

String implements the Stringer interface

type Server 

type Server struct {
	SessionID bsoncore.Document
	TxnNumber int64
	LastUsed  time.Time
	Dirty     bool
}

Server is an open session with the server.

func (*Server) IncrementTxnNumber 

func (ss *Server) IncrementTxnNumber()

IncrementTxnNumber increments the transaction number.

func (*Server) MarkDirty 

func (ss *Server) MarkDirty()

MarkDirty marks the session as dirty.

type TransactionOptions 

type TransactionOptions struct {
	ReadConcern    *readconcern.ReadConcern
	WriteConcern   *writeconcern.WriteConcern
	ReadPreference *readpref.ReadPref
}

TransactionOptions represents all possible options for starting a transaction in a session.

type TransactionState 

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 

func (s TransactionState) String() string

String implements the fmt.Stringer interface.

Source Files

  • client_session.go
  • cluster_clock.go
  • doc.go
  • options.go
  • server_session.go
  • session_pool.go

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.