priority

Documentation

Overview

Package priority implements the priority protocol that resolves arbitrary cluster wide priorities.

Protocol overview:

• Priorities are arbitrary protobufs (data).
• Priorities are grouped by a topic (also arbitrary protobuf data).
• Peers in the cluster participate in a priority protocol instances.
• The protocol consists of two steps: priority exchange followed by priority consensus.
• All peers propose their own set of priorities for an instance.
• These are exchanged with all other peers.
• All peers also respond with their priorities.
• The exchange step is complete when the priorities of all peers have been received or on timeout.
• Each peer calculates what they consider as the cluster wide priorities based on the priorities available to them at the point.
• Each peer then starts a consensus instance proposing this deterministic calculated result.
• Consensus is reached if quorum peers propose the same value.

Index

• func Protocols() []protocol.ID
• type Component
  • func NewComponent(ctx context.Context, tcpNode host.Host, peers []peer.ID, minRequired int, ...) (*Component, error)
  • func (c *Component) Prioritise(ctx context.Context, duty core.Duty, proposals ...TopicProposal) error
  • func (c *Component) Start(ctx context.Context)
  • func (c *Component) Subscribe(fn func(context.Context, core.Duty, []TopicResult) error)
• type Consensus
• type Prioritiser
  • func NewForT(_ *testing.T, tcpNode host.Host, peers []peer.ID, minRequired int, ...) *Prioritiser
  • func (p *Prioritiser) Prioritise(ctx context.Context, msg *pbv1.PriorityMsg) error
  • func (p *Prioritiser) Start(ctx context.Context)
  • func (p *Prioritiser) Subscribe(fn subscriber)
• type Priority
• type ScoredPriority
• type Topic
• type TopicProposal
• type TopicResult
  • func (r TopicResult) PrioritiesOnly() []string

Functions

func Protocols

func Protocols() []protocol.ID

Protocols returns the supported protocols of this package in order of precedence.

Types

type Component

type Component struct {
	// contains filtered or unexported fields
}

Component wraps a prioritise protocol instance providing a friendly API (hiding the underlying protobuf types) and does signing.

func NewComponent

func NewComponent(ctx context.Context, tcpNode host.Host, peers []peer.ID, minRequired int, sendFunc p2p.SendReceiveFunc,
	registerHandlerFunc p2p.RegisterHandlerFunc, consensus coreConsensus,
	exchangeTimeout time.Duration, privkey *ecdsa.PrivateKey, deadlineFunc func(duty core.Duty) (time.Time, bool),
) (*Component, error)

NewComponent returns a new priority component.

func (*Component) Prioritise

func (c *Component) Prioritise(ctx context.Context, duty core.Duty, proposals ...TopicProposal) error

Prioritise starts a new prioritisation instance for the provided duty and proposals or returns an error.

func (*Component) Start

func (c *Component) Start(ctx context.Context)

Start starts a goroutine that cleans state.

func (*Component) Subscribe

func (c *Component) Subscribe(fn func(context.Context, core.Duty, []TopicResult) error)

Subscribe registers a prioritiser output subscriber function.

type Consensus

type Consensus interface {
	ProposePriority(context.Context, core.Duty, *pbv1.PriorityResult) error
	SubscribePriority(func(context.Context, core.Duty, *pbv1.PriorityResult) error)
}

type Prioritiser

type Prioritiser struct {
	// contains filtered or unexported fields
}

Prioritiser resolves cluster wide priorities.

func NewForT

func NewForT(_ *testing.T, tcpNode host.Host, peers []peer.ID, minRequired int,
	sendFunc p2p.SendReceiveFunc, registerHandlerFunc p2p.RegisterHandlerFunc,
	consensus Consensus, msgValidator msgValidator, exchangeTimeout time.Duration,
	deadliner core.Deadliner,
) *Prioritiser

NewForT exports newInternal for testing and returns a new prioritiser.

func (*Prioritiser) Prioritise

func (p *Prioritiser) Prioritise(ctx context.Context, msg *pbv1.PriorityMsg) error

Prioritise starts a new prioritisation instance for the provided message or returns an error.

func (*Prioritiser) Start

func (p *Prioritiser) Start(ctx context.Context)

Start starts a goroutine that cleans state. This must only be called once.

func (*Prioritiser) Subscribe

func (p *Prioritiser) Subscribe(fn subscriber)

Subscribe registers a prioritiser output subscriber function. This is not thread safe and MUST NOT be called after Run.

type Priority

type Priority proto.Message

Priority is one of many grouped by a Topic being prioritised in an Instance.

type ScoredPriority

type ScoredPriority struct {
	Priority string
	Score    int
}

ScoredPriority defines a resulting cluster-agreed priority including its score.

type Topic

type Topic proto.Message

Topic groups priorities in an instance.

type TopicProposal

type TopicProposal struct {
	Topic      string
	Priorities []string
}

TopicProposal defines the proposed priorities of a single prioritise topic.

type TopicResult

type TopicResult struct {
	Topic      string
	Priorities []ScoredPriority
}

TopicResult defines the resulting cluster-agreed upon priorities of a single prioritise topic.

func (TopicResult) PrioritiesOnly

func (r TopicResult) PrioritiesOnly() []string

PrioritiesOnly returns the priorities without scores.