sessiontxn

type ConstantFuture uint64

type EnterNewTxnRequest struct {
	// Type is the type for new entering a new txn
	Type EnterNewTxnType
	// provider is the context provider
	Provider TxnContextProvider
	// txnMode is the transaction mode for the new txn. It has 3 values: `ast.Pessimistic` ,`ast.Optimistic` or empty/
	// When the value is empty, it means the value will be determined from sys vars.
	TxnMode string
	// causalConsistencyOnly means whether enable causal consistency for transactions, default is false
	CausalConsistencyOnly bool
	// staleReadTS indicates the read ts for the stale read transaction.
	// The default value is zero which means not a stale read transaction.
	StaleReadTS uint64
}

type EnterNewTxnType int

type StmtErrorAction int

type StmtErrorHandlePoint int

type TxnAdvisable interface {
	// AdviseWarmup provides warmup for inner state
	AdviseWarmup() error
	// AdviseOptimizeWithPlan providers optimization according to the plan
	AdviseOptimizeWithPlan(plan any) error
}

type TxnContextProvider interface {
	TxnAdvisable
	// GetTxnInfoSchema returns the information schema used by txn
	GetTxnInfoSchema() infoschema.InfoSchema
	// GetTxnScope returns the current txn scope
	GetTxnScope() string
	// GetReadReplicaScope returns the read replica scope
	GetReadReplicaScope() string
	// GetStmtReadTS returns the read timestamp used by select statement (not for select ... for update)
	GetStmtReadTS() (uint64, error)
	// GetStmtForUpdateTS returns the read timestamp used by update/insert/delete or select ... for update
	GetStmtForUpdateTS() (uint64, error)
	// GetSnapshotWithStmtReadTS gets snapshot with read ts
	GetSnapshotWithStmtReadTS() (kv.Snapshot, error)
	// GetSnapshotWithStmtForUpdateTS gets snapshot with for update ts
	GetSnapshotWithStmtForUpdateTS() (kv.Snapshot, error)

	// OnInitialize is the hook that should be called when enter a new txn with this provider
	OnInitialize(ctx context.Context, enterNewTxnType EnterNewTxnType) error
	// OnStmtStart is the hook that should be called when a new statement started
	OnStmtStart(ctx context.Context, node ast.StmtNode) error
	// OnPessimisticStmtStart is the hook that should be called when starts handling a pessimistic DML or
	// a pessimistic select-for-update statement.
	OnPessimisticStmtStart(ctx context.Context) error
	// OnPessimisticStmtEnd is the hook that should be called when finishes handling a pessimistic DML or
	// select-for-update statement.
	OnPessimisticStmtEnd(ctx context.Context, isSuccessful bool) error
	// OnStmtErrorForNextAction is the hook that should be called when a new statement get an error
	OnStmtErrorForNextAction(ctx context.Context, point StmtErrorHandlePoint, err error) (StmtErrorAction, error)
	// OnStmtRetry is the hook that should be called when a statement is retried internally.
	OnStmtRetry(ctx context.Context) error
	// OnStmtCommit is the hook that should be called when a statement is executed successfully.
	OnStmtCommit(ctx context.Context) error
	// OnStmtRollback is the hook that should be called when a statement fails to execute.
	OnStmtRollback(ctx context.Context, isForPessimisticRetry bool) error
	// OnLocalTemporaryTableCreated is the hook that should be called when a local temporary table created.
	OnLocalTemporaryTableCreated()
	// ActivateTxn activates the transaction.
	ActivateTxn() (kv.Transaction, error)
	// SetOptionsBeforeCommit is called after execution and before commit, which sets necessary options for the transaction.
	SetOptionsBeforeCommit(txn kv.Transaction, commitTSChecker func(uint64) bool) error
}

type TxnManager interface {
	TxnAdvisable
	// GetTxnInfoSchema returns the information schema used by txn
	// If the session is not in any transaction, for example: between two autocommit statements,
	// this method will return the latest information schema in session that is same with `sessionctx.GetLatestInfoSchema()`
	GetTxnInfoSchema() infoschema.InfoSchema
	// GetTxnScope returns the current txn scope
	GetTxnScope() string
	// GetReadReplicaScope returns the read replica scope
	GetReadReplicaScope() string
	// GetStmtReadTS returns the read timestamp used by select statement (not for select ... for update)
	// Calling this method will activate the txn implicitly if current read is not stale/historical read
	GetStmtReadTS() (uint64, error)
	// GetStmtForUpdateTS returns the read timestamp used by update/insert/delete or select ... for update
	// Calling this method will activate the txn implicitly if current read is not stale/historical read
	GetStmtForUpdateTS() (uint64, error)
	// GetContextProvider returns the current TxnContextProvider
	GetContextProvider() TxnContextProvider
	// GetSnapshotWithStmtReadTS gets snapshot with read ts
	GetSnapshotWithStmtReadTS() (kv.Snapshot, error)
	// GetSnapshotWithStmtForUpdateTS gets snapshot with for update ts
	GetSnapshotWithStmtForUpdateTS() (kv.Snapshot, error)

	// EnterNewTxn enters a new transaction.
	EnterNewTxn(ctx context.Context, req *EnterNewTxnRequest) error
	// OnTxnEnd is the hook that should be called after transaction commit or rollback
	OnTxnEnd()
	// OnStmtStart is the hook that should be called when a new statement started
	OnStmtStart(ctx context.Context, node ast.StmtNode) error
	// OnPessimisticStmtStart is the hook that should be called when starts handling a pessimistic DML or
	// a pessimistic select-for-update statement.
	OnPessimisticStmtStart(ctx context.Context) error
	// OnPessimisticStmtEnd is the hook that should be called when finishes handling a pessimistic DML or
	// select-for-update statement.
	OnPessimisticStmtEnd(ctx context.Context, isSuccessful bool) error
	// OnStmtErrorForNextAction is the hook that should be called when a new statement get an error
	// This method is not required to be called for every error in the statement,
	// it is only required to be called for some errors handled in some specified points given by the parameter `point`.
	// When the return error is not nil the return action is 'StmtActionError' and vice versa.
	OnStmtErrorForNextAction(ctx context.Context, point StmtErrorHandlePoint, err error) (StmtErrorAction, error)
	// OnStmtRetry is the hook that should be called when a statement retry
	OnStmtRetry(ctx context.Context) error
	// OnStmtCommit is the hook that should be called when a statement is executed successfully.
	OnStmtCommit(ctx context.Context) error
	// OnStmtRollback is the hook that should be called when a statement fails to execute.
	OnStmtRollback(ctx context.Context, isForPessimisticRetry bool) error
	// OnStmtEnd is called when a statement ends, together with txn.onStmtEnd()
	OnStmtEnd()
	// OnLocalTemporaryTableCreated is the hook that should be called when a local temporary table created.
	OnLocalTemporaryTableCreated()
	// ActivateTxn activates the transaction.
	ActivateTxn() (kv.Transaction, error)
	// GetCurrentStmt returns the current statement node
	GetCurrentStmt() ast.StmtNode
	// SetOptionsBeforeCommit is called after execution and before commit, which sets necessary options for the transaction.
	SetOptionsBeforeCommit(txn kv.Transaction, commitTSChecker func(uint64) bool) error
}