actor

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Nov 29, 2023 License: Apache-2.0 Imports: 36 Imported by: 0

Documentation

Overview

Package actor declares the types used to represent actors in the Actor Model.

The actors model provide a high level abstraction for writing concurrent and distributed systems. This approach simplifies the burden imposed on engineers, such as explicit locks and concurrent access to shared state, as actors receive messages synchronously.

The following quote from Wikipedia distills the definition of an actor down to its essence

In response to a message that it receives, an actor can: make local decisions, create more actors,
send more messages, and determine how to respond to the next message received.

Creating Actors

Props provide the building blocks for declaring how actors should be created. The following example defines an actor using a function literal to process messages:

var props Props = actor.PropsFromFunc(func(c Context) {
	// process messages
})

Alternatively, a type which conforms to the Actor interface, by defining a single Receive method, can be used.

type MyActor struct {}

func (a *MyActor) Receive(c Context) {
	// process messages
}

var props Props = actor.PropsFromProducer(func() Actor { return &MyActor{} })

Spawn and SpawnNamed use the given props to create a running instances of an actor. Once spawned, the actor is ready to process incoming messages. To spawn an actor with a unique name, use

pid := context.Spawn(props)

The result of calling Spawn is a unique PID or process identifier.

Each time an actor is spawned, a new mailbox is created and associated with the PID. Messages are sent to the mailbox and then forwarded to the actor to process.

Processing Messages

An actor processes messages via its Receive handler. The signature of this function is:

Receive(c actor.Context)

The actor system guarantees that this method is called synchronously, therefore there is no requirement to protect shared state inside calls to this function.

Communicating With Actors

A PID is the primary interface for sending messages to actors. Context.Send is used to send an asynchronous message to the actor associated with the PID:

context.Aend(pid, "Hello World")

Depending on the requirements, communication between actors can take place synchronously or asynchronously. Regardless of the circumstances, actors always communicate via a PID.

When sending a message using PID.Request or PID.RequestFuture, the actor which receives the message will respond using the Context.Sender method, which returns the PID of of the sender.

For synchronous communication, an actor will use a Future and wait for the result before continuing. To send a message to an actor and wait for a response, use the RequestFuture method, which returns a Future:

f := actor.RequestFuture(pid,"Hello", 50 * time.Millisecond)
res, err := f.Result() // waits for pid to reply
Example

Demonstrates how to create an actor using a function literal and how to send a message asynchronously

context := system.Root
props := actor.PropsFromFunc(func(c actor.Context) {
	if msg, ok := c.Message().(string); ok {
		fmt.Println(msg) // outputs "Hello World"
	}
})

pid := context.Spawn(props)

context.Send(pid, "Hello World")
time.Sleep(time.Millisecond * 100)

_ = context.StopFuture(pid).Wait() // wait for the actor to stop
Output:

Hello World
Example (Synchronous)

Demonstrates how to send a message from one actor to another and for the caller to wait for a response before proceeding

var wg sync.WaitGroup

wg.Add(1)

// callee will wait for the PING message
callee := system.Root.Spawn(actor.PropsFromFunc(func(c actor.Context) {
	if msg, ok := c.Message().(string); ok {
		fmt.Println(msg) // outputs PING
		c.Respond("PONG")
	}
}))

// caller will send a PING message and wait for the PONG
caller := system.Root.Spawn(actor.PropsFromFunc(func(c actor.Context) {
	switch msg := c.Message().(type) {
	// the first message an actor receives after it has started
	case *actor.Started:
		// send a PING to the callee, and specify the response
		// is sent to Self, which is this actor'pids PID
		c.Request(callee, "PING")

	case string:
		fmt.Println(msg) // PONG
		wg.Done()
	}
}))

wg.Wait()
_ = system.Root.StopFuture(callee).Wait()
_ = system.Root.StopFuture(caller).Wait()
Output:

PING
PONG

Index

Examples

Constants

View Source
const (
	DefaultPriority = int8(priorityLevels / 2)
)

Variables

View Source
var (
	TerminatedReason_name = map[int32]string{
		0: "Stopped",
		1: "AddressTerminated",
		2: "NotFound",
	}
	TerminatedReason_value = map[string]int32{
		"Stopped":           0,
		"AddressTerminated": 1,
		"NotFound":          2,
	}
)

Enum value maps for TerminatedReason.

View Source
var EmptyMessageHeader = make(messageHeader)
View Source
var ErrDeadLetter = errors.New("future: dead letter")

ErrDeadLetter is meaning you request to a unreachable PID.

View Source
var ErrNameExists = errors.New("spawn: name exists")

ErrNameExists is the error used when an existing name is used for spawning an actor.

View Source
var ErrTimeout = errors.New("future: timeout")

ErrTimeout is the error used when a future times out before receiving a result.

View Source
var File_actor_proto protoreflect.FileDescriptor

Functions

func NewDeadLetter

func NewDeadLetter(actorSystem *ActorSystem) *deadLetterProcess

func NewGuardians

func NewGuardians(actorSystem *ActorSystem) *guardiansValue

func NewPriorityGoringQueue

func NewPriorityGoringQueue() *priorityQueue

func NewPriorityMpscQueue

func NewPriorityMpscQueue() *priorityQueue

func NewPriorityQueue

func NewPriorityQueue(queueProducer func() queue) *priorityQueue

func SubscribeSupervision

func SubscribeSupervision(actorSystem *ActorSystem)

func UnwrapEnvelope

func UnwrapEnvelope(message interface{}) (ReadonlyMessageHeader, interface{}, *PID)

func UnwrapEnvelopeMessage

func UnwrapEnvelopeMessage(message interface{}) interface{}

Types

type Actor

type Actor interface {
	Receive(c Context)
}

Actor is the interface that defines the Receive method.

Receive is sent messages to be processed from the mailbox associated with the instance of the actor

type ActorProcess

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

func NewActorProcess

func NewActorProcess(mailbox Mailbox) *ActorProcess

func (*ActorProcess) SendSystemMessage

func (ref *ActorProcess) SendSystemMessage(_ *PID, message interface{})

func (*ActorProcess) SendUserMessage

func (ref *ActorProcess) SendUserMessage(_ *PID, message interface{})

func (*ActorProcess) Stop

func (ref *ActorProcess) Stop(pid *PID)

type ActorSystem

type ActorSystem struct {
	ProcessRegistry *ProcessRegistryValue
	Root            *RootContext
	EventStream     *eventstream.EventStream
	Guardians       *guardiansValue
	DeadLetter      *deadLetterProcess
	Extensions      *extensions.Extensions
	Config          *Config
	ID              string
	// contains filtered or unexported fields
}

func NewActorSystem

func NewActorSystem(options ...ConfigOption) *ActorSystem

func NewActorSystemWithConfig

func NewActorSystemWithConfig(config *Config) *ActorSystem

func (*ActorSystem) Address

func (as *ActorSystem) Address() string

func (*ActorSystem) GetHostPort

func (as *ActorSystem) GetHostPort() (host string, port int, err error)

func (*ActorSystem) IsStopped added in v0.3.0

func (as *ActorSystem) IsStopped() bool

func (*ActorSystem) Logger added in v0.3.0

func (as *ActorSystem) Logger() *slog.Logger

func (*ActorSystem) NewLocalPID

func (as *ActorSystem) NewLocalPID(id string) *PID

func (*ActorSystem) Shutdown

func (as *ActorSystem) Shutdown()

type AddressResolver

type AddressResolver func(*PID) (Process, bool)

An AddressResolver is used to resolve remote actors

type AutoReceiveMessage

type AutoReceiveMessage interface {
	AutoReceiveMessage()
}

An AutoReceiveMessage is a special kind of user message that will be handled in some way automatically by the actor

type AutoRespond

type AutoRespond interface {
	GetAutoResponse(context Context) interface{}
}

type Behavior

type Behavior []ReceiveFunc

func NewBehavior

func NewBehavior() Behavior

func (*Behavior) Become

func (b *Behavior) Become(receive ReceiveFunc)

func (*Behavior) BecomeStacked

func (b *Behavior) BecomeStacked(receive ReceiveFunc)

func (*Behavior) Receive

func (b *Behavior) Receive(context Context)

func (*Behavior) UnbecomeStacked

func (b *Behavior) UnbecomeStacked()

type Config

type Config struct {
	DeadLetterThrottleInterval  time.Duration      // throttle deadletter logging after this interval
	DeadLetterThrottleCount     int32              // throttle deadletter logging after this count
	DeadLetterRequestLogging    bool               // do not log dead-letters with sender
	DeveloperSupervisionLogging bool               // console log and promote supervision logs to Warning level
	DiagnosticsSerializer       func(Actor) string // extract diagnostics from actor and return as string
	MetricsProvider             metric.MeterProvider
	LoggerFactory               func(system *ActorSystem) *slog.Logger
}

func Configure

func Configure(options ...ConfigOption) *Config

Configure sets the configuration options

func NewConfig

func NewConfig() *Config

type ConfigOption

type ConfigOption func(config *Config)

ConfigOption is a function that configures the actor system

func WithDeadLetterRequestLogging

func WithDeadLetterRequestLogging(enabled bool) ConfigOption

WithDeadLetterRequestLogging sets the dead letter request logging on or off

func WithDeadLetterThrottleCount

func WithDeadLetterThrottleCount(count int32) ConfigOption

WithDeadLetterThrottleCount sets the dead letter throttle count

func WithDeadLetterThrottleInterval

func WithDeadLetterThrottleInterval(duration time.Duration) ConfigOption

WithDeadLetterThrottleInterval sets the dead letter throttle interval

func WithDefaultPrometheusProvider

func WithDefaultPrometheusProvider(port ...int) ConfigOption

WithDefaultPrometheusProvider sets the default prometheus provider

func WithDeveloperSupervisionLogging

func WithDeveloperSupervisionLogging(enabled bool) ConfigOption

WithDeveloperSupervisionLogging sets the developer supervision logging on or off

func WithDiagnosticsSerializer

func WithDiagnosticsSerializer(serializer func(Actor) string) ConfigOption

WithDiagnosticsSerializer sets the diagnostics serializer

func WithLoggerFactory added in v0.3.0

func WithLoggerFactory(factory func(system *ActorSystem) *slog.Logger) ConfigOption

WithLoggerFactory sets the logger factory to use for the actor system

func WithMetricProviders

func WithMetricProviders(provider metric.MeterProvider) ConfigOption

WithMetricProviders sets the metric providers

type Context

type Context interface {
	// contains filtered or unexported methods
}

Context contains contextual information for actors

Example (SetReceiveTimeout)

SetReceiveTimeout allows an actor to be notified repeatedly if it does not receive any messages for a specified duration

package main

import (
	"fmt"
	"sync"
	"time"

	"github.com/keecon/protoactor-go/actor"
)

type setReceiveTimeoutActor struct {
	*sync.WaitGroup
}

// Receive is the default message handler when an actor is started
func (f *setReceiveTimeoutActor) Receive(context actor.Context) {
	switch context.Message().(type) {
	case *actor.Started:
		// when the actor starts, set the receive timeout to 10 milliseconds.
		//
		// the system will send an *actor.ReceiveTimeout message every time the timeout
		// expires until SetReceiveTimeout is called again with a duration < 1 ms]
		context.SetReceiveTimeout(10 * time.Millisecond)
	case *actor.ReceiveTimeout:
		fmt.Println("timed out")
		f.Done()
	}
}

// SetReceiveTimeout allows an actor to be notified repeatedly if it does not receive any messages
// for a specified duration
func main() {
	wg := &sync.WaitGroup{}
	wg.Add(1)

	pid := system.Root.Spawn(actor.PropsFromProducer(func() actor.Actor { return &setReceiveTimeoutActor{wg} }))
	defer func() {
		_ = system.Root.StopFuture(pid).Wait()
	}()

	wg.Wait() // wait for the ReceiveTimeout message

}
Output:

timed out

type ContextDecorator

type ContextDecorator func(next ContextDecoratorFunc) ContextDecoratorFunc

type ContextDecoratorFunc

type ContextDecoratorFunc func(ctx Context) Context

type DeadLetterEvent

type DeadLetterEvent struct {
	PID     *PID        // The invalid process, to which the message was sent
	Message interface{} // The message that could not be delivered
	Sender  *PID        // the process that sent the Message
}

A DeadLetterEvent is published via event.Publish when a message is sent to a nonexistent PID

type DeadLetterResponse

type DeadLetterResponse struct {
	Target *PID `protobuf:"bytes,1,opt,name=Target,proto3" json:"Target,omitempty"`
	// contains filtered or unexported fields
}

func (*DeadLetterResponse) Descriptor deprecated

func (*DeadLetterResponse) Descriptor() ([]byte, []int)

Deprecated: Use DeadLetterResponse.ProtoReflect.Descriptor instead.

func (*DeadLetterResponse) GetTarget

func (x *DeadLetterResponse) GetTarget() *PID

func (*DeadLetterResponse) ProtoMessage

func (*DeadLetterResponse) ProtoMessage()

func (*DeadLetterResponse) ProtoReflect

func (x *DeadLetterResponse) ProtoReflect() protoreflect.Message

func (*DeadLetterResponse) Reset

func (x *DeadLetterResponse) Reset()

func (*DeadLetterResponse) String

func (x *DeadLetterResponse) String() string

type DeciderFunc

type DeciderFunc func(reason interface{}) Directive

DeciderFunc is a function which is called by a SupervisorStrategy

type Directive

type Directive int

Directive is an enum for supervision actions

const (
	// ResumeDirective instructs the supervisor to resume the actor and continue processing messages
	ResumeDirective Directive = iota

	// RestartDirective instructs the supervisor to discard the actor, replacing it with a new instance,
	// before processing additional messages
	RestartDirective

	// StopDirective instructs the supervisor to stop the actor
	StopDirective

	// EscalateDirective instructs the supervisor to escalate handling of the failure to the actor'pids parent supervisor
	EscalateDirective
)

Directive determines how a supervisor should handle a faulting actor

func DefaultDecider

func DefaultDecider(_ interface{}) Directive

DefaultDecider is a decider that will always restart the failing child actor

func (Directive) String

func (i Directive) String() string

type Dispatcher

type Dispatcher interface {
	Schedule(fn func())
	Throughput() int
}

func NewDefaultDispatcher

func NewDefaultDispatcher(throughput int) Dispatcher

func NewSynchronizedDispatcher

func NewSynchronizedDispatcher(throughput int) Dispatcher

type EventStreamProcess

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

func NewEventStreamProcess

func NewEventStreamProcess(actorSystem *ActorSystem) *EventStreamProcess

func (*EventStreamProcess) SendSystemMessage

func (e *EventStreamProcess) SendSystemMessage(_ *PID, _ interface{})

func (*EventStreamProcess) SendUserMessage

func (e *EventStreamProcess) SendUserMessage(_ *PID, message interface{})

func (*EventStreamProcess) Stop

func (e *EventStreamProcess) Stop(_ *PID)

type ExtensionContext

type ExtensionContext interface {
	// contains filtered or unexported methods
}

type Failure

type Failure struct {
	Who          *PID
	Reason       interface{}
	RestartStats *RestartStatistics
	Message      interface{}
}

Failure message is sent to an actor parent when an exception is thrown by one of its methods

func (*Failure) SystemMessage

func (*Failure) SystemMessage()

type Future

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

func NewFuture

func NewFuture(actorSystem *ActorSystem, d time.Duration) *Future

NewFuture creates and returns a new actor.Future with a timeout of duration d.

func (*Future) PID

func (f *Future) PID() *PID

PID to the backing actor for the Future result.

func (*Future) PipeTo

func (f *Future) PipeTo(pids ...*PID)

PipeTo forwards the result or error of the future to the specified pids.

Example
package main

import (
	"fmt"
	"sync"
	"time"

	"github.com/keecon/protoactor-go/actor"
)

var system = actor.NewActorSystem()

func main() {
	var wg sync.WaitGroup
	wg.Add(1)

	// test actor that will be the target of the future PipeTo
	pid := system.Root.Spawn(actor.PropsFromFunc(func(ctx actor.Context) {
		// check if the message is a string and therefore
		// the "hello world" message piped from the future
		if m, ok := ctx.Message().(string); ok {
			fmt.Println(m)
			wg.Done()
		}
	}))

	f := actor.NewFuture(system, 50*time.Millisecond)
	f.PipeTo(pid)
	// resolve the future and pipe to waiting actor
	system.Root.Send(f.PID(), "hello world")
	wg.Wait()

}
Output:

hello world

func (*Future) Result

func (f *Future) Result() (interface{}, error)

Result waits for the future to resolve.

func (*Future) Wait

func (f *Future) Wait() error

type IgnoreDeadLetterLogging

type IgnoreDeadLetterLogging interface {
	IgnoreDeadLetterLogging()
}

IgnoreDeadLetterLogging messages are not logged in deadletter log

type InfrastructureMessage

type InfrastructureMessage interface {
	InfrastructureMessage()
}

InfrastructureMessage is a marker for all built in Proto.Actor messages

type Mailbox

type Mailbox interface {
	PostUserMessage(message interface{})
	PostSystemMessage(message interface{})
	RegisterHandlers(invoker MessageInvoker, dispatcher Dispatcher)
	Start()
	UserMessageCount() int
}

Mailbox interface is used to enqueue messages to the mailbox

type MailboxMessage

type MailboxMessage interface {
	MailboxMessage()
}

type MailboxMiddleware

type MailboxMiddleware interface {
	MailboxStarted()
	MessagePosted(message interface{})
	MessageReceived(message interface{})
	MailboxEmpty()
}

MailboxMiddleware is an interface for intercepting messages and events in the mailbox

type MailboxProducer

type MailboxProducer func() Mailbox

MailboxProducer is a function which creates a new mailbox

func Bounded

func Bounded(size int, mailboxStats ...MailboxMiddleware) MailboxProducer

Bounded returns a producer which creates a bounded mailbox of the specified size.

func BoundedDropping

func BoundedDropping(size int, mailboxStats ...MailboxMiddleware) MailboxProducer

BoundedDropping returns a producer which creates a bounded mailbox of the specified size that drops front element on push.

func Unbounded

func Unbounded(mailboxStats ...MailboxMiddleware) MailboxProducer

Unbounded returns a producer which creates an unbounded mailbox

func UnboundedLockfree

func UnboundedLockfree(mailboxStats ...MailboxMiddleware) MailboxProducer

UnboundedLockfree returns a producer which creates an unbounded, lock-free mailbox. This mailbox is cheaper to allocate, but has a slower throughput than the plain Unbounded mailbox.

func UnboundedPriority

func UnboundedPriority(mailboxStats ...MailboxMiddleware) MailboxProducer

func UnboundedPriorityMpsc

func UnboundedPriorityMpsc(mailboxStats ...MailboxMiddleware) MailboxProducer

type MessageBatch

type MessageBatch interface {
	GetMessages() []interface{}
}

type MessageEnvelope

type MessageEnvelope struct {
	Header  messageHeader
	Message interface{}
	Sender  *PID
}

func WrapEnvelope

func WrapEnvelope(message interface{}) *MessageEnvelope

func (*MessageEnvelope) GetHeader

func (envelope *MessageEnvelope) GetHeader(key string) string

func (*MessageEnvelope) SetHeader

func (envelope *MessageEnvelope) SetHeader(key string, value string)

type MessageInvoker

type MessageInvoker interface {
	InvokeSystemMessage(interface{})
	InvokeUserMessage(interface{})
	EscalateFailure(reason interface{}, message interface{})
}

MessageInvoker is the interface used by a mailbox to forward messages for processing

type Metrics

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

func NewMetrics

func NewMetrics(system *ActorSystem, provider metric.MeterProvider) *Metrics

func (*Metrics) CommonLabels

func (m *Metrics) CommonLabels(ctx Context) []attribute.KeyValue

func (*Metrics) Enabled

func (m *Metrics) Enabled() bool

func (*Metrics) ExtensionID

func (m *Metrics) ExtensionID() extensions.ExtensionID

func (*Metrics) PrepareMailboxLengthGauge

func (m *Metrics) PrepareMailboxLengthGauge()

type NotInfluenceReceiveTimeout

type NotInfluenceReceiveTimeout interface {
	NotInfluenceReceiveTimeout()
}

NotInfluenceReceiveTimeout messages will not reset the ReceiveTimeout timer of an actor that receives the message

type PID

type PID struct {
	Address   string `protobuf:"bytes,1,opt,name=Address,proto3" json:"Address,omitempty"`
	Id        string `protobuf:"bytes,2,opt,name=Id,proto3" json:"Id,omitempty"`
	RequestId uint32 `protobuf:"varint,3,opt,name=request_id,json=requestId,proto3" json:"request_id,omitempty"`
	// contains filtered or unexported fields
}

func NewPID

func NewPID(address, id string) *PID

NewPID returns a new instance of the PID struct.

func UnwrapEnvelopeSender

func UnwrapEnvelopeSender(message interface{}) *PID

func (*PID) Descriptor deprecated

func (*PID) Descriptor() ([]byte, []int)

Deprecated: Use PID.ProtoReflect.Descriptor instead.

func (*PID) Equal

func (pid *PID) Equal(other *PID) bool

func (*PID) GetAddress

func (x *PID) GetAddress() string

func (*PID) GetId

func (x *PID) GetId() string

func (*PID) GetRequestId

func (x *PID) GetRequestId() uint32

func (*PID) ProtoMessage

func (*PID) ProtoMessage()

func (*PID) ProtoReflect

func (x *PID) ProtoReflect() protoreflect.Message

func (*PID) Reset

func (x *PID) Reset()

func (*PID) String

func (x *PID) String() string

type PIDSet

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

func NewPIDSet

func NewPIDSet(pids ...*PID) *PIDSet

NewPIDSet returns a new PIDSet with the given pids.

func (*PIDSet) Add

func (p *PIDSet) Add(v *PID)

Add adds the element v to the set.

func (*PIDSet) Clear

func (p *PIDSet) Clear()

Clear removes all the elements in the set.

func (*PIDSet) Clone

func (p *PIDSet) Clone() *PIDSet

func (*PIDSet) Contains

func (p *PIDSet) Contains(v *PID) bool

func (*PIDSet) Empty

func (p *PIDSet) Empty() bool

Empty reports whether the set is empty.

func (*PIDSet) ForEach

func (p *PIDSet) ForEach(f func(i int, pid *PID))

ForEach invokes f for every element of the set.

func (*PIDSet) Get

func (p *PIDSet) Get(index int) *PID

func (*PIDSet) Len

func (p *PIDSet) Len() int

Len returns the number of elements in the set.

func (*PIDSet) Remove

func (p *PIDSet) Remove(v *PID) bool

Remove removes v from the set and returns true if them element existed.

func (*PIDSet) Values

func (p *PIDSet) Values() []*PID

Values returns all the elements of the set as a slice.

type PoisonPill

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

user messages

func (*PoisonPill) AutoReceiveMessage

func (*PoisonPill) AutoReceiveMessage()

func (*PoisonPill) Descriptor deprecated

func (*PoisonPill) Descriptor() ([]byte, []int)

Deprecated: Use PoisonPill.ProtoReflect.Descriptor instead.

func (*PoisonPill) ProtoMessage

func (*PoisonPill) ProtoMessage()

func (*PoisonPill) ProtoReflect

func (x *PoisonPill) ProtoReflect() protoreflect.Message

func (*PoisonPill) Reset

func (x *PoisonPill) Reset()

func (*PoisonPill) String

func (x *PoisonPill) String() string

type PriorityMessage

type PriorityMessage interface {
	GetPriority() int8
}

type Process

type Process interface {
	SendUserMessage(pid *PID, message interface{})
	SendSystemMessage(pid *PID, message interface{})
	Stop(pid *PID)
}

A Process is an interface that defines the base contract for interaction of actors

type ProcessRegistryValue

type ProcessRegistryValue struct {
	SequenceID     uint64
	ActorSystem    *ActorSystem
	Address        string
	LocalPIDs      *SliceMap
	RemoteHandlers []AddressResolver
}

func NewProcessRegistry

func NewProcessRegistry(actorSystem *ActorSystem) *ProcessRegistryValue

func (*ProcessRegistryValue) Add

func (pr *ProcessRegistryValue) Add(process Process, id string) (*PID, bool)

func (*ProcessRegistryValue) Get

func (pr *ProcessRegistryValue) Get(pid *PID) (Process, bool)

func (*ProcessRegistryValue) GetLocal

func (pr *ProcessRegistryValue) GetLocal(id string) (Process, bool)

func (*ProcessRegistryValue) NextId

func (pr *ProcessRegistryValue) NextId() string

func (*ProcessRegistryValue) RegisterAddressResolver

func (pr *ProcessRegistryValue) RegisterAddressResolver(handler AddressResolver)

func (*ProcessRegistryValue) Remove

func (pr *ProcessRegistryValue) Remove(pid *PID)

type Producer

type Producer func() Actor

The Producer type is a function that creates a new actor

type ProducerWithActorSystem added in v0.3.0

type ProducerWithActorSystem func(system *ActorSystem) Actor

type Props

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

Props represents configuration to define how an actor should be created.

func PropsFromFunc

func PropsFromFunc(f ReceiveFunc, opts ...PropsOption) *Props

PropsFromFunc creates a props with the given receive func assigned as the actor producer.

func PropsFromProducer

func PropsFromProducer(producer Producer, opts ...PropsOption) *Props

PropsFromProducer creates a props with the given actor producer assigned.

func PropsFromProducerWithActorSystem added in v0.3.0

func PropsFromProducerWithActorSystem(producer ProducerWithActorSystem, opts ...PropsOption) *Props

PropsFromProducer creates a props with the given actor producer assigned.

func (*Props) Clone

func (props *Props) Clone(opts ...PropsOption) *Props

func (*Props) Configure

func (props *Props) Configure(opts ...PropsOption) *Props

type PropsOption

type PropsOption func(props *Props)

func WithContextDecorator

func WithContextDecorator(contextDecorator ...ContextDecorator) PropsOption

func WithDispatcher

func WithDispatcher(dispatcher Dispatcher) PropsOption

func WithFunc

func WithFunc(f ReceiveFunc) PropsOption

func WithGuardian

func WithGuardian(guardian SupervisorStrategy) PropsOption

func WithMailbox

func WithMailbox(mailbox MailboxProducer) PropsOption

func WithOnInit

func WithOnInit(init ...func(ctx Context)) PropsOption

func WithProducer

func WithProducer(p Producer) PropsOption

func WithReceiverMiddleware

func WithReceiverMiddleware(middleware ...ReceiverMiddleware) PropsOption

func WithSenderMiddleware

func WithSenderMiddleware(middleware ...SenderMiddleware) PropsOption

func WithSpawnFunc

func WithSpawnFunc(spawn SpawnFunc) PropsOption

func WithSpawnMiddleware

func WithSpawnMiddleware(middleware ...SpawnMiddleware) PropsOption

func WithSupervisor

func WithSupervisor(supervisor SupervisorStrategy) PropsOption

type ReadonlyMessageHeader

type ReadonlyMessageHeader interface {
	Get(key string) string
	Keys() []string
	Length() int
	ToMap() map[string]string
}

func UnwrapEnvelopeHeader

func UnwrapEnvelopeHeader(message interface{}) ReadonlyMessageHeader

type ReceiveFunc

type ReceiveFunc func(c Context)

The ReceiveFunc type is an adapter to allow the use of ordinary functions as actors to process messages

func (ReceiveFunc) Receive

func (f ReceiveFunc) Receive(c Context)

Receive calls f(c)

type ReceiveTimeout

type ReceiveTimeout struct{}

A ReceiveTimeout message is sent to an actor after the Context.ReceiveTimeout duration has expired

type ReceiverContext

type ReceiverContext interface {
	// contains filtered or unexported methods
}

type ReceiverFunc

type ReceiverFunc func(c ReceiverContext, envelope *MessageEnvelope)

type ReceiverMiddleware

type ReceiverMiddleware func(next ReceiverFunc) ReceiverFunc

type Restart

type Restart struct{}

Restart is message sent by the actor system to control the lifecycle of an actor

func (*Restart) SystemMessage

func (*Restart) SystemMessage()

type RestartStatistics

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

RestartStatistics keeps track of how many times an actor have restarted and when

func NewRestartStatistics

func NewRestartStatistics() *RestartStatistics

NewRestartStatistics construct a RestartStatistics

func (*RestartStatistics) Fail

func (rs *RestartStatistics) Fail()

Fail increases the associated actors' failure count

func (*RestartStatistics) FailureCount

func (rs *RestartStatistics) FailureCount() int

FailureCount returns failure count

func (*RestartStatistics) NumberOfFailures

func (rs *RestartStatistics) NumberOfFailures(withinDuration time.Duration) int

NumberOfFailures returns number of failures within a given duration

func (*RestartStatistics) Reset

func (rs *RestartStatistics) Reset()

Reset the associated actors' failure count

type Restarting

type Restarting struct{}

A Restarting message is sent to an actor when the actor is being restarted by the system due to a failure

func (*Restarting) AutoReceiveMessage

func (*Restarting) AutoReceiveMessage()

type ResumeMailbox

type ResumeMailbox struct{}

ResumeMailbox is message sent by the actor system to resume mailbox processing.

This will not be forwarded to the Receive method

func (*ResumeMailbox) MailboxMessage

func (*ResumeMailbox) MailboxMessage()

type RootContext

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

func NewRootContext

func NewRootContext(actorSystem *ActorSystem, header map[string]string, middleware ...SenderMiddleware) *RootContext

func (*RootContext) Actor

func (rc *RootContext) Actor() Actor

func (*RootContext) ActorSystem

func (rc *RootContext) ActorSystem() *ActorSystem

func (RootContext) Copy

func (rc RootContext) Copy() *RootContext

func (*RootContext) Logger added in v0.3.0

func (rc *RootContext) Logger() *slog.Logger

func (*RootContext) Message

func (rc *RootContext) Message() interface{}

func (*RootContext) MessageHeader

func (rc *RootContext) MessageHeader() ReadonlyMessageHeader

func (*RootContext) Parent

func (rc *RootContext) Parent() *PID

func (*RootContext) Poison

func (rc *RootContext) Poison(pid *PID)

Poison will tell actor to stop after processing current user messages in mailbox.

func (*RootContext) PoisonFuture

func (rc *RootContext) PoisonFuture(pid *PID) *Future

PoisonFuture will tell actor to stop after processing current user messages in mailbox, and return its future.

func (*RootContext) Request

func (rc *RootContext) Request(pid *PID, message interface{})

func (*RootContext) RequestFuture

func (rc *RootContext) RequestFuture(pid *PID, message interface{}, timeout time.Duration) *Future

RequestFuture sends a message to a given PID and returns a Future.

func (*RootContext) RequestWithCustomSender

func (rc *RootContext) RequestWithCustomSender(pid *PID, message interface{}, sender *PID)

func (*RootContext) Self

func (rc *RootContext) Self() *PID

func (*RootContext) Send

func (rc *RootContext) Send(pid *PID, message interface{})

func (*RootContext) Sender

func (rc *RootContext) Sender() *PID

func (*RootContext) Spawn

func (rc *RootContext) Spawn(props *Props) *PID

Spawn starts a new actor based on props and named with a unique id.

Example

Spawn creates instances of actors, similar to 'new' or 'make' but for actors.

var wg sync.WaitGroup
wg.Add(1)

// create root context
// define the actor props.
// props define the creation process of an actor
props := actor.PropsFromFunc(func(ctx actor.Context) {
	// check if the message is a *actor.Started message
	// this is the first message all actors get
	// actor.Started is received async and can be used
	// to initialize your actors initial state
	if _, ok := ctx.Message().(*actor.Started); ok {
		fmt.Println("hello world")
		wg.Done()
	}
})

// spawn the actor based on the props
system.Root.Spawn(props)
wg.Wait()
Output:

hello world

func (*RootContext) SpawnNamed

func (rc *RootContext) SpawnNamed(props *Props, name string) (*PID, error)

SpawnNamed starts a new actor based on props and named using the specified name

ErrNameExists will be returned if id already exists

Please do not use name sharing same pattern with system actors, for example "YourPrefix$1", "Remote$1", "future$1".

Example

Spawn creates instances of actors, similar to 'new' or 'make' but for actors.

var wg sync.WaitGroup
wg.Add(1)

// create root context
context := system.Root

// define the actor props.
// props define the creation process of an actor
props := actor.PropsFromFunc(func(ctx actor.Context) {
	// check if the message is a *actor.Started message
	// this is the first message all actors get
	// actor.Started is received async and can be used
	// to initialize your actors initial state
	if _, ok := ctx.Message().(*actor.Started); ok {
		fmt.Println("hello world")
		wg.Done()
	}
})

// spawn the actor based on the props
_, err := context.SpawnNamed(props, "my-actor")
if err != nil {
	log.Fatal("The actor name is already in use")
}
wg.Wait()
Output:

hello world

func (*RootContext) SpawnPrefix

func (rc *RootContext) SpawnPrefix(props *Props, prefix string) *PID

SpawnPrefix starts a new actor based on props and named using a prefix followed by a unique id.

func (*RootContext) Stop

func (rc *RootContext) Stop(pid *PID)

Stop will stop actor immediately regardless of existing user messages in mailbox.

func (*RootContext) StopFuture

func (rc *RootContext) StopFuture(pid *PID) *Future

StopFuture will stop actor immediately regardless of existing user messages in mailbox, and return its future.

func (*RootContext) WithGuardian

func (rc *RootContext) WithGuardian(guardian SupervisorStrategy) *RootContext

func (*RootContext) WithHeaders

func (rc *RootContext) WithHeaders(headers map[string]string) *RootContext

func (*RootContext) WithSenderMiddleware

func (rc *RootContext) WithSenderMiddleware(middleware ...SenderMiddleware) *RootContext

func (*RootContext) WithSpawnMiddleware

func (rc *RootContext) WithSpawnMiddleware(middleware ...SpawnMiddleware) *RootContext

type SenderContext

type SenderContext interface {
	// contains filtered or unexported methods
}

type SenderFunc

type SenderFunc func(c SenderContext, target *PID, envelope *MessageEnvelope)

type SenderMiddleware

type SenderMiddleware func(next SenderFunc) SenderFunc

type ShouldThrottle

type ShouldThrottle func() Valve

func NewThrottle

func NewThrottle(maxEventsInPeriod int32, period time.Duration, throttledCallBack func(int32)) ShouldThrottle

NewThrottle This has no guarantees that the throttle opens exactly after the period, since it is reset asynchronously Throughput has been prioritized over exact re-opening throttledCallBack, This will be called with the number of events what was throttled after the period

func NewThrottleWithLogger added in v0.3.0

func NewThrottleWithLogger(logger *slog.Logger, maxEventsInPeriod int32, period time.Duration, throttledCallBack func(*slog.Logger, int32)) ShouldThrottle

type SliceMap

type SliceMap struct {
	LocalPIDs []cmap.ConcurrentMap
}

func (*SliceMap) GetBucket

func (s *SliceMap) GetBucket(key string) cmap.ConcurrentMap

type SpawnFunc

type SpawnFunc func(actorSystem *ActorSystem, id string, props *Props, parentContext SpawnerContext) (*PID, error)
var DefaultSpawner SpawnFunc = defaultSpawner

DefaultSpawner this is a hacking way to allow Proto.Router access default spawner func.

type SpawnMiddleware

type SpawnMiddleware func(next SpawnFunc) SpawnFunc

type SpawnerContext

type SpawnerContext interface {
	// contains filtered or unexported methods
}

type Started

type Started struct{}

A Started message is sent to an actor once it has been started and ready to begin receiving messages.

func (*Started) SystemMessage

func (*Started) SystemMessage()

type Stop

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

func (*Stop) Descriptor deprecated

func (*Stop) Descriptor() ([]byte, []int)

Deprecated: Use Stop.ProtoReflect.Descriptor instead.

func (*Stop) ProtoMessage

func (*Stop) ProtoMessage()

func (*Stop) ProtoReflect

func (x *Stop) ProtoReflect() protoreflect.Message

func (*Stop) Reset

func (x *Stop) Reset()

func (*Stop) String

func (x *Stop) String() string

func (*Stop) SystemMessage

func (*Stop) SystemMessage()

type Stopped

type Stopped struct{}

A Stopped message is sent to the actor once it has been stopped. A stopped actor will receive no further messages

func (*Stopped) AutoReceiveMessage

func (*Stopped) AutoReceiveMessage()

type Stopping

type Stopping struct{}

A Stopping message is sent to an actor prior to the actor being stopped

func (*Stopping) AutoReceiveMessage

func (*Stopping) AutoReceiveMessage()

type Supervisor

type Supervisor interface {
	Children() []*PID
	EscalateFailure(reason interface{}, message interface{})
	RestartChildren(pids ...*PID)
	StopChildren(pids ...*PID)
	ResumeChildren(pids ...*PID)
}

Supervisor is an interface that is used by the SupervisorStrategy to manage child actor lifecycle

type SupervisorEvent

type SupervisorEvent struct {
	Child     *PID
	Reason    interface{}
	Directive Directive
}

SupervisorEvent is sent on the EventStream when a supervisor have applied a directive to a failing child actor

type SupervisorStrategy

type SupervisorStrategy interface {
	HandleFailure(actorSystem *ActorSystem, supervisor Supervisor, child *PID, rs *RestartStatistics, reason interface{}, message interface{})
}

SupervisorStrategy is an interface that decides how to handle failing child actors

func DefaultSupervisorStrategy

func DefaultSupervisorStrategy() SupervisorStrategy

func NewAllForOneStrategy

func NewAllForOneStrategy(maxNrOfRetries int, withinDuration time.Duration, decider DeciderFunc) SupervisorStrategy

NewAllForOneStrategy returns a new SupervisorStrategy which applies the given fault Directive from the decider to the failing child and all its children.

This strategy is appropriate when the children have a strong dependency, such that and any single one failing would place them all into a potentially invalid state.

func NewExponentialBackoffStrategy

func NewExponentialBackoffStrategy(backoffWindow time.Duration, initialBackoff time.Duration) SupervisorStrategy

NewExponentialBackoffStrategy creates a new Supervisor strategy that restarts a faulting child using an exponential back off algorithm:

delay =

func NewOneForOneStrategy

func NewOneForOneStrategy(maxNrOfRetries int, withinDuration time.Duration, decider DeciderFunc) SupervisorStrategy

NewOneForOneStrategy returns a new Supervisor strategy which applies the fault Directive from the decider to the failing child process.

This strategy is applicable if it is safe to handle a single child in isolation from its peers or dependents

func NewRestartingStrategy

func NewRestartingStrategy() SupervisorStrategy

func RestartingSupervisorStrategy

func RestartingSupervisorStrategy() SupervisorStrategy

type SuspendMailbox

type SuspendMailbox struct{}

SuspendMailbox is message sent by the actor system to suspend mailbox processing.

This will not be forwarded to the Receive method

func (*SuspendMailbox) MailboxMessage

func (*SuspendMailbox) MailboxMessage()

type SystemMessage

type SystemMessage interface {
	SystemMessage()
}

A SystemMessage message is reserved for specific lifecycle messages used by the actor system

type Terminated

type Terminated struct {
	Who *PID             `protobuf:"bytes,1,opt,name=who,proto3" json:"who,omitempty"`
	Why TerminatedReason `protobuf:"varint,2,opt,name=Why,proto3,enum=actor.TerminatedReason" json:"Why,omitempty"`
	// contains filtered or unexported fields
}

func (*Terminated) Descriptor deprecated

func (*Terminated) Descriptor() ([]byte, []int)

Deprecated: Use Terminated.ProtoReflect.Descriptor instead.

func (*Terminated) GetWho

func (x *Terminated) GetWho() *PID

func (*Terminated) GetWhy

func (x *Terminated) GetWhy() TerminatedReason

func (*Terminated) ProtoMessage

func (*Terminated) ProtoMessage()

func (*Terminated) ProtoReflect

func (x *Terminated) ProtoReflect() protoreflect.Message

func (*Terminated) Reset

func (x *Terminated) Reset()

func (*Terminated) String

func (x *Terminated) String() string

func (*Terminated) SystemMessage

func (*Terminated) SystemMessage()

type TerminatedReason

type TerminatedReason int32
const (
	TerminatedReason_Stopped           TerminatedReason = 0
	TerminatedReason_AddressTerminated TerminatedReason = 1
	TerminatedReason_NotFound          TerminatedReason = 2
)

func (TerminatedReason) Descriptor

func (TerminatedReason) Enum

func (TerminatedReason) EnumDescriptor deprecated

func (TerminatedReason) EnumDescriptor() ([]byte, []int)

Deprecated: Use TerminatedReason.Descriptor instead.

func (TerminatedReason) Number

func (TerminatedReason) String

func (x TerminatedReason) String() string

func (TerminatedReason) Type

type Touch

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

func (*Touch) Descriptor deprecated

func (*Touch) Descriptor() ([]byte, []int)

Deprecated: Use Touch.ProtoReflect.Descriptor instead.

func (*Touch) GetAutoResponse

func (*Touch) GetAutoResponse(ctx Context) interface{}

func (*Touch) ProtoMessage

func (*Touch) ProtoMessage()

func (*Touch) ProtoReflect

func (x *Touch) ProtoReflect() protoreflect.Message

func (*Touch) Reset

func (x *Touch) Reset()

func (*Touch) String

func (x *Touch) String() string

type Touched

type Touched struct {
	Who *PID `protobuf:"bytes,1,opt,name=who,proto3" json:"who,omitempty"`
	// contains filtered or unexported fields
}

func (*Touched) Descriptor deprecated

func (*Touched) Descriptor() ([]byte, []int)

Deprecated: Use Touched.ProtoReflect.Descriptor instead.

func (*Touched) GetWho

func (x *Touched) GetWho() *PID

func (*Touched) ProtoMessage

func (*Touched) ProtoMessage()

func (*Touched) ProtoReflect

func (x *Touched) ProtoReflect() protoreflect.Message

func (*Touched) Reset

func (x *Touched) Reset()

func (*Touched) String

func (x *Touched) String() string

type Unwatch

type Unwatch struct {
	Watcher *PID `protobuf:"bytes,1,opt,name=Watcher,proto3" json:"Watcher,omitempty"`
	// contains filtered or unexported fields
}

func (*Unwatch) Descriptor deprecated

func (*Unwatch) Descriptor() ([]byte, []int)

Deprecated: Use Unwatch.ProtoReflect.Descriptor instead.

func (*Unwatch) GetWatcher

func (x *Unwatch) GetWatcher() *PID

func (*Unwatch) ProtoMessage

func (*Unwatch) ProtoMessage()

func (*Unwatch) ProtoReflect

func (x *Unwatch) ProtoReflect() protoreflect.Message

func (*Unwatch) Reset

func (x *Unwatch) Reset()

func (*Unwatch) String

func (x *Unwatch) String() string

func (*Unwatch) SystemMessage

func (*Unwatch) SystemMessage()

type Valve

type Valve int32
const (
	Open Valve = iota
	Closing
	Closed
)

type Watch

type Watch struct {
	Watcher *PID `protobuf:"bytes,1,opt,name=Watcher,proto3" json:"Watcher,omitempty"`
	// contains filtered or unexported fields
}

system messages

func (*Watch) Descriptor deprecated

func (*Watch) Descriptor() ([]byte, []int)

Deprecated: Use Watch.ProtoReflect.Descriptor instead.

func (*Watch) GetWatcher

func (x *Watch) GetWatcher() *PID

func (*Watch) ProtoMessage

func (*Watch) ProtoMessage()

func (*Watch) ProtoReflect

func (x *Watch) ProtoReflect() protoreflect.Message

func (*Watch) Reset

func (x *Watch) Reset()

func (*Watch) String

func (x *Watch) String() string

func (*Watch) SystemMessage

func (*Watch) SystemMessage()

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL