sync

Documentation

Overview

Package sync provides interfaces for managing externally synchronized APIs.

The methods allow queries to be performed on an API to allow the determination of where blocking operations between threads of execution happen. These methods allow us to reason about execution in a non-linear way.

Index

• func MutateWithSubcommands(ctx context.Context, c *path.Capture, cmds []api.Cmd, ...) error
• func MutationCmdsFor(ctx context.Context, c *path.Capture, cmds []api.Cmd, id api.CmdID, ...) ([]api.Cmd, error)
• type Data
  • func NewData() *Data
  • func (s Data) SortedKeys() SynchronizationIndices
• type ExecutionRanges
  • func (e ExecutionRanges) SortedKeys() SynchronizationIndices
• type SubcommandReference
• type SynchronizationIndices
  • func (s SynchronizationIndices) Len() int
  • func (s SynchronizationIndices) Less(i, j int) bool
  • func (s SynchronizationIndices) Swap(i, j int)
• type SynchronizedAPI

Functions

func MutateWithSubcommands

func MutateWithSubcommands(ctx context.Context, c *path.Capture, cmds []api.Cmd, callback func(*api.State, api.SubCmdIdx, api.Cmd)) error

MutateWithSubcommands returns a list of commands that represent the correct mutations to have the state for all commands before and including the given index.

func MutationCmdsFor

func MutationCmdsFor(ctx context.Context, c *path.Capture, cmds []api.Cmd, id api.CmdID, subindex []uint64) ([]api.Cmd, error)

MutationCmdsFor returns a list of command that represent the correct mutations to have the state for all commands before and including the given index.

Types

type Data

type Data struct {
	// CommandRanges contains commands that will be blocked from completion,
	// and what subcommands will be made available by future commands.
	CommandRanges map[api.CmdID]ExecutionRanges
	// SubcommandReferences contains the information about every subcommand
	// run by a particular command.
	SubcommandReferences map[api.CmdID][]SubcommandReference
	// SubcommandGroups represents the last Subcommand in every command buffer.
	SubcommandGroups map[api.CmdID][]api.SubCmdIdx
}

Data contains a map of synchronization pairs.

func NewData

func NewData() *Data

NewData creates a new clean Data object

func (Data) SortedKeys

func (s Data) SortedKeys() SynchronizationIndices

SortedKeys returns the keys of 's' in sorted order

type ExecutionRanges

type ExecutionRanges struct {
	// LastIndex is the final subcommand that exists within this command.
	LastIndex api.SubCmdIdx
	// Ranges defines which future command will unblock the command in question, and
	// which subcommand is the last that will be run at that point.
	Ranges map[api.CmdID]api.SubCmdIdx
}

ExecutionRanges contains the information about a blocked command.

func (ExecutionRanges) SortedKeys

func (e ExecutionRanges) SortedKeys() SynchronizationIndices

SortedKeys returns the keys of 'e' in sorted order

type SubcommandReference

type SubcommandReference struct {
	Index         api.SubCmdIdx
	GeneratingCmd api.CmdID
}

SubcommandReference contains a subcommand index as well as an atom.ID that references the command that generated this subcommand.

type SynchronizationIndices

type SynchronizationIndices []api.CmdID

SynchronizationIndices is a list of command identifiers, defining the location of a one side synchronization dependency.

func (SynchronizationIndices) Len

func (s SynchronizationIndices) Len() int

Len returns the length of subcommand indices

func (SynchronizationIndices) Less

func (s SynchronizationIndices) Less(i, j int) bool

Less returns true if s[i] < s[j]

func (SynchronizationIndices) Swap

func (s SynchronizationIndices) Swap(i, j int)

Swap swaps the 2 subcommands in the given slice

type SynchronizedAPI

type SynchronizedAPI interface {
	// GetTerminator returns a transform that will allow the given capture to be terminated
	// after a atom
	GetTerminator(ctx context.Context, c *path.Capture) (transform.Terminator, error)

	// ResolveSynchronization resolve all of the synchronization information for
	// the given API
	ResolveSynchronization(ctx context.Context, d *Data, c *path.Capture) error

	// MutateSubcommands mutates the given Atom calling callback after each subcommand is executed.
	MutateSubcommands(ctx context.Context, id api.CmdID, cmd api.Cmd, s *api.State, callback func(*api.State, api.SubCmdIdx, api.Cmd)) error
}

SynchronizedAPI defines an API that explicitly has multiple threads of execution. This means that replays are not necessarily linear in terms of atoms.