github.com/matrixorigin/matrixone@v0.7.0/pkg/txn/client/types.go (about)

     1  // Copyright 2022 Matrix Origin
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //      http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  package client
    16  
    17  import (
    18  	"context"
    19  
    20  	"github.com/matrixorigin/matrixone/pkg/pb/txn"
    21  	"github.com/matrixorigin/matrixone/pkg/txn/rpc"
    22  )
    23  
    24  // TxnOption options for setup transaction
    25  type TxnOption func(*txnOperator)
    26  
    27  // TxnClientCreateOption options for create txn
    28  type TxnClientCreateOption func(*txnClient)
    29  
    30  // TxnClient transaction client, the operational entry point for transactions.
    31  // Each CN node holds one instance of TxnClient.
    32  type TxnClient interface {
    33  	// New returns a TxnOperator to handle read and write operation for a
    34  	// transaction.
    35  	New(options ...TxnOption) (TxnOperator, error)
    36  	// NewWithSnapshot create a txn operator from a snapshot. The snapshot must
    37  	// be from a CN coordinator txn operator.
    38  	NewWithSnapshot(snapshot []byte) (TxnOperator, error)
    39  	// Close closes client.sender
    40  	Close() error
    41  }
    42  
    43  // TxnOperator operator for transaction clients, handling read and write
    44  // requests for transactions, and handling distributed transactions across DN
    45  // nodes.
    46  // Note: For Error returned by Read/Write/WriteAndCommit/Commit/Rollback, need
    47  // to check if it is a moerr.ErrDNShardNotFound error, if so, the DN information
    48  // held is out of date and needs to be reloaded by HAKeeper.
    49  type TxnOperator interface {
    50  	// Txn returns the current txn metadata
    51  	Txn() txn.TxnMeta
    52  	// Snapshot a snapshot of the transaction handle that can be passed around the
    53  	// network. In some scenarios, operations of a transaction are executed on multiple
    54  	// CN nodes for performance acceleration. But with only one CN coordinator, Snapshot
    55  	// can be used to recover the transaction operation handle at a non-CN coordinator
    56  	// node, or it can be used to pass information back to the transaction coordinator
    57  	// after the non-CN coordinator completes the transaction operation.
    58  	Snapshot() ([]byte, error)
    59  	// ApplySnapshot CN coordinator applies a snapshot of the non-coordinator's transaction
    60  	// operation information.
    61  	ApplySnapshot(data []byte) error
    62  	// Read transaction read operation, the operator routes the message based
    63  	// on the given DN node information and waits for the read data synchronously.
    64  	// The transaction has been aborted if ErrTxnAborted returned.
    65  	// After use, SendResult needs to call the Release method
    66  	Read(ctx context.Context, ops []txn.TxnRequest) (*rpc.SendResult, error)
    67  	// Write transaction write operation, and the operator will record the DN
    68  	// nodes written by the current transaction, and when it finds that multiple
    69  	// DN nodes are written, it will start distributed transaction processing.
    70  	// The transaction has been aborted if ErrTxnAborted returned.
    71  	// After use, SendResult needs to call the Release method
    72  	Write(ctx context.Context, ops []txn.TxnRequest) (*rpc.SendResult, error)
    73  	// WriteAndCommit is similar to Write, but commit the transaction after write.
    74  	// After use, SendResult needs to call the Release method
    75  	WriteAndCommit(ctx context.Context, ops []txn.TxnRequest) (*rpc.SendResult, error)
    76  	// Commit the transaction. If data has been written to multiple DN nodes, a
    77  	// 2pc distributed transaction commit process is used.
    78  	Commit(ctx context.Context) error
    79  	// Rollback the transaction.
    80  	Rollback(ctx context.Context) error
    81  }
    82  
    83  // DebugableTxnOperator debugable txn operator
    84  type DebugableTxnOperator interface {
    85  	TxnOperator
    86  
    87  	// Debug send debug request to DN, after use, SendResult needs to call the Release
    88  	// method.
    89  	Debug(ctx context.Context, ops []txn.TxnRequest) (*rpc.SendResult, error)
    90  }
    91  
    92  // TxnIDGenerator txn id generator
    93  type TxnIDGenerator interface {
    94  	// Generate returns a unique transaction id
    95  	Generate() []byte
    96  }