Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Readmes #945

Merged
merged 3 commits into from
Nov 21, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions _examples/actor-autorespond/readme.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
## AI Generated Content. Please report issues

# Go Example with Proto.Actor Auto Response

## Introduction
This Go example demonstrates the use of the Auto Response feature in the Proto.Actor framework. It illustrates how an actor can automatically generate a response to a message.

## Description
In this example, we define `myAutoResponder` and `myAutoResponse` types to use the Auto Response feature of Proto.Actor. This feature allows an actor to automatically create a response message upon receiving a specific type of message. This is particularly useful for acknowledging message receipt in systems like the ClusterPubSub feature.

## Setup
To run this example, ensure you have the following prerequisites:
- Go programming environment
- Proto.Actor for Go installed in your environment

You can install Proto.Actor using the following command:
```bash
go get -u github.com/asynkron/protoactor-go
```

## Running the Example

```bash
go run main.go
```

## Additional Notes
- The `myAutoResponder` struct implements the `GetAutoResponse` method which is essential for the Auto Response mechanism.
- The `main` function initializes an actor system, creates an actor, and sends a message to it. The response is then printed to the console.

This example provides a basic understanding of how to implement and use the Auto Response feature in the Proto.Actor framework in Go.
33 changes: 33 additions & 0 deletions _examples/actor-deadletter/readme.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
## AI Generated Content. Please report issues

# Go Example: Handling Invalid PIDs with Deadletter in Proto.Actor

## Introduction
This Go example demonstrates handling invalid PIDs (Process Identifiers) using the deadletter mechanism in the Proto.Actor framework. It showcases how messages sent to invalid PIDs are managed by the deadletter handler.

## Description
The example sets up a scenario where messages are sent to an invalid PID. This triggers the deadletter mechanism, which is a way to handle messages that cannot be delivered to their intended recipients. The program includes options to adjust the rate of message sending, the throttle of deadletter logs, and the duration of the message-sending loop.

## Setup
To run this example, ensure the following are installed:
- Go programming environment
- Proto.Actor for Go

Install Proto.Actor with the following command:
```bash
go get -u github.com/asynkron/protoactor-go
```

## Running the Example

```bash
go run main.go
```
You can also pass optional flags like `--rate`, `--throttle`, and `--duration` to adjust the behavior of the example.

## Additional Notes
- The `main` function initializes an actor system with a custom configuration for deadletter handling.
- The program sends messages to a deliberately invalid PID to demonstrate how the deadletter mechanism works in Proto.Actor.
- The example is useful for understanding the deadletter process in actor-based systems, especially for error handling and debugging.

This example provides insight into managing undeliverable messages in the Proto.Actor framework using Go.
32 changes: 32 additions & 0 deletions _examples/actor-helloworld/readme.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
## AI Generated Content. Please report issues

# Go Example: Hello World with Proto.Actor

## Introduction
This simple Go example demonstrates a basic "Hello World" scenario using the Proto.Actor framework. It's a straightforward introduction to actor-based programming in Go.

## Description
The program defines a `hello` message struct and a `helloActor` actor type. The actor receives a `hello` message and logs a greeting to the console. This example is designed to be an entry point for understanding how actors receive and process messages in Proto.Actor.

## Setup
Ensure the following are installed to run this example:
- Go programming environment
- Proto.Actor for Go

To install Proto.Actor, use the command:
```bash
go get -u github.com/asynkron/protoactor-go
```

## Running the Example

```bash
go run main.go
```

## Additional Notes
- The `helloActor` struct implements the `Receive` method, which is triggered upon message arrival.
- The `main` function creates an actor system, spawns a `helloActor`, and sends it a `hello` message.
- This example is a great starting point for those new to the Proto.Actor framework and actor-based systems in Go.

This example provides a basic yet illustrative demonstration of using actors in Go with the Proto.Actor framework.
39 changes: 32 additions & 7 deletions _examples/actor-jaegertracing/README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,30 @@
# Jeager Tracing / OpenTracing example
## AI Generated Content. Please report issues

# Go Example: Jaeger Tracing with Proto.Actor

## Introduction
This Go example demonstrates how to integrate Jaeger tracing with the Proto.Actor framework. It provides a practical demonstration of implementing distributed tracing in a microservices architecture using Jaeger.

## Description
The program initializes a Jaeger tracer and sets up a simple actor system with Proto.Actor. It sends messages between actors and traces these interactions using Jaeger. This example is particularly useful for understanding how distributed tracing works in complex systems where understanding the flow of requests and responses is crucial.

## Setup
Ensure you have the following to run this example:
- Go programming environment
- Proto.Actor for Go
- Jaeger Tracing libraries

Install the necessary libraries using:
```bash
go get -u github.com/asynkron/protoactor-go
go get -u github.com/uber/jaeger-client-go
```

## Running the Example

```bash
go run main.go
```

To run the example an instance of Jaeger server is required running locally. The easiest way to run a jaeger server
instance is starting it using the included docker-compose file like this
Expand All @@ -7,11 +33,10 @@ instance is starting it using the included docker-compose file like this
docker-compose -f ./examples/jaegertracing/docker-compose.yaml up -d
```

And the just run the example:

```bash
go run ./examples/jaegertracing/main.go
```
## Additional Notes
- The `initJaeger` function sets up Jaeger tracing with basic configuration.
- The program creates an actor system and uses Jaeger to trace the message flow between actors.
- This example is ideal for those looking to implement distributed tracing in their Go applications using Jaeger and Proto.Actor.

After the test has run (and also during), traces can found using the Jaeger UI started at http://localhost:16686.

This example is an insightful demonstration of using Jaeger for distributed tracing in a Go application with the Proto.Actor framework.
32 changes: 32 additions & 0 deletions _examples/actor-lifecycleevents/readme.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
## AI Generated Content. Please report issues

# Go Example: Actor Lifecycle Events with Proto.Actor

## Introduction
This Go example demonstrates handling actor lifecycle events in the Proto.Actor framework. It showcases the various stages in an actor's life, from initialization to shutdown.

## Description
The program creates an actor system and demonstrates the lifecycle events of an actor, including `Started`, `Stopping`, `Stopped`, and `Restarting`. It also sends a `hello` message to the actor to illustrate interaction during its active state. This example is valuable for understanding the lifecycle management of actors 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 `helloActor` struct handles different lifecycle events and logs corresponding messages.
- The `main` function initializes an actor system, spawns a `helloActor`, sends it a message, and then stops it to demonstrate the lifecycle events.
- This example is a practical demonstration for those interested in the lifecycle management of actors in the Proto.Actor framework.

The example provides a clear view of the lifecycle events of an actor in a Go application using the Proto.Actor framework.
4 changes: 4 additions & 0 deletions _examples/actor-logging/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -23,18 +23,21 @@ func (state *helloActor) Receive(context actor.Context) {
}
}

// enable JSON logging
func jsonLogging(system *actor.ActorSystem) *slog.Logger {
return slog.New(slog.NewJSONHandler(os.Stdout, nil)).
With("lib", "Proto.Actor").
With("system", system.ID)
}

// enable console logging
func consoleLogging(system *actor.ActorSystem) *slog.Logger {
return slog.Default().
With("lib", "Proto.Actor").
With("system", system.ID)
}

// enable colored console logging
func coloredConsoleLogging(system *actor.ActorSystem) *slog.Logger {
return slog.New(tint.NewHandler(os.Stdout, &tint.Options{
Level: slog.LevelDebug,
Expand All @@ -44,6 +47,7 @@ func coloredConsoleLogging(system *actor.ActorSystem) *slog.Logger {
With("system", system.ID)
}

// enable Zap logging
func zapAdapterLogging(system *actor.ActorSystem) *slog.Logger {
zapLogger, _ := zap.NewProduction()

Expand Down
35 changes: 35 additions & 0 deletions _examples/actor-logging/readme.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
## AI Generated Content. Please report issues

# Go Example: Advanced Logging with Proto.Actor

## Introduction
This Go example demonstrates various logging mechanisms within the Proto.Actor framework. It shows how to implement different types of logging, including JSON, console, colored console, and Zap adapter logging.

## Description
The program creates a simple actor system and uses different logging methods to log a `hello` message. This example is useful for understanding how to implement and customize logging in applications using the Proto.Actor framework, offering insights into structured logging and its benefits.

## Setup
To run this example, make sure you have:
- Go programming environment
- Proto.Actor for Go
- Necessary logging libraries

Install the required libraries using:
```bash
go get -u github.com/asynkron/protoactor-go
go get -u github.com/lmittmann/tint
go get -u go.uber.org/zap
```

## Running the Example

```bash
go run main.go
```

## Additional Notes
- The example includes different logging functions: `jsonLogging`, `consoleLogging`, `coloredConsoleLogging`, and `zapAdapterLogging`.
- The `helloActor` struct handles a `hello` message and logs it using the specified logging method.
- This example is ideal for developers looking to implement advanced logging techniques in their Go applications using Proto.Actor.

This example provides a comprehensive demonstration of various logging methods in a Go application using the Proto.Actor framework.
33 changes: 33 additions & 0 deletions _examples/actor-supervision/readme.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
## AI Generated Content. Please report issues

# Go Example: Actor Supervision with Proto.Actor

## Introduction
This Go example showcases actor supervision in the Proto.Actor framework. It demonstrates how to handle failures and supervise child actors within a parent actor.

## Description
The program defines two actor types: `parentActor` and `childActor`. The `parentActor` spawns a `childActor` and sends a message to it. The `childActor` simulates a failure upon receiving the message, triggering the supervision strategy defined in the parent actor. This example is crucial for understanding error handling and supervision 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 `parentActor` is responsible for creating and supervising the `childActor`.
- The `childActor` deliberately causes a panic to demonstrate the supervision mechanism.
- The supervision strategy is defined using `actor.NewOneForOneStrategy`.
- This example is particularly useful for developers looking to implement robust error handling and actor supervision in their Go applications using Proto.Actor.

This example provides a detailed insight into actor supervision and error handling in a Go application using the Proto.Actor framework.