document the event stream. (#101)

README.md

@@ -14,8 +14,9 @@ advertising brokers, trading engines, etc... It can handle **10 million messages
 The Actor Model is a computational model used to build highly concurrent and distributed systems. It was introduced by
 Carl Hewitt in 1973 as a way to handle complex systems in a more scalable and fault-tolerant manner.
 
-In the Actor Model, the basic building block is an actor, called receiver in Hollywood, which is an independent unit of
-computation that communicates with other actors by exchanging messages. Each actor has its own state and behavior, and
+In the Actor Model, the basic building block is an actor, sometimes referred to as a receiver in Hollywood, 
+which is an independent unit of computation that communicates with other actors by exchanging messages. 
+Each actor has its own state and behavior, and
 can only communicate with other actors by sending messages. This message-passing paradigm allows for a highly
 decentralized and fault-tolerant system, as actors can continue to operate independently even if other actors fail or
 become unavailable.
@@ -28,7 +29,7 @@ large number of concurrent users and complex interactions.
 
 ## Features
 
-- guaranteed message delivery on receiver failure (buffer mechanism)
+- guaranteed message delivery on actor failure (buffer mechanism)
 - fire & forget or request & response messaging, or both.
 - High performance dRPC as the transport layer
 - Optimized proto buffers without reflection
@@ -62,14 +63,14 @@ compiler.
 ## Hello world.
 
 Let's go through a Hello world message. The complete example is available in the 
-***[hello world](https://github.com/anthdm/hollywood/tree/master/examples/helloworld)*** folder. Let's start in main:
+[hello world](examples/helloworld) folder. Let's start in main:
 ```go
 	engine, err := actor.NewEngine()
 ```
 This creates a new engine. The engine is the core of Hollywood. It's responsible for spawning actors, sending messages
 and handling the lifecycle of actors. If Hollywood fails to create the engine it'll return an error. 
 
-Next we'll need to create an actor. These are some times referred to as Receivers after the interface they must 
+Next we'll need to create an actor. These are some times referred to as `Receivers` after the interface they must 
 implement. Let's create a new actor that will print a message when it receives a message. 
 
 ```go
@@ -132,11 +133,14 @@ Finally, lets send a message to the actor.
 This will send a message to the actor. Hollywood will route the message to the correct actor. The actor will then print
 a message to the console.
 
-The **[examples](https://github.com/anthdm/hollywood/tree/master/examples)** folder is the best place to learn and
+The [examples](https://github.com/anthdm/hollywood/tree/master/examples) folder is the best place to learn and
 explore Hollywood further.
 
 
-## Spawning receivers (actors) 
+## Spawning actors
+
+When you spawn an actor you'll need to provide a function that returns a new actor. As the actor is spawn there are a few
+tunable options you can provide.
 
 ### With default configuration
 ```go
@@ -168,10 +172,14 @@ e.SpawnFunc(func(c *actor.Context) {
 Actors can communicate with each other over the network with the Remote package. 
 This works the same as local actors but "over the wire". Hollywood supports serialization with protobuf.
 
-***[Remote actor examples](https://github.com/anthdm/hollywood/tree/master/examples/remote)***
+Look at the [Remote actor examples](examples/remote) and the [Chat client & Server](examples/chat) for more information.
 
 ## Eventstream
 
+In a production system thing will eventually go wrong. Actors will crash, machines will fail, messages will end up in
+the deadletter queue. You can build software that can handle these events in a graceful and predictable way by using
+the event stream.
+
 The Eventstream is a powerful abstraction that allows you to build flexible and pluggable systems without dependencies. 
 
 1. Subscribe any actor to a various list of system events
@@ -184,15 +192,21 @@ deliver a message to an actor it will send a `DeadLetterEvent` to the event stre
 Any event that fulfills the `actor.LogEvent` interface will be logged to the default logger, with the severity level, 
 message and the attributes of the event set by the `actor.LogEvent` `log()` method.
 
-You can find more in-depth information on how to use the Eventstream in your application in the Eventstream ***[examples](https://github.com/anthdm/hollywood/tree/master/examples/eventstream)***
-
 ### List of internal system events 
 * `ActorStartedEvent`, an actor has started
 * `ActorStoppedEvent`, an actor has stopped
 * `DeadLetterEvent`, a message was not delivered to an actor
 * `ActorRestartedEvent`, an actor has restarted after a crash/panic.
 
-Have a look at the `actor/events.go` file for more information on the events.
+### Eventstream example
+
+There is a [eventstream monitoring example](examples/eventstream-monitor) which shows you how to use the event stream.
+It features two actors, one is unstable and will crash every second. The other actor is subscribed to the event stream
+and maintains a few counters for different events such as crashes, etc. 
+
+The application will run for a few seconds and the poison the unstable actor. It'll then query the monitor with a 
+request. As actors are floating around inside the engine, this is the way you interact with them. main will then print
+the result of the query and the application will exit.
 
 ## Customizing the Engine
 

actor/deadletter_test.go

@@ -18,7 +18,7 @@ func TestDeadLetterCustom(t *testing.T) {
 	e.SpawnFunc(func(c *Context) {
 		switch c.Message().(type) {
 		case Initialized:
-			c.engine.BroadcastEvent(EventSub{c.pid})
+			c.engine.Subscribe(c.PID())
 		case DeadLetterEvent:
 			wg.Done()
 		}

actor/engine.go

@@ -242,12 +242,12 @@ func (e *Engine) SendLocal(pid *PID, msg any, sender *PID) {
 
 // Subscribe will subscribe the given PID to the event stream.
 func (e *Engine) Subscribe(pid *PID) {
-	e.Send(e.eventStream, EventSub{pid: pid})
+	e.Send(e.eventStream, eventSub{pid: pid})
 }
 
 // Unsubscribe will un subscribe the given PID from the event stream.
 func (e *Engine) Unsubscribe(pid *PID) {
-	e.Send(e.eventStream, EventUnsub{pid: pid})
+	e.Send(e.eventStream, eventUnsub{pid: pid})
 }
 
 func (e *Engine) isLocalMessage(pid *PID) bool {

actor/event_stream.go

@@ -5,13 +5,13 @@ import (
 	"log/slog"
 )
 
-// EventSub is the message that will be send to subscribe to the event stream.
-type EventSub struct {
+// eventSub is the message that will be send to subscribe to the event stream.
+type eventSub struct {
 	pid *PID
 }
 
 // EventUnSub is the message that will be send to unsubscribe from the event stream.
-type EventUnsub struct {
+type eventUnsub struct {
 	pid *PID
 }
 
@@ -28,13 +28,13 @@ func NewEventStream() Producer {
 }
 
 // Receive for the event stream. All system-wide events are sent here.
-// Some events are specially handled, such as EventSub, EventUnSub (for subscribing to events),
+// Some events are specially handled, such as eventSub, EventUnSub (for subscribing to events),
 // DeadletterSub, DeadletterUnSub, for subscribing to DeadLetterEvent
 func (e *EventStream) Receive(c *Context) {
 	switch msg := c.Message().(type) {
-	case EventSub:
+	case eventSub:
 		e.subs[msg.pid] = true
-	case EventUnsub:
+	case eventUnsub:
 		delete(e.subs, msg.pid)
 	default:
 		// check if we should log the event, if so, log it with the relevant level, message and attributes

examples/eventstream-monitor/main.go

@@ -0,0 +1,95 @@
+package main
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/anthdm/hollywood/actor"
+)
+
+type monitor struct {
+	crashes     int
+	starts      int
+	stops       int
+	deadletters int
+	msg         string
+}
+
+type query struct {
+	crashes     int
+	starts      int
+	stops       int
+	deadletters int
+}
+
+func newMonitor() actor.Receiver {
+	return &monitor{}
+
+}
+func (m *monitor) Receive(c *actor.Context) {
+	switch c.Message().(type) {
+	case actor.Initialized:
+		c.Engine().Subscribe(c.PID())
+	case actor.ActorRestartedEvent:
+		m.crashes++
+	case actor.ActorStartedEvent:
+		m.starts++
+	case actor.ActorStoppedEvent:
+		m.stops++
+	case actor.DeadLetterEvent:
+		m.deadletters++
+	case query:
+		c.Respond(query{
+			crashes:     m.crashes,
+			starts:      m.starts,
+			stops:       m.stops,
+			deadletters: m.deadletters,
+		})
+	}
+
+}
+
+type customMessage struct{}
+type unstableActor struct {
+	restarts  int
+	spawnTime time.Time
+}
+
+func newUnstableActor() actor.Receiver {
+	return &unstableActor{}
+}
+func (m *unstableActor) Receive(c *actor.Context) {
+	switch c.Message().(type) {
+	case actor.Initialized:
+		m.spawnTime = time.Now()
+	case actor.Started:
+		fmt.Println("actor started")
+	case customMessage:
+		if time.Since(m.spawnTime) > time.Second { // We should crash once per second.
+			panic("my time has come")
+		}
+
+	}
+}
+
+func main() {
+	e, _ := actor.NewEngine()
+	// Spawn a monitor actor and then an unstable actor.
+	monitor := e.Spawn(newMonitor, "monitor")
+	ua := e.Spawn(newUnstableActor, "unstable_actor", actor.WithMaxRestarts(10000))
+	repeater := e.SendRepeat(ua, customMessage{}, time.Millisecond*20)
+	time.Sleep(time.Second * 5)
+	repeater.Stop()
+	e.Poison(ua).Wait()
+	res, err := e.Request(monitor, query{}, time.Second).Result()
+	if err != nil {
+		fmt.Println("Query", err)
+	}
+	q := res.(query)
+	fmt.Printf("Observed %d crashes\n", q.crashes)
+	fmt.Printf("Observed %d starts\n", q.starts)
+	fmt.Printf("Observed %d stops\n", q.stops)
+	fmt.Printf("Observed %d deadletters\n", q.deadletters)
+	e.Poison(monitor).Wait() // the monitor will output stats on stop.
+	fmt.Println("done")
+}