github.com/matrixorigin/matrixone@v1.2.0/proto/lock.proto

/* 
 * Copyright 2021 Matrix Origin
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

syntax = "proto3";
package lock; 
option go_package = "github.com/matrixorigin/matrixone/pkg/pb/lock";

import "github.com/gogo/protobuf/gogoproto/gogo.proto";
import "timestamp.proto";

option (gogoproto.goproto_enum_prefix_all) = true;

// Granularity row granularity, single row or row range
enum Granularity {
  Row   = 0;
  Range = 1;
}

// LockMode lock mode
enum LockMode {
  Exclusive = 0;
  Shared    = 1;
}

// WaitPolicy wait policy
enum WaitPolicy {
  Wait     = 0;
  FastFail = 1;
}

enum Sharding {
  None   = 0;
  ByRow  = 1;
}

// LockOptions lock options
message LockOptions {
  Granularity         Granularity       = 1;
  LockMode            Mode              = 2;
  WaitPolicy          Policy            = 3;
  string              ForwardTo         = 4;
  bool                TableDefChanged   = 5;
  int64               RetryWait         = 6;
  uint32              Group             = 7;
  Sharding            Sharding          = 8;
  timestamp.Timestamp SnapShotTs        = 9 [(gogoproto.nullable) = false];
}

// LockTable describes which CN manages a Table's Locks.
message LockTable {
  // Table table id
  uint64   Table       = 1;
  // ServiceID lock service id, a cn node will only run one instance of LockService
  string   ServiceID   = 2;
  // Version will incr if CN-Table bind changed.
  uint64   Version     = 3;
  // Valid false if the service is disabled, and no new service bind this table
  bool     Valid       = 4;
  uint32   Group       = 5;
  Sharding Sharding    = 6;
  uint64   OriginTable = 7;
}

// Method lock table operations
enum Method {
  // Lock lock rows on remote lock table
  Lock               = 0;
  // Write unlock rows from remote lock table
  Unlock             = 1;
  // GetTxnLock get lock data on a special lock
  GetTxnLock         = 2;
  // GetWaitingList get waiting txns on a special lock
  GetWaitingList     = 3;
  // KeepRemoteLock keep remote lock on remote lock service 
  KeepRemoteLock     = 4;
  // GetBind get or create lock table bind from lock table allocator
  GetBind            = 5;
  // KeepLockTableBind keep the lock table bind on lock table allocator
  KeepLockTableBind  = 6;
  // ForwardLock forward lock request to another service
  ForwardLock        = 7;
  // ForwardUnlock forward unlock request to another service
  ForwardUnlock      = 8;
  // ValidateService validate if lock service alive
  ValidateService    = 9;
  // CannotCommit for orphaned transactions that are found, the lock is released
  // immediately, and you need to mark these transactions as not being able to be
  // committed in the TN
  CannotCommit       = 10;
  // GetActiveTxn used to get the active txn on the lock service
  GetActiveTxn       = 11;
  // SetRestartService set restart lock service
  SetRestartService  = 12;
  // RemainTxnInService get remain txn in lock service
  RemainTxnInService = 13;
  // canRestartService judge if can restart lock service
  CanRestartService  = 14;
}

enum Status {
  ServiceLockEnable        = 0;
  ServiceLockWaiting       = 1;
  ServiceUnLockSucc        = 2;
  ServiceCanRestart        = 3;
}

// Request is used to send a request for a LockTable related operation to another 
// service.
message Request {
  // RequestID request id
  uint64                     RequestID           = 1;
  // LockTable lock target table
  LockTable                  LockTable           = 2  [(gogoproto.nullable) = false];
  Method                     Method              = 3;
  LockRequest                Lock                = 4  [(gogoproto.nullable) = false];
  UnlockRequest              Unlock              = 5  [(gogoproto.nullable) = false];
  GetTxnLockRequest          GetTxnLock          = 6  [(gogoproto.nullable) = false];
  GetWaitingListRequest      GetWaitingList      = 7  [(gogoproto.nullable) = false];
  GetBindRequest             GetBind             = 8  [(gogoproto.nullable) = false];
  KeepLockTableBindRequest   KeepLockTableBind   = 9  [(gogoproto.nullable) = false];
  KeepRemoteLockRequest      KeepRemoteLock      = 10 [(gogoproto.nullable) = false];
  ValidateServiceRequest     ValidateService     = 11 [(gogoproto.nullable) = false];
  CannotCommitRequest        CannotCommit        = 12 [(gogoproto.nullable) = false];
  GetActiveTxnRequest        GetActiveTxn        = 13 [(gogoproto.nullable) = false];
  SetRestartServiceRequest   SetRestartService   = 14 [(gogoproto.nullable) = false];
  CanRestartServiceRequest   CanRestartService   = 15 [(gogoproto.nullable) = false];
  RemainTxnInServiceRequest  RemainTxnInService  = 16 [(gogoproto.nullable) = false];
}

// Response response
message Response {
    // RequestID corresponding request id
    uint64                     RequestID            = 1;
    Method                     Method               = 2;
    // Error we use this field to send moerr from service to another cn. Set with 
    // moerr.MarshalBinary, and use moerr.UnmarshalBinary to restore moerr.
    bytes                      Error                = 3;
    LockTable                  NewBind              = 4;
    LockResponse               Lock                 = 5  [(gogoproto.nullable) = false];
    UnlockResponse             Unlock               = 6  [(gogoproto.nullable) = false];
    GetTxnLockResponse         GetTxnLock           = 7  [(gogoproto.nullable) = false];
    GetWaitingListResponse     GetWaitingList       = 8  [(gogoproto.nullable) = false];
    GetBindResponse            GetBind              = 9  [(gogoproto.nullable) = false];
    KeepLockTableBindResponse  KeepLockTableBind    = 10 [(gogoproto.nullable) = false];
    KeepRemoteLockResponse     KeepRemoteLock       = 11 [(gogoproto.nullable) = false];
    ValidateServiceResponse    ValidateService      = 12 [(gogoproto.nullable) = false];
    CannotCommitResponse       CannotCommit         = 13 [(gogoproto.nullable) = false];
    GetActiveTxnResponse       GetActiveTxn         = 14 [(gogoproto.nullable) = false];
    SetRestartServiceResponse  SetRestartService    = 15 [(gogoproto.nullable) = false];
    CanRestartServiceResponse  CanRestartService    = 16 [(gogoproto.nullable) = false];
    RemainTxnInServiceResponse RemainTxnInService   = 17 [(gogoproto.nullable) = false];
}

// LockRequest lock request
message LockRequest {
  bytes               TxnID       = 1;
  string              ServiceID   = 2;
  repeated  bytes     Rows        = 3;
  // LockOptions lock options
  LockOptions         Options     = 4 [(gogoproto.nullable) = false];
}

// LockResponse lock response
message LockResponse {
  Result Result = 1 [(gogoproto.nullable) = false];
}

// GetTxnLockRequest get a waiting txn list on a special lock 
// request, used to dead lock detect
message GetTxnLockRequest {
  bytes     TxnID     = 1;
  bytes     Row       = 2;
}

// GetTxnLockResponse get txn Lock response
message GetTxnLockResponse {
  int32            Value       = 1;
  repeated WaitTxn WaitingList = 2 [(gogoproto.nullable) = false];
}

// GetWaitingListRequest get a waiting txn list on a specical txn request. CN -> CN
message GetWaitingListRequest {
  WaitTxn Txn = 1 [(gogoproto.nullable) = false];
}

// GetWaitingListResponse get a waiting txn list on a specical txn response. CN -> CN
message GetWaitingListResponse {
  repeated WaitTxn WaitingList = 1 [(gogoproto.nullable) = false];
}

// WaitTxn wait txn include txn created on
message WaitTxn {
  bytes     TxnID     = 1;
  string    CreatedOn = 2;
}

// UnlockRequest unlock lock on remote lock service request. CN -> CN
message UnlockRequest {
  bytes                  TxnID     = 1;
  // CommitTS is the commit timestamp of the current txn. Empty if txn is
  // roll backed
  timestamp.Timestamp    CommitTS  = 2 [(gogoproto.nullable) = false];
  repeated ExtraMutation Mutations = 3 [(gogoproto.nullable) = false];
}

// UnlockResponse unlock lock on remote lock service response. CN -> CN
message UnlockResponse {

}

// GetBindRequest get bind request from allocator request. CN -> TN
message GetBindRequest {
  string   ServiceID   = 1;
  uint64   Table       = 2;
  uint32   Group       = 3;
  Sharding Sharding    = 4;
  uint64   OriginTable = 5;
}

// GetBindResponse get bind request from allocator response. TN -> CN
message GetBindResponse {
  LockTable LockTable = 2 [(gogoproto.nullable) = false];
}

// KeepLockTableBindRequest keep lock table bind request. CN -> TN
message KeepLockTableBindRequest {
  string ServiceID = 1;
  Status Status = 2;
  repeated bytes TxnIDs = 3;
  repeated LockTable LockTables = 4 [(gogoproto.nullable) = false];
}

// KeepLockTableBindResponse keep lock table bind response. TN -> CN
message KeepLockTableBindResponse {
  bool OK = 1;
  Status Status = 2;
}

// SetRestartServiceRequest set restart lock service request from allocator request. operator -> TN
message SetRestartServiceRequest {
  string ServiceID = 1;
}

// SetRestartServiceResponse set restart lock service request from allocator response. TN -> operator
message SetRestartServiceResponse {
  bool OK = 1;
}

// CanRestartServiceRequest can restart lock service request from allocator request. operator -> TN
message CanRestartServiceRequest {
  string ServiceID = 1;
}

// CanRestartServiceResponse can restart lock service request from allocator response. TN -> operator
message CanRestartServiceResponse {
  bool OK = 1;
}

// RemainTxnInServiceRequest get remain txn in service request from allocator request. operator -> TN
message RemainTxnInServiceRequest {
  string ServiceID = 1;
}

// RemainTxnInServiceResponse get remain txn in service request from allocator response. TN -> operator
message RemainTxnInServiceResponse {
  int32 RemainTxn = 1;
}

// KeepRemoteLockRequest keep lock on remote lockservice request. CN -> CN
message KeepRemoteLockRequest {
  string ServiceID       = 1;
}

// KeepRemoteLockResponse keep lock on remote lockservice response. TN -> CN
message KeepRemoteLockResponse {
  bool OK = 1;
}

// ValidateServiceRequest validate if lock service alive request. TN -> CN
message ValidateServiceRequest {
  string ServiceID       = 1;
}

// KeepLockTableBindResponse keep lock table bind response. CN -> DN
message ValidateServiceResponse {
  bool OK = 1;
}


// CannotCommitRequest cannot commit request. CN -> TN
message CannotCommitRequest {
  repeated OrphanTxn OrphanTxnList = 1 [(gogoproto.nullable) = false];
}

// CannotCommitResponse cannot commit response. TN -> CN
message CannotCommitResponse {
  repeated bytes CommittingTxn = 1;
}

message GetActiveTxnRequest {
  string ServiceID = 1;
}

message GetActiveTxnResponse {
  bool         Valid = 1;
  repeated bytes Txn = 2;
}

message OrphanTxn {
  string     Service = 1;
  repeated bytes Txn = 2;
}

// Result result is used to tell the caller the result of the lock operation.
message Result {
  // LockedOn lock is locked on which locktable
  LockTable           LockedOn        = 1 [(gogoproto.nullable) = false];
  // HasConflict if true means encounter lock conflict
  bool                HasConflict     = 2;
  // HasPrevCommit if HasPrevCommit && HasConflict, Timestamp is the latest commit
  // timestamp.
  bool                HasPrevCommit   = 3;
  // Timestamp is used to help determine which version of RC should be queried 
  // under the RC isolation level, this timestamp ensures that the latest data 
  // is always read.
  timestamp.Timestamp Timestamp       = 4 [(gogoproto.nullable) = false];
  // TableDefChanged conflict with ddl lock, need rebuild plan to get new table def
  bool                TableDefChanged = 5;
  bytes               ConflictKey     = 6;
  bytes               ConflictTxn     = 7;   
  bytes               PrevWaiter      = 8; 
  uint32              Waiters         = 9;                 
}

message ExtraMutation {
  bytes key       = 1;
  bool  skip      = 2;
  bytes replaceTo = 3;
}