Merge pull request #946 from asynkron/more-readmes

add example readmes

_examples/actor-mailbox-middleware/readme.md

@@ -0,0 +1,33 @@
+## AI Generated Content. Please report issues
+
+# Go Example: Custom Mailbox Logging with Proto.Actor
+
+## Introduction
+This Go example demonstrates how to implement custom mailbox logging in the Proto.Actor framework. It shows how to track mailbox events such as message posting, receiving, and when the mailbox becomes empty.
+
+## Description
+The program sets up an actor system with a custom mailbox logger, `mailboxLogger`. This logger logs different events related to the actor's mailbox, such as when a message is posted or received, and when the mailbox is empty. This is useful for debugging and monitoring the behavior of actors in more complex systems.
+
+## Setup
+Ensure the following are installed to run this example:
+- Go programming environment
+- Proto.Actor for Go
+
+Install Proto.Actor with:
+```bash
+go get -u github.com/asynkron/protoactor-go
+```
+
+## Running the Example
+
+```bash
+go run main.go
+```
+
+## Additional Notes
+- The `mailboxLogger` struct implements methods to log different mailbox events.
+- Custom mailbox logging provides insights into the message processing lifecycle of an actor.
+- The example illustrates an effective way to monitor and debug actor behavior in the Proto.Actor framework.
+- This example is beneficial for developers looking to implement advanced monitoring and logging mechanisms in their Go applications using Proto.Actor.
+
+This example offers a clear demonstration of custom mailbox logging in a Go application using the Proto.Actor framework.

_examples/actor-messagebatch/readme.md

@@ -0,0 +1,33 @@
+## AI Generated Content. Please report issues
+
+# Go Example: Message Batching with Proto.Actor
+
+## Introduction
+This Go example demonstrates the concept of message batching in the Proto.Actor framework. It shows how to group multiple messages into a single batch and process them individually.
+
+## Description
+The program creates an actor system and defines a `myMessageBatch` struct, which groups multiple messages together. These messages are then sent as a single batch to the actor but processed as individual messages. This technique is particularly useful in scenarios like cluster PubSub, where batching can improve performance and efficiency.
+
+## Setup
+To run this example, ensure you have:
+- Go programming environment
+- Proto.Actor for Go
+
+Install Proto.Actor with:
+```bash
+go get -u github.com/asynkron/protoactor-go
+```
+
+## Running the Example
+
+```bash
+go run main.go
+```
+
+## Additional Notes
+- The example demonstrates how to create and send a batch of messages using the `myMessageBatch` struct.
+- The actor processes each message in the batch individually, showcasing effective message batching.
+- This approach is beneficial for scenarios requiring efficient message processing and delivery.
+- The example is ideal for developers looking to implement message batching in their Go applications using Proto.Actor.
+
+This example provides a clear understanding of message batching in a Go application using the Proto.Actor framework.

_examples/actor-receive-middleware/readme.md

@@ -0,0 +1,33 @@
+## AI Generated Content. Please report issues
+
+# Go Example: Middleware Usage with Proto.Actor
+
+## Introduction
+This Go example demonstrates the use of middleware in the Proto.Actor framework. It illustrates how to enhance actor functionality with additional layers of processing.
+
+## Description
+The example sets up a basic actor system where the `receive` function handles a `hello` message. Middleware, specifically the logger middleware, is added to the actor properties to log incoming messages. This example is an excellent demonstration of using middleware to augment actor behavior in Proto.Actor.
+
+## Setup
+To run this example, make sure you have:
+- Go programming environment
+- Proto.Actor for Go
+
+Install Proto.Actor with:
+```bash
+go get -u github.com/asynkron/protoactor-go
+```
+
+## Running the Example
+
+```bash
+go run main.go
+```
+
+## Additional Notes
+- The `receive` function acts as the message handler for the actor.
+- Middleware is added to the actor properties using `actor.WithReceiverMiddleware`.
+- The logger middleware logs each message received by the actor.
+- This example is ideal for those who want to understand how to implement and use middleware in actor-based systems using Proto.Actor.
+
+This example provides a clear demonstration of incorporating middleware into an actor in a Go application using the Proto.Actor framework.

_examples/actor-receive-timeout/readme.md

@@ -0,0 +1,33 @@
+## AI Generated Content. Please report issues
+
+# Go Example: Receive Timeout with Proto.Actor
+
+## Introduction
+This Go example showcases the use of receive timeout in the Proto.Actor framework. It demonstrates how to handle timeouts and messages that do not influence the receive timeout.
+
+## Description
+The program sets up an actor that uses `SetReceiveTimeout` to trigger actions if no messages are received within a specified duration. It also introduces a custom message type, `NoInfluence`, that does not reset the receive timeout. This example is useful for understanding timeout handling in actor-based systems.
+
+## Setup
+Ensure the following are installed to run this example:
+- Go programming environment
+- Proto.Actor for Go
+
+Install Proto.Actor with:
+```bash
+go get -u github.com/asynkron/protoactor-go
+```
+
+## Running the Example
+
+```bash
+go run main.go
+```
+
+## Additional Notes
+- The actor sets a receive timeout and logs a message each time the timeout is triggered.
+- The `NoInfluence` message type is designed to be processed without resetting the timeout.
+- The example illustrates how to cancel the receive timeout with a specific message.
+- This example is ideal for developers looking to implement timeout mechanisms in their actor-based applications using Proto.Actor.
+
+This example provides insight into managing receive timeouts and non-influential messages in a Go application with the Proto.Actor framework.

_examples/actor-request-response/readme.md

@@ -0,0 +1,33 @@
+## AI Generated Content. Please report issues
+
+# Go Example: RequestFuture with Proto.Actor
+
+## Introduction
+This Go example demonstrates the use of `RequestFuture` in the Proto.Actor framework. It showcases how to handle asynchronous requests and responses between actors.
+
+## Description
+The program sets up an actor system where an actor receives a `Hello` message and responds to it. The `RequestFuture` method is used to send a message to the actor and wait for the response. This method is crucial as it creates a temporary actor to handle the response, allowing the main func to wait for the response to arrive or time out.
+
+## Setup
+Ensure the following are installed to run this example:
+- Go programming environment
+- Proto.Actor for Go
+
+Install Proto.Actor with:
+```bash
+go get -u github.com/asynkron/protoactor-go
+```
+
+## Running the Example
+
+```bash
+go run main.go
+```
+
+## Additional Notes
+- The `Receive` function processes the `Hello` message and sends a response.
+- `RequestFuture` is used for sending the message and waiting for the response. It creates a temporary actor for this purpose.
+- The example highlights the use of asynchronous message handling and response waiting in actor-based systems.
+- This example is beneficial for developers looking to implement asynchronous request-response patterns in their Go applications using Proto.Actor.
+
+This example provides a clear understanding of using `RequestFuture` for asynchronous communication in a Go application with the Proto.Actor framework.

_examples/actor-setbehavior/README.MD

@@ -1,5 +1,31 @@
-# Switchable Behaviors
+## AI Generated Content. Please report issues
+
+# Go Example: Behavior Switching in Actors with Proto.Actor
+
+## Introduction
+This Go example demonstrates behavior switching in actors using the Proto.Actor framework. It shows how an actor can change its behavior dynamically in response to messages.
+
+## Description
+The program defines a `SetBehaviorActor` with two behaviors: `One` and `Other`. Initially, the actor responds to a `Hello` message with the `One` behavior. Upon receiving a `Hello` message, it switches to the `Other` behavior for subsequent messages. This example illustrates the dynamic behavior capabilities of actors in Proto.Actor, allowing them to adapt their responses based on their state or received messages.
+
+## Setup
+Ensure the following are installed to run this example:
+- Go programming environment
+- Proto.Actor for Go
+
+Install Proto.Actor with:
+```bash
+go get -u github.com/asynkron/protoactor-go
+```
 
+## Running the Example
+
+```bash
+go run main.go
+```
+
+
+# Switchable Behaviors
 Actors have the power to switch their behaviors at any point in time. This is usually referred as *becoming something*,
 as in *the actor becomes busy* or *the actor becomes connected*.
 
@@ -22,47 +48,11 @@ The API to change behaviors is available to the actor instance is very simple:
   ones;
 * `UnbecomeStacked` - Reverts to the previous message handler from the stack (only works with PushBehavior);
 
-```go
-...
-
-type Hello struct{ Who string }
-type SetBehaviorActor struct {
-	behavior actor.Behavior
-}
-
-func (state *SetBehaviorActor) Receive(context actor.Context) {
-	state.behavior.Receive(context)
-}
-
-func (state *SetBehaviorActor) One(context actor.Context) {
-	switch msg := context.Message().(type) {
-	case Hello:
-		fmt.Printf("Hello %v\n", msg.Who)
-		state.behavior.Become(state.Other)
-	}
-}
-
-func (state *SetBehaviorActor) Other(context actor.Context) {
-	switch msg := context.Message().(type) {
-	case Hello:
-		fmt.Printf("%v, ey we are now handling messages in another behavior", msg.Who)
-	}
-}
-
-func NewSetBehaviorActor() actor.Actor {
-	act := &SetBehaviorActor{
-		behavior: actor.NewBehavior(),
-	}
-	act.behavior.Become(act.One)
-	return act
-}
-
-func main() {
-	rootContext := actor.EmptyRootContext
-	props := actor.PropsFromProducer(NewSetBehaviorActor)
-	pid, _ := rootContext.Spawn(props)
-	rootContext.Send(pid, Hello{Who: "Roger"})
-	rootContext.Send(pid, Hello{Who: "Roger"})
-	console.ReadLine()
-}
-```
+
+## Additional Notes
+- The `SetBehaviorActor` uses the `Behavior` type to switch between `One` and `Other`.
+- The actor starts with the `One` behavior and switches to `Other` after processing the first `Hello` message.
+- This technique is useful for creating flexible and stateful actors that can change their behavior during runtime.
+- The example is beneficial for developers looking to implement dynamic actor behaviors in their Go applications using Proto.Actor.
+
+This example provides a comprehensive demonstration of behavior switching in actors within a Go application using the Proto.Actor framework.

_examples/router-demo/readme.md

@@ -0,0 +1,33 @@
+## AI Generated Content. Please report issues
+
+# Go Example: Routing Strategies with Proto.Actor
+
+## Introduction
+This Go example explores various routing strategies in the Proto.Actor framework, including Round Robin, Random, ConsistentHash, and BroadcastPool routing.
+
+## Description
+The program sets up an actor system and demonstrates four different routing strategies: Round Robin, Random, ConsistentHash, and BroadcastPool. Each strategy is used to distribute messages among a pool of actors. The `myMessage` struct, which includes a custom hash function, is used to demonstrate message routing behavior.
+
+## Setup
+Ensure the following are installed to run this example:
+- Go programming environment
+- Proto.Actor for Go
+
+Install Proto.Actor with:
+```bash
+go get -u github.com/asynkron/protoactor-go
+```
+
+## Running the Example
+
+```bash
+go run main.go
+```
+
+## Additional Notes
+- The example illustrates how messages are processed differently under each routing strategy.
+- Round Robin distributes messages evenly among actors, Random chooses actors randomly, ConsistentHash routes based on message hash, and BroadcastPool sends messages to all actors in the pool.
+- Understanding these routing strategies is crucial for building scalable and efficient actor-based systems.
+- This example is beneficial for developers looking to implement advanced message routing mechanisms in their Go applications using Proto.Actor.
+
+This example provides a comprehensive overview of implementing various routing strategies in a Go application using the Proto.Actor framework.

_examples/router-limitconcurrency/readme.md

@@ -0,0 +1,33 @@
+## AI Generated Content. Please report issues
+
+# Go Example: Concurrency Control with Routers in Proto.Actor
+
+## Introduction
+This Go example highlights concurrency control using routers in the Proto.Actor framework. It illustrates how to limit the concurrency level when processing messages in an actor system.
+
+## Description
+The program creates an actor system with a Round Robin router to distribute work items among a pool of actors. The maximum concurrency level is set to `maxConcurrency`. Each actor processes `workItem` messages, ensuring that the concurrency level does not exceed the defined limit. This example is key for understanding concurrency control in actor-based systems.
+
+## Setup
+To run this example, ensure you have:
+- Go programming environment
+- Proto.Actor for Go
+
+Install Proto.Actor with:
+```bash
+go get -u github.com/asynkron/protoactor-go
+```
+
+## Running the Example
+
+```bash
+go run main.go
+```
+
+## Additional Notes
+- The example uses a Round Robin router to distribute messages evenly among actors.
+- `doWork` is the function each actor uses to process messages, respecting the `maxConcurrency` limit.
+- This approach is beneficial for managing workload and preventing overloading actors.
+- The example is ideal for developers looking to implement controlled concurrency in their Go applications using Proto.Actor.
+
+This example provides an insightful demonstration of managing concurrency with routers in a Go application using the Proto.Actor framework.

_examples/scheduler/readme.md

@@ -0,0 +1,32 @@
+## AI Generated Content. Please report issues
+
+# Go Example: Message Scheduling with Proto.Actor
+
+## Introduction
+This Go example showcases message scheduling in the Proto.Actor framework. It demonstrates various ways to schedule and cancel message delivery to actors.
+
+## Description
+The program sets up an actor system and uses the scheduler to send and request messages at specified intervals. It also demonstrates the cancellation of scheduled messages. The example uses an array of `HelloMessages` in different languages to illustrate message scheduling and processing.
+
+## Setup
+To run this example, ensure you have:
+- Go programming environment
+- Proto.Actor for Go
+
+Install Proto.Actor with:
+```bash
+go get -u github.com/asynkron/protoactor-go
+```
+
+## Running the Example
+
+```bash
+go run main.go
+```
+
+## Additional Notes
+- The example uses the `scheduler` package for sending and requesting messages at regular intervals.
+- The ability to cancel scheduled messages is also demonstrated, which is useful for dynamic scheduling scenarios.
+- This example is ideal for developers looking to implement time-based message scheduling in their Go applications using Proto.Actor.
+
+This example provides a comprehensive demonstration of using a message scheduler in a Go application with the Proto.Actor framework.