github.com/voedger/voedger@v0.0.0-20240520144910-273e84102129/pkg/iratesce/types.go (about)

     1  /*
     2   * Copyright (c) 2020-present unTill Pro, Ltd.
     3   */
     4  
     5  package iratesce
     6  
     7  import (
     8  	"sync"
     9  	"time"
    10  
    11  	irates "github.com/voedger/voedger/pkg/irates"
    12  	coreutils "github.com/voedger/voedger/pkg/utils"
    13  )
    14  
    15  // bucket, соответствующий некому ключу irates.BucketKey
    16  // содержит в себе Limiter и параметры ограничения, с которыми он работает
    17  // bucket corresponding to a certain key irates.BucketKey
    18  // contains a Limiter and the restriction parameters with which it works
    19  type bucketType struct {
    20  	limiter Limiter
    21  	state   irates.BucketState
    22  }
    23  
    24  // реализация для irates.IBuckets
    25  // распределяет отображение bucket'ов (token bucket)и отображение поименованных параметров ограничений "по умолчанию"
    26  type bucketsType struct {
    27  	mu            sync.Mutex
    28  	buckets       map[irates.BucketKey]*bucketType
    29  	defaultStates map[string]irates.BucketState
    30  	timeFunc      coreutils.TimeFunc
    31  }
    32  
    33  // A Limiter controls how frequently events are allowed to happen.
    34  // It implements a "token bucket" of size b, initially full and refilled
    35  // at rate r tokens per second.
    36  // Informally, in any large enough time interval, the Limiter limits the
    37  // rate to r tokens per second, with a maximum burst size of b events.
    38  // As a special case, if r == Inf (the infinite rate), b is ignored.
    39  // See https://en.wikipedia.org/wiki/Token_bucket for more about token buckets.
    40  //
    41  // The zero value is a valid Limiter, but it will reject all events.
    42  // Use NewLimiter to create non-zero Limiters.
    43  //
    44  // Limiter has three main methods, Allow, Reserve, and Wait.
    45  // Most callers should use Wait.
    46  //
    47  // Each of the three methods consumes a single token.
    48  // They differ in their behavior when no token is available.
    49  // If no token is available, Allow returns false.
    50  // If no token is available, Reserve returns a reservation for a future token
    51  // and the amount of time the caller must wait before using it.
    52  // If no token is available, Wait blocks until one can be obtained
    53  // or its associated context.Context is canceled.
    54  //
    55  // The methods AllowN, ReserveN, and WaitN consume n tokens.
    56  type Limiter struct {
    57  	mu     sync.Mutex
    58  	limit  Limit
    59  	burst  int
    60  	tokens float64
    61  	// last is the last time the limiter's tokens field was updated
    62  	last time.Time
    63  	// lastEvent is the latest time of a rate-limited event (past or future)
    64  	lastEvent time.Time
    65  	// timeFunc  coreutils.TimeFunc
    66  }
    67  
    68  // A Reservation holds information about events that are permitted by a Limiter to happen after a delay.
    69  // A Reservation may be canceled, which may enable the Limiter to permit additional events.
    70  // Reservation содержит информацию о событиях, которые разрешены Limiter после задержки.
    71  // Reservation может быть отменено, что может позволить Limiter разрешить дополнительные мероприятия
    72  type Reservation struct {
    73  	ok        bool
    74  	lim       *Limiter
    75  	tokens    int
    76  	timeToAct time.Time
    77  	// This is the Limit at reservation time, it can change later.
    78  	limit Limit
    79  }
    80  
    81  // Limit defines the maximum frequency of some events.
    82  // Limit is represented as number of events per second.
    83  // A zero Limit allows no events.
    84  type Limit float64