github.com/onflow/flow-go@v0.35.7-crescendo-preview.23-atree-inlining/consensus/hotstuff/event_handler.go (about)

     1  package hotstuff
     2  
     3  import (
     4  	"context"
     5  	"time"
     6  
     7  	"github.com/onflow/flow-go/consensus/hotstuff/model"
     8  	"github.com/onflow/flow-go/model/flow"
     9  )
    10  
    11  // PartialTcCreated represents a notification emitted by the TimeoutProcessor component,
    12  // whenever it has collected TimeoutObjects from a superminority
    13  // of consensus participants for a specific view. Along with the view, it
    14  // reports the newest QC and TC (for previous view) discovered during
    15  // timeout collection. Per convention, the newest QC is never nil, while
    16  // the TC for the previous view might be nil.
    17  type PartialTcCreated struct {
    18  	View       uint64
    19  	NewestQC   *flow.QuorumCertificate
    20  	LastViewTC *flow.TimeoutCertificate
    21  }
    22  
    23  // EventHandler runs a state machine to process proposals, QC and local timeouts.
    24  // Not concurrency safe.
    25  type EventHandler interface {
    26  
    27  	// OnReceiveQc processes a valid qc constructed by internal vote aggregator or discovered in TimeoutObject.
    28  	// All inputs should be validated before feeding into this function. Assuming trusted data.
    29  	// No errors are expected during normal operation.
    30  	OnReceiveQc(qc *flow.QuorumCertificate) error
    31  
    32  	// OnReceiveTc processes a valid tc constructed by internal timeout aggregator, discovered in TimeoutObject or
    33  	// broadcast over the network.
    34  	// All inputs should be validated before feeding into this function. Assuming trusted data.
    35  	// No errors are expected during normal operation.
    36  	OnReceiveTc(tc *flow.TimeoutCertificate) error
    37  
    38  	// OnReceiveProposal processes a block proposal received from another HotStuff
    39  	// consensus participant.
    40  	// All inputs should be validated before feeding into this function. Assuming trusted data.
    41  	// No errors are expected during normal operation.
    42  	OnReceiveProposal(proposal *model.Proposal) error
    43  
    44  	// OnLocalTimeout handles a local timeout event by creating a model.TimeoutObject and broadcasting it.
    45  	// No errors are expected during normal operation.
    46  	OnLocalTimeout() error
    47  
    48  	// OnPartialTcCreated handles notification produces by the internal timeout aggregator. If the notification is for the current view,
    49  	// a corresponding model.TimeoutObject is broadcast to the consensus committee.
    50  	// No errors are expected during normal operation.
    51  	OnPartialTcCreated(partialTC *PartialTcCreated) error
    52  
    53  	// TimeoutChannel returns a channel that sends a signal on timeout.
    54  	TimeoutChannel() <-chan time.Time
    55  
    56  	// Start starts the event handler.
    57  	// No errors are expected during normal operation.
    58  	// CAUTION: EventHandler is not concurrency safe. The Start method must
    59  	// be executed by the same goroutine that also calls the other business logic
    60  	// methods, or concurrency safety has to be implemented externally.
    61  	Start(ctx context.Context) error
    62  }