Help us shape the future of Go! Take the 2026 Go Developer Survey

execution_controller

package
v0.57.29 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 26, 2026 License: Apache-2.0 Imports: 35 Imported by: 0

Documentation

Index

Constants

View Source 
const ConfigID = ControllerID

ConfigID is the string used to identify this config object.

View Source 
const ControllerID = "forge/execution"

ControllerID is the ID of the controller.

Variables

View Source 
var ErrNotExecController = errors.New("controller does not implement ExecController")

ErrNotExecController is returned if a exec.controller does not implement target.ExecController.

View Source 
var Version = controller.MustParseVersion("0.0.1")

Version is the version of the controller implementation.

Functions

This section is empty.

Types

type Config 

type Config struct {

	// EngineId is the world engine id for the forge state.
	EngineId string `protobuf:"bytes,1,opt,name=engine_id,json=engineId,proto3" json:"engineId,omitempty"`
	// ObjectKey is the Execution state object to attach to.
	// If not exists, waits for it to exist.
	ObjectKey string `protobuf:"bytes,2,opt,name=object_key,json=objectKey,proto3" json:"objectKey,omitempty"`
	// PeerId is the peer ID to use for the execution controller.
	// Must match the Execution peer except when reclaiming an expired claim.
	// If not set, will look up the peer id from the state.
	PeerId string `protobuf:"bytes,3,opt,name=peer_id,json=peerId,proto3" json:"peerId,omitempty"`
	// ResolveControllerConfigTimeout is a timeout for resolving the exec.controller config.
	ResolveControllerConfigTimeout string `` /* 152-byte string literal not displayed */
	// AllowNonExecController allows exec.controller to not implement ExecController.
	AllowNonExecController bool `` /* 129-byte string literal not displayed */
	// InputWorld is the default value for the "world" input.
	InputWorld *target.InputWorld `protobuf:"bytes,6,opt,name=input_world,json=inputWorld,proto3" json:"inputWorld,omitempty"`
	// ClaimId is the stable owner token used across controller retries.
	ClaimId string `protobuf:"bytes,7,opt,name=claim_id,json=claimId,proto3" json:"claimId,omitempty"`
	// ClaimLease is how long a claim stays live without renewal, as a duration
	// string. The controller renews at a third of the lease. Peers may reclaim
	// an Execution once its holder has missed the lease. Defaults to five minutes.
	ClaimLease string `protobuf:"bytes,8,opt,name=claim_lease,json=claimLease,proto3" json:"claimLease,omitempty"`
	// WorkerObjectKey selects the Worker's placement on reclaim. Required when
	// reclaiming a placed Execution; the peer must be linked to this Worker.
	WorkerObjectKey string `protobuf:"bytes,9,opt,name=worker_object_key,json=workerObjectKey,proto3" json:"workerObjectKey,omitempty"`
	// contains filtered or unexported fields
}

Config is the execution controller configuration.

func NewConfig 

func NewConfig(engineID, objectKey string, peerID peer.ID, inpWorld *forge_target.InputWorld) *Config

NewConfig constructs a new execution controller config. Sets the most important fields only.

func (*Config) BuildUniqueID 

func (c *Config) BuildUniqueID() string

BuildUniqueID builds the durable execution controller ID.

func (*Config) CloneMessageVT 

func (m *Config) CloneMessageVT() protobuf_go_lite.CloneMessage

func (*Config) CloneVT 

func (m *Config) CloneVT() *Config

func (*Config) EqualMessageVT 

func (this *Config) EqualMessageVT(thatMsg any) bool

func (*Config) EqualVT 

func (this *Config) EqualVT(that *Config) bool

func (*Config) EqualsConfig 

func (c *Config) EqualsConfig(other config.Config) bool

EqualsConfig checks if the other config is equal.

func (*Config) GetAllowNonExecController 

func (x *Config) GetAllowNonExecController() bool

func (*Config) GetClaimId added in v0.57.0 

func (x *Config) GetClaimId() string

func (*Config) GetClaimLease 

func (x *Config) GetClaimLease() string

func (*Config) GetConfigID 

func (c *Config) GetConfigID() string

GetConfigID returns the unique string for this configuration type. This string is stored with the encoded config.

func (*Config) GetEngineId 

func (x *Config) GetEngineId() string

func (*Config) GetInputWorld 

func (x *Config) GetInputWorld() *target.InputWorld

func (*Config) GetObjectKey 

func (x *Config) GetObjectKey() string

func (*Config) GetPeerId 

func (x *Config) GetPeerId() string

func (*Config) GetResolveControllerConfigTimeout 

func (x *Config) GetResolveControllerConfigTimeout() string

func (*Config) GetWorkerObjectKey 

func (x *Config) GetWorkerObjectKey() string

func (*Config) MarshalJSON 

func (x *Config) MarshalJSON() ([]byte, error)

MarshalJSON marshals the Config to JSON.

func (*Config) MarshalProtoJSON 

func (x *Config) MarshalProtoJSON(s *json.MarshalState)

MarshalProtoJSON marshals the Config message to JSON.

func (*Config) MarshalProtoText 

func (x *Config) MarshalProtoText() string

func (*Config) MarshalToSizedBufferVT 

func (m *Config) MarshalToSizedBufferVT(dAtA []byte) (int, error)

func (*Config) MarshalToVT 

func (m *Config) MarshalToVT(dAtA []byte) (int, error)

func (*Config) MarshalVT 

func (m *Config) MarshalVT() (dAtA []byte, err error)

func (*Config) ParseClaimLease 

func (c *Config) ParseClaimLease() (time.Duration, error)

ParseClaimLease parses a lease longer than the clock-skew allowance.

func (*Config) ParsePeerID 

func (c *Config) ParsePeerID() (peer.ID, error)

ParsePeerID parses the peer ID field.

func (*Config) ParseResolveControllerConfigTimeout 

func (c *Config) ParseResolveControllerConfigTimeout() (time.Duration, error)

ParseResolveControllerConfigTimeout parses the timeout dur.

func (*Config) ProtoMessage 

func (*Config) ProtoMessage()

func (*Config) Reset 

func (x *Config) Reset()

func (*Config) SizeVT 

func (m *Config) SizeVT() (n int)

func (*Config) String 

func (x *Config) String() string

func (*Config) UnmarshalJSON 

func (x *Config) UnmarshalJSON(b []byte) error

UnmarshalJSON unmarshals the Config from JSON.

func (*Config) UnmarshalProtoJSON 

func (x *Config) UnmarshalProtoJSON(s *json.UnmarshalState)

UnmarshalProtoJSON unmarshals the Config message from JSON.

func (*Config) UnmarshalVT 

func (m *Config) UnmarshalVT(dAtA []byte) error

func (*Config) Validate 

func (c *Config) Validate() error

Validate validates the configuration. This is a cursory validation to see if the values "look correct."

type Controller 

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

Controller implements the Execution controller. An Execution is an attempt to process a given Target. Usually constructed & managed by the Pass controller. Spawns "exec" controllers on the provided bus.

func NewController 

func NewController(
	le *logrus.Entry,
	bus bus.Bus,
	conf *Config,
) *Controller

NewController constructs a new Execution controller. Note: exec.controller instances will be run on the given bus.

func StartControllerWithConfig 

func StartControllerWithConfig(
	ctx context.Context,
	b bus.Bus,
	conf *Config,
) (*Controller, directive.Reference, error)

StartControllerWithConfig starts a execution controller with a config. Waits for the controller to start. Returns a Release function to close the controller when done.

func (*Controller) CancelWaitCh added in v0.57.2 

func (c *Controller) CancelWaitCh() <-chan struct{}

CancelWaitCh returns a channel that closes once durable cancellation of the execution has been observed.

func (*Controller) CheckExecControllerConfig 

func (c *Controller) CheckExecControllerConfig(ctx context.Context, conf config.Config) error

CheckExecControllerConfig checks if the controller config is OK to execute.

func (*Controller) Close 

func (c *Controller) Close() error

Close releases any resources used by the controller. Error indicates any issue encountered releasing.

func (*Controller) Execute 

func (c *Controller) Execute(ctx context.Context) error

Execute executes the controller. Returning nil ends execution. Returning an error triggers a retry with backoff.

func (*Controller) GetControllerInfo 

func (c *Controller) GetControllerInfo() *controller.Info

GetControllerInfo returns information about the controller.

func (*Controller) HandleDirective 

func (c *Controller) HandleDirective(ctx context.Context, inst directive.Instance) ([]directive.Resolver, error)

HandleDirective asks if the handler can resolve the directive.

func (*Controller) ProcessState 

func (c *Controller) ProcessState(
	ctx context.Context,
	le *logrus.Entry,
	ws world.WorldState,
	obj world.ObjectState,
	rootRef *bucket.ObjectRef, rev uint64,
) (waitForChanges bool, err error)

ProcessState implements the state reconciliation loop.

NOTE: the Execution may be updated by the controller several times during execution.

type ExecConfig 

type ExecConfig struct {

	// Execution is the current state of the execution.
	// NOTE: value_set and result are set to nil.
	Execution *execution.Execution `protobuf:"bytes,1,opt,name=execution,proto3" json:"execution,omitempty"`
	// Target is the current target to execute.
	// This is the value of the TargetRef in execution.
	Target *target.Target `protobuf:"bytes,2,opt,name=target,proto3" json:"target,omitempty"`
	// contains filtered or unexported fields
}

ExecConfig is a configuration for the execution routine.

func (*ExecConfig) CloneMessageVT 

func (m *ExecConfig) CloneMessageVT() protobuf_go_lite.CloneMessage

func (*ExecConfig) CloneVT 

func (m *ExecConfig) CloneVT() *ExecConfig

func (*ExecConfig) EqualMessageVT 

func (this *ExecConfig) EqualMessageVT(thatMsg any) bool

func (*ExecConfig) EqualVT 

func (this *ExecConfig) EqualVT(that *ExecConfig) bool

func (*ExecConfig) GetExecution 

func (x *ExecConfig) GetExecution() *execution.Execution

func (*ExecConfig) GetTarget 

func (x *ExecConfig) GetTarget() *target.Target

func (*ExecConfig) MarshalJSON 

func (x *ExecConfig) MarshalJSON() ([]byte, error)

MarshalJSON marshals the ExecConfig to JSON.

func (*ExecConfig) MarshalProtoJSON 

func (x *ExecConfig) MarshalProtoJSON(s *json.MarshalState)

MarshalProtoJSON marshals the ExecConfig message to JSON.

func (*ExecConfig) MarshalProtoText 

func (x *ExecConfig) MarshalProtoText() string

func (*ExecConfig) MarshalToSizedBufferVT 

func (m *ExecConfig) MarshalToSizedBufferVT(dAtA []byte) (int, error)

func (*ExecConfig) MarshalToVT 

func (m *ExecConfig) MarshalToVT(dAtA []byte) (int, error)

func (*ExecConfig) MarshalVT 

func (m *ExecConfig) MarshalVT() (dAtA []byte, err error)

func (*ExecConfig) ProtoMessage 

func (*ExecConfig) ProtoMessage()

func (*ExecConfig) Reset 

func (x *ExecConfig) Reset()

func (*ExecConfig) SizeVT 

func (m *ExecConfig) SizeVT() (n int)

func (*ExecConfig) String 

func (x *ExecConfig) String() string

func (*ExecConfig) UnmarshalJSON 

func (x *ExecConfig) UnmarshalJSON(b []byte) error

UnmarshalJSON unmarshals the ExecConfig from JSON.

func (*ExecConfig) UnmarshalProtoJSON 

func (x *ExecConfig) UnmarshalProtoJSON(s *json.UnmarshalState)

UnmarshalProtoJSON unmarshals the ExecConfig message from JSON.

func (*ExecConfig) UnmarshalVT 

func (m *ExecConfig) UnmarshalVT(dAtA []byte) error

type Factory 

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

Factory constructs a Execution controller.

func NewFactory 

func NewFactory(bus bus.Bus) *Factory

NewFactory builds a controller factory.

func (*Factory) Construct 

func (t *Factory) Construct(
	ctx context.Context,
	conf config.Config,
	opts controller.ConstructOpts,
) (controller.Controller, error)

Construct constructs the associated controller given configuration.

func (*Factory) ConstructConfig 

func (t *Factory) ConstructConfig() config.Config

ConstructConfig constructs an instance of the controller configuration.

func (*Factory) GetConfigID 

func (t *Factory) GetConfigID() string

GetConfigID returns the unique ID for the config.

func (*Factory) GetControllerID 

func (t *Factory) GetControllerID() string

GetControllerID returns the unique ID for the controller.

func (*Factory) GetVersion 

func (t *Factory) GetVersion() controller.Version

GetVersion returns the version of this controller.

type Lease 

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

Lease renews one granted claim and cancels its operation ClaimClockSkew before the last committed expiry. Renewal and settlement stop permanently on a stale epoch. Reclaim cannot overlap operation when the reclaimer's clock lead plus operation's cancellation drain time stays within ClaimClockSkew.

func NewLease 

func NewLease(le *logrus.Entry, expiry time.Time, duration time.Duration, renew func(context.Context, time.Time) error) *Lease

NewLease constructs a lease for one granted claim with duration greater than ClaimClockSkew. renew must honor cancellation and report success only after the new expiry commits. Construction and Execute require an already granted claim.

func (*Lease) Execute 

func (l *Lease) Execute(rctx context.Context, operation func(context.Context) error) error

Execute runs and drains operation under the committed lease. A failed or blocked renewal cannot delay cancellation past expiry minus ClaimClockSkew. Losing the lease returns nil so a routine does not restart the same claim. Execute joins renewal before returning; renew must honor its context.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.