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

     1  package approvals
     2  
     3  import (
     4  	"github.com/onflow/flow-go/engine/consensus"
     5  	"github.com/onflow/flow-go/model/flow"
     6  )
     7  
     8  // ProcessingStatus is a state descriptor for the AssignmentCollector.
     9  type ProcessingStatus int
    10  
    11  const (
    12  	// CachingApprovals is a state descriptor for the AssignmentCollector. In this state,
    13  	// the collector is currently caching approvals but _not_ yet processing them.
    14  	CachingApprovals ProcessingStatus = iota
    15  	// VerifyingApprovals is a state descriptor for the AssignmentCollector. In this state,
    16  	// the collector is processing approvals.
    17  	VerifyingApprovals
    18  	// Orphaned is a state descriptor for the AssignmentCollector. In this state,
    19  	// the collector discards all approvals.
    20  	Orphaned
    21  )
    22  
    23  func (ps ProcessingStatus) String() string {
    24  	names := [...]string{"CachingApprovals", "VerifyingApprovals", "Orphaned"}
    25  	if ps < CachingApprovals || ps > Orphaned {
    26  		return "UNKNOWN"
    27  	}
    28  	return names[ps]
    29  }
    30  
    31  // AssignmentCollector tracks the known verifier assignments for a particular execution result.
    32  // For the same result, there can be multiple different assignments. This happens if the result is
    33  // incorporated in different forks, because in each fork a unique verifier assignment is generated
    34  // using the incorporating block's unique 'source of randomness'.
    35  // An AssignmentCollector can be in different states (enumerated by ProcessingStatus). State
    36  // transitions are atomic and concurrency safe. The high-level AssignmentCollector implements the
    37  // logic for state transitions, while it delegates the state-specific portion of the logic to
    38  // `AssignmentCollectorState`.
    39  type AssignmentCollector interface {
    40  	AssignmentCollectorState
    41  
    42  	// ChangeProcessingStatus changes the AssignmentCollector's internal processing
    43  	// status. The operation is implemented as an atomic compare-and-swap, i.e. the
    44  	// state transition is only executed if AssignmentCollector's internal state is
    45  	// equal to `expectedValue`. The return indicates whether the state was updated.
    46  	// The implementation only allows the transitions
    47  	//         CachingApprovals -> VerifyingApprovals
    48  	//    and                      VerifyingApprovals -> Orphaned
    49  	// Error returns:
    50  	// * nil if the state transition was successfully executed
    51  	// * ErrDifferentCollectorState if the AssignmentCollector's state is different than expectedCurrentStatus
    52  	// * ErrInvalidCollectorStateTransition if the given state transition is impossible
    53  	// * all other errors are unexpected and potential symptoms of internal bugs or state corruption (fatal)
    54  	ChangeProcessingStatus(expectedValue, newValue ProcessingStatus) error
    55  }
    56  
    57  // AssignmentCollectorState represents an AssignmentCollector in one specific state (without any
    58  // knowledge about state transitions).
    59  type AssignmentCollectorState interface {
    60  	// BlockID returns the ID of the executed block.
    61  	BlockID() flow.Identifier
    62  	// Block returns the header of the executed block.
    63  	Block() *flow.Header
    64  	// ResultID returns the ID of the result this assignment collector tracks.
    65  	ResultID() flow.Identifier
    66  	// Result returns the result this assignment collector tracks.
    67  	Result() *flow.ExecutionResult
    68  
    69  	// ProcessIncorporatedResult starts tracking the approval for IncorporatedResult.
    70  	// Method is idempotent.
    71  	// Error Returns:
    72  	//  * no errors expected during normal operation;
    73  	//    errors might be symptoms of bugs or internal state corruption (fatal)
    74  	ProcessIncorporatedResult(incorporatedResult *flow.IncorporatedResult) error
    75  
    76  	// ProcessApproval ingests Result Approvals and triggers sealing of execution result
    77  	// when sufficient approvals have arrived. Method is idempotent.
    78  	// Error Returns:
    79  	//  * nil in case of success (outdated approvals might be silently discarded)
    80  	//  * engine.InvalidInputError if the result approval is invalid
    81  	//  * any other errors might be symptoms of bugs or internal state corruption (fatal)
    82  	ProcessApproval(approval *flow.ResultApproval) error
    83  
    84  	// CheckEmergencySealing checks whether this AssignmentCollector can be emergency
    85  	// sealed. If this is the case, the AssignmentCollector produces a candidate seal
    86  	// as part of this method call. No errors are expected during normal operations.
    87  	CheckEmergencySealing(observer consensus.SealingObservation, finalizedBlockHeight uint64) error
    88  
    89  	// RequestMissingApprovals sends requests for missing approvals to the respective
    90  	// verification nodes. Returns number of requests made. No errors are expected
    91  	// during normal operations.
    92  	RequestMissingApprovals(observer consensus.SealingObservation, maxHeightForRequesting uint64) (uint, error)
    93  
    94  	// ProcessingStatus returns the AssignmentCollector's ProcessingStatus (state descriptor).
    95  	ProcessingStatus() ProcessingStatus
    96  }