github.com/KinWaiYuen/client-go/v2@v2.5.4/oracle/oracle.go (about)

     1  // Copyright 2021 TiKV Authors
     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  // NOTE: The code in this file is based on code from the
    16  // TiDB project, licensed under the Apache License v 2.0
    17  //
    18  // https://github.com/pingcap/tidb/tree/cc5e161ac06827589c4966674597c137cc9e809c/store/tikv/oracle/oracle.go
    19  //
    20  
    21  // Copyright 2016 PingCAP, Inc.
    22  //
    23  // Licensed under the Apache License, Version 2.0 (the "License");
    24  // you may not use this file except in compliance with the License.
    25  // You may obtain a copy of the License at
    26  //
    27  //     http://www.apache.org/licenses/LICENSE-2.0
    28  //
    29  // Unless required by applicable law or agreed to in writing, software
    30  // distributed under the License is distributed on an "AS IS" BASIS,
    31  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    32  // See the License for the specific language governing permissions and
    33  // limitations under the License.
    34  
    35  package oracle
    36  
    37  import (
    38  	"context"
    39  	"time"
    40  )
    41  
    42  // Option represents available options for the oracle.Oracle.
    43  type Option struct {
    44  	TxnScope string
    45  }
    46  
    47  // Oracle is the interface that provides strictly ascending timestamps.
    48  type Oracle interface {
    49  	GetTimestamp(ctx context.Context, opt *Option) (uint64, error)
    50  	GetTimestampAsync(ctx context.Context, opt *Option) Future
    51  	GetLowResolutionTimestamp(ctx context.Context, opt *Option) (uint64, error)
    52  	GetLowResolutionTimestampAsync(ctx context.Context, opt *Option) Future
    53  	GetStaleTimestamp(ctx context.Context, txnScope string, prevSecond uint64) (uint64, error)
    54  	IsExpired(lockTimestamp, TTL uint64, opt *Option) bool
    55  	UntilExpired(lockTimeStamp, TTL uint64, opt *Option) int64
    56  	Close()
    57  }
    58  
    59  // Future is a future which promises to return a timestamp.
    60  type Future interface {
    61  	Wait() (uint64, error)
    62  }
    63  
    64  const (
    65  	physicalShiftBits = 18
    66  	logicalBits       = (1 << physicalShiftBits) - 1
    67  	// GlobalTxnScope is the default transaction scope for a Oracle service.
    68  	GlobalTxnScope = "global"
    69  )
    70  
    71  // ComposeTS creates a ts from physical and logical parts.
    72  func ComposeTS(physical, logical int64) uint64 {
    73  	return uint64((physical << physicalShiftBits) + logical)
    74  }
    75  
    76  // ExtractPhysical returns a ts's physical part.
    77  func ExtractPhysical(ts uint64) int64 {
    78  	return int64(ts >> physicalShiftBits)
    79  }
    80  
    81  // ExtractLogical return a ts's logical part.
    82  func ExtractLogical(ts uint64) int64 {
    83  	return int64(ts & logicalBits)
    84  }
    85  
    86  // GetPhysical returns physical from an instant time with millisecond precision.
    87  func GetPhysical(t time.Time) int64 {
    88  	return t.UnixNano() / int64(time.Millisecond)
    89  }
    90  
    91  // GetTimeFromTS extracts time.Time from a timestamp.
    92  func GetTimeFromTS(ts uint64) time.Time {
    93  	ms := ExtractPhysical(ts)
    94  	return time.Unix(ms/1e3, (ms%1e3)*1e6)
    95  }
    96  
    97  // GoTimeToTS converts a Go time to uint64 timestamp.
    98  func GoTimeToTS(t time.Time) uint64 {
    99  	ts := (t.UnixNano() / int64(time.Millisecond)) << physicalShiftBits
   100  	return uint64(ts)
   101  }
   102  
   103  // GoTimeToLowerLimitStartTS returns the min start_ts of the uncommitted transaction.
   104  // maxTxnTimeUse means the max time a Txn May use (in ms) from its begin to commit.
   105  func GoTimeToLowerLimitStartTS(now time.Time, maxTxnTimeUse int64) uint64 {
   106  	return GoTimeToTS(now.Add(-time.Duration(maxTxnTimeUse) * time.Millisecond))
   107  }