README
¶
go-actor
This is far far incomplete actor implementation in golang. This is only for my golang learning.
go-actor now supports:
- become/unbecome
- actor hierarchy (actor has children. parent termination propagates to children, but supervisor is comming soon.)
- monitor (monitor receives its target actor's termination.)
- forwarding actor (this actor forwards all messages other actors.)
GoDoc
GoDoc is here
How to Try
If you tried to run this, please just hit.
$ cd example
$ go run ping-pong/main.go
==========================================================
== Ping-Pong example.
/ping-pong/pinger sends : Ping
/ping-pong/ponger received: Ping
/ping-pong/ponger sends : Pong
/ping-pong/pinger receives: Pong.
Ping-Pong finished.
==========================================================
$ go run become-unbecome/main.go
==========================================================
== Become/UnBecome example
== An actor's behavior changes:
== echo --(become)-->echo in upper case --(unbecome)--> echo.
/become-unbecome/0: this should be echoed.. become echoInUpper.
/become-unbecome/0: THIS SHOULD BE ECHOED IN UPPER CASE.. unbecome
/become-unbecome/0: become terminate!!. become terminate
==========================================================
$ go run forward/main.go
==========================================================
== Forwarding actor example
== It is sometimes useful that an actor which just forward
== messages other actors. In this example,
== "forward" actor forwards to "echo1" and "echo2"
Sent [hello] to "forward"
/forwad/echo1 : [hello]
/forwad/echo2 : [hello]
==========================================================
$ go run monitor/main.go
==========================================================
== Monitor example
== Monitor can detect actor's termination.
== In this example, spawn "traget" actor and it is monitored
== by "monitor"
/monitor-system/target receive: [hello]
/monitor-system/monitor detects: /monitor-system/target terminated
==========================================================
$ go run parent-child/main.go
==========================================================
== Actor hierarchy example
== Actor has children. Children's termination is propagated
== to parent.
child receive: [hello]
actorA receive: [hello]
terminate child. you will see parent's termination too.
/parent-child/monitor detects: /parent-child/actorA/child terminated
/parent-child/monitor detects: /parent-child/actorA terminated
==========================================================
Documentation
¶
Overview ¶
Actor library in go, which is inspired both erlang and akka framework.
Index ¶
- type Actor
- func (actor *Actor) ActorPath() string
- func (actor *Actor) CanonicalName() string
- func (actor *Actor) Demonitor(mon *Actor)
- func (actor *Actor) IsRunning() bool
- func (actor *Actor) Kill()
- func (actor *Actor) Monitor(mon *Actor)
- func (actor *Actor) Send(msg Message)
- func (actor *Actor) Spawn(receive Receive) *Actor
- func (actor *Actor) SpawnForwardActor(name string, actors ...*Actor) *ForwardingActor
- func (actor *Actor) SpawnWithName(name string, receive Receive) *Actor
- func (actor *Actor) Terminate()
- type ActorContext
- type ActorSystem
- func (system *ActorSystem) GracefulShutdown()
- func (system *ActorSystem) GracefulShutdownIn(duration time.Duration)
- func (system *ActorSystem) Shutdown()
- func (system *ActorSystem) ShutdownIn(duration time.Duration)
- func (system *ActorSystem) Spawn(receive Receive) *Actor
- func (system *ActorSystem) SpawnForwardActor(name string, actors ...*Actor) *ForwardingActor
- func (system *ActorSystem) SpawnWithName(name string, receive Receive) *Actor
- func (system *ActorSystem) WaitForAllActorsStopped()
- type Down
- type ForwardingActor
- type Message
- type PoisonPill
- type Receive
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Actor ¶
type Actor struct {
Name string
System *ActorSystem
// contains filtered or unexported fields
}
Actor.
An actor has its name and belongs to exactly one actor system.
func (*Actor) ActorPath ¶
ActorPath returns an actor path from the actor system root. An actor path is deliminated by '/' For example,
actorSystem := actor.NewActorSystem("systemX")
foo := actorSystem.Spawn("foo", ..Receive function..)
bar := foo.Spawn("bar", ..Receive function..)
foo.ActorPath() // ===> /foo
bar.ActorPath() // ==> "/foo/bar"
func (*Actor) CanonicalName ¶
CanonicalName returns a full path name of the actor which indicates actor hierarchy from the actor system to which it belongs.
Canonical name forms '<actor system name>:<actor path>' For example,
actorSystem := actor.NewActorSystem("systemX")
foo := actorSystem.Spawn("foo", ..Receive function..)
bar := foo.Spawn("bar", ..Receive function..)
bar.CanonicalName() // ==> "systemX:/foo/bar"
func (*Actor) Demonitor ¶
Demonitor detaches a given monitor asynchronously.
Detached monitors will not be notified its stop (terminate and kill) event anymore.
func (*Actor) Kill ¶
func (actor *Actor) Kill()
Kill sends "Kill" signal to the actor asynchronously.
If the actor receives the signal, the actor stops immediately. However, the timing of receipt of the signal depends on goroutine scheduler. Therefore, the number of messages will be processed before its stop is undefined.
func (*Actor) Monitor ¶
Monitor attaches another actor(mon) as its monitor asynchronously.
Attached monitors will be notified its stop (terminate and kill) event with actor.Down message.
func (*Actor) Send ¶
Send sends message to the actor asynchronously.
Please note that message should be wrapped in actor.Message. example:
actor.Send(Message{"hello"})
func (*Actor) Spawn ¶
Spawn creates and starts a child actor of the actor.
This takes Receive(an type alias for actor's message handler) returns the pointer to started actor. The difference between top level actors which are created directly from actor system is that created child actor will be terminated or killed when the actor is terminated or killed.
For example:
child := actor.Spawn(func(msg Message, context *ActorContext){
fmt.Println(msg)
})
actor.Terminates()
// then child will also terminate.
func (*Actor) SpawnForwardActor ¶
func (actor *Actor) SpawnForwardActor(name string, actors ...*Actor) *ForwardingActor
func (*Actor) SpawnWithName ¶
SpawnWithName is the same as Spawn except that you can name it.
func (*Actor) Terminate ¶
func (actor *Actor) Terminate()
Terminate sends "Terminate" signal to the actor asynchronously.
"Terminate" signal stop the actor in graceful manner. This method will just post "Message{PoisonPill{}}" to their mailbox. Thus, the actor will stop after processing remained messages in their mailbox.
type ActorContext ¶
type ActorContext struct {
Self *Actor
// contains filtered or unexported fields
}
Actor Context
Actor Context will be passed to actor's message handler with message received. This data enables message handler to access myself(it's useful when you want to send a message to myself), and to change its behavior.
func (*ActorContext) Become ¶
func (context *ActorContext) Become(behavior Receive, discardOld bool)
Become change actor's behavior.
ActorContext can be accessed in message handler. For example,
echo := func(msg Message, context *ActorContext){
fmt.Println(msg)
context.Become(echoInUpper)
}
echoInUpper := func(msg Message, context *ActorContext){
fmt.Println(msg)
context.Unbecome()
}
alternate := system.Spawn(echo)
"alternate" actor behaves echo and echoInUpper alternately. As you might notice, actor's behavior was stacked. So, you can unbecome to set back to the previous behavior.
If discardOld flag is true, this doesn't push a given behavior to its behavior stack but just overwrite the top of the stack.
func (*ActorContext) Unbecome ¶
func (context *ActorContext) Unbecome()
Unbecome set its behavior to the previous behavior in its behavior stack.
Please see Become for details.
func (*ActorContext) Unwatch ¶
func (context *ActorContext) Unwatch(actor *Actor)
Unwatch method detaches myself as monitor from given actor.
This is equivalent with
actor.Demonitor(context.Self)
func (*ActorContext) Watch ¶
func (context *ActorContext) Watch(actor *Actor)
Watch method attaches myself to given actor as monitor.
This is equivalent with
actor.Monitor(context.Self)
type ActorSystem ¶
type ActorSystem struct {
//TODO top level supervisor
Name string
// contains filtered or unexported fields
}
ActorSystem is an umbrella which maintains actor hierarchy.
func NewActorSystem ¶
func NewActorSystem(name string) *ActorSystem
NewActorSystem creates an ActorSystem instance.
func (*ActorSystem) GracefulShutdown ¶
func (system *ActorSystem) GracefulShutdown()
GracefulShutdown shutdowns the actor system in graceful manner.
It sends terminate signal(Terminate() method) to all the actors in the actor system.
func (*ActorSystem) GracefulShutdownIn ¶
func (system *ActorSystem) GracefulShutdownIn(duration time.Duration)
GracefulShutdownIn shutdowns the actor system in graceful manner after waiting a given duration.
It sends terminate signal(Terminate() method) to all the actors in the actor system after waiting for a given duration.
func (*ActorSystem) Shutdown ¶
func (system *ActorSystem) Shutdown()
Shutdown the actor system.
It sends kill signal(Kill() method) to all the actors in the actor system.
func (*ActorSystem) ShutdownIn ¶
func (system *ActorSystem) ShutdownIn(duration time.Duration)
ShutdownIn shutdowns the actor system after waiting a given duration.
It sends kill signal(Kill() method) to all the actors in the actor system after waiting for a given duration.
func (*ActorSystem) Spawn ¶
func (system *ActorSystem) Spawn(receive Receive) *Actor
Spawn creates and starts an actor in the actor system.
This takes Receive(type ailis for actor's message handler) returns the pointer to started actor.
For example, simple echo actor would be:
actorSystem.Spawn(func(msg Message, context *ActorContext){
fmt.Println(msg)
})
func (*ActorSystem) SpawnForwardActor ¶
func (system *ActorSystem) SpawnForwardActor(name string, actors ...*Actor) *ForwardingActor
func (*ActorSystem) SpawnWithName ¶
func (system *ActorSystem) SpawnWithName(name string, receive Receive) *Actor
SpawnWithName is the same as Spawn except that you can name it.
func (*ActorSystem) WaitForAllActorsStopped ¶
func (system *ActorSystem) WaitForAllActorsStopped()
WaitForAllActorsStopped waits for all the actors in the actor system stopped(terminated or killed).
type Down ¶
Down is a message sent to Monitor If monitored actor was terminates, monitor will receive
Message{Down{
Cause: "terminated",
Actor: <pointer to the actor>
}}
If monitored actor was killed, monitor will receive
Message{Down{
Cause: "killed",
Actor: <pointer to the actor>
}}
type ForwardingActor ¶
type ForwardingActor struct {
*Actor
// contains filtered or unexported fields
}
func (*ForwardingActor) Add ¶
func (actor *ForwardingActor) Add(recipient *Actor)
func (*ForwardingActor) Remove ¶
func (actor *ForwardingActor) Remove(recipient *Actor)
type Message ¶
type Message []interface{}
Message envelope for actor All message sent to actors should be wrapped with this envelope. example:
someActor.Send(actor.Message{"hello"})
type PoisonPill ¶
type PoisonPill struct{}
PoisonPill terminates actors. Sending the PoisonPill message is nearly equivalent with Terminate() method. example:
someActor.Send(actor.Message{actor.PoisonPill{}})
type Receive ¶
type Receive func(msg Message, context *ActorContext)
Receive is a type for Actor's message handler. It is just an alias for func(msg Message, context *ActorContext). For example, simple echo actor would be:
actorSystem.Spawn(func(msg Message, context *ActorContext){
fmt.Println(msg)
})
Source Files
Directories