github.com/onflow/flow-go@v0.33.17/consensus/hotstuff/cruisectl/config.go (about)

     1  package cruisectl
     2  
     3  import (
     4  	"time"
     5  
     6  	"go.uber.org/atomic"
     7  )
     8  
     9  // DefaultConfig returns the default config for the BlockTimeController.
    10  func DefaultConfig() *Config {
    11  	return &Config{
    12  		TimingConfig{
    13  			TargetTransition:      DefaultEpochTransitionTime(),
    14  			FallbackProposalDelay: atomic.NewDuration(250 * time.Millisecond),
    15  			MinViewDuration:       atomic.NewDuration(600 * time.Millisecond),
    16  			MaxViewDuration:       atomic.NewDuration(1600 * time.Millisecond),
    17  			Enabled:               atomic.NewBool(false),
    18  		},
    19  		ControllerParams{
    20  			N_ewma: 5,
    21  			N_itg:  50,
    22  			KP:     2.0,
    23  			KI:     0.6,
    24  			KD:     3.0,
    25  		},
    26  	}
    27  }
    28  
    29  // Config defines configuration for the BlockTimeController.
    30  type Config struct {
    31  	TimingConfig
    32  	ControllerParams
    33  }
    34  
    35  // TimingConfig specifies the BlockTimeController's limits of authority.
    36  type TimingConfig struct {
    37  	// TargetTransition defines the target time to transition epochs each week.
    38  	TargetTransition EpochTransitionTime
    39  
    40  	// FallbackProposalDelay is the minimal block construction delay. When used, it behaves like the
    41  	// old command line flag `block-rate-delay`. Specifically, the primary measures the duration from
    42  	// starting to construct its proposal to the proposal being ready to be published. If this
    43  	// duration is _less_ than FallbackProposalDelay, the primary delays broadcasting its proposal
    44  	// by the remainder needed to reach `FallbackProposalDelay`
    45  	// It is used:
    46  	//  - when Enabled is false
    47  	//  - when epoch fallback has been triggered
    48  	FallbackProposalDelay *atomic.Duration
    49  
    50  	// MaxViewDuration is a hard maximum on the total view time targeted by ProposalTiming.
    51  	// If the BlockTimeController computes a larger desired ProposalTiming value
    52  	// based on the observed error and tuning, this value will be used instead.
    53  	MaxViewDuration *atomic.Duration
    54  
    55  	// MinViewDuration  is a hard maximum on the total view time targeted by ProposalTiming.
    56  	// If the BlockTimeController computes a smaller desired ProposalTiming value
    57  	// based on the observed error and tuning, this value will be used instead.
    58  	MinViewDuration *atomic.Duration
    59  
    60  	// Enabled defines whether responsive control of the GetProposalTiming is enabled.
    61  	// When disabled, the FallbackProposalDelay is used.
    62  	Enabled *atomic.Bool
    63  }
    64  
    65  // ControllerParams specifies the BlockTimeController's internal parameters.
    66  type ControllerParams struct {
    67  	// N_ewma defines how historical measurements are incorporated into the EWMA for the proportional error term.
    68  	// Intuition: Suppose the input changes from x to y instantaneously:
    69  	//  - N_ewma is the number of samples required to move the EWMA output about 2/3 of the way from x to y
    70  	// Per convention, this must be a _positive_ integer.
    71  	N_ewma uint
    72  
    73  	// N_itg defines how historical measurements are incorporated into the integral error term.
    74  	// Intuition: For a constant error x:
    75  	//  - the integrator value will saturate at `x•N_itg`
    76  	//  - an integrator initialized at 0 reaches 2/3 of the saturation value after N_itg samples
    77  	// Per convention, this must be a _positive_ integer.
    78  	N_itg uint
    79  
    80  	// KP, KI, KD, are the coefficients to the PID controller and define its response.
    81  	// KP adjusts the proportional term (responds to the magnitude of error).
    82  	// KI adjusts the integral term (responds to the error sum over a recent time interval).
    83  	// KD adjusts the derivative term (responds to the rate of change, i.e. time derivative, of the error).
    84  	KP, KI, KD float64
    85  }
    86  
    87  // alpha returns α, the inclusion parameter for the error EWMA. See N_ewma for details.
    88  func (c *ControllerParams) alpha() float64 {
    89  	return 1.0 / float64(c.N_ewma)
    90  }
    91  
    92  // beta returns ß, the memory parameter of the leaky error integrator. See N_itg for details.
    93  func (c *ControllerParams) beta() float64 {
    94  	return 1.0 / float64(c.N_itg)
    95  }
    96  
    97  func (ctl *TimingConfig) GetFallbackProposalDuration() time.Duration {
    98  	return ctl.FallbackProposalDelay.Load()
    99  }
   100  func (ctl *TimingConfig) GetMaxViewDuration() time.Duration {
   101  	return ctl.MaxViewDuration.Load()
   102  }
   103  func (ctl *TimingConfig) GetMinViewDuration() time.Duration {
   104  	return ctl.MinViewDuration.Load()
   105  }
   106  func (ctl *TimingConfig) GetEnabled() bool {
   107  	return ctl.Enabled.Load()
   108  }
   109  
   110  func (ctl *TimingConfig) SetFallbackProposalDuration(dur time.Duration) error {
   111  	ctl.FallbackProposalDelay.Store(dur)
   112  	return nil
   113  }
   114  func (ctl *TimingConfig) SetMaxViewDuration(dur time.Duration) error {
   115  	ctl.MaxViewDuration.Store(dur)
   116  	return nil
   117  }
   118  func (ctl *TimingConfig) SetMinViewDuration(dur time.Duration) error {
   119  	ctl.MinViewDuration.Store(dur)
   120  	return nil
   121  
   122  }
   123  func (ctl *TimingConfig) SetEnabled(enabled bool) error {
   124  	ctl.Enabled.Store(enabled)
   125  	return nil
   126  }