{"id":13413048,"url":"https://github.com/vladopajic/go-actor","last_synced_at":"2025-04-12T23:39:09.700Z","repository":{"id":56855112,"uuid":"525332482","full_name":"vladopajic/go-actor","owner":"vladopajic","description":"A lightweight library for writing concurrent programs in Go using the Actor model.","archived":false,"fork":false,"pushed_at":"2025-03-27T09:36:41.000Z","size":290,"stargazers_count":211,"open_issues_count":0,"forks_count":15,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-12T23:38:54.972Z","etag":null,"topics":["actor","actor-model","communicating-sequential-processes","concurrency","concurrent-programming","csp","go","go-actor","go-channel","go-concurrency","golang","goroutine","goroutines","goroutines-channels","high-performance"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vladopajic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["vladopajic"]}},"created_at":"2022-08-16T10:31:52.000Z","updated_at":"2025-04-10T10:39:55.000Z","dependencies_parsed_at":"2024-01-08T15:03:05.793Z","dependency_job_id":"345650d0-866f-4550-81b1-09aa0bd47b5f","html_url":"https://github.com/vladopajic/go-actor","commit_stats":{"total_commits":155,"total_committers":4,"mean_commits":38.75,"dds":"0.40645161290322585","last_synced_commit":"61feae2a0a159b3b0493922e123da049f61a3dd5"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladopajic%2Fgo-actor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladopajic%2Fgo-actor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladopajic%2Fgo-actor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladopajic%2Fgo-actor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vladopajic","download_url":"https://codeload.github.com/vladopajic/go-actor/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248647255,"owners_count":21139081,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actor","actor-model","communicating-sequential-processes","concurrency","concurrent-programming","csp","go","go-actor","go-channel","go-concurrency","golang","goroutine","goroutines","goroutines-channels","high-performance"],"created_at":"2024-07-30T20:01:32.805Z","updated_at":"2025-04-12T23:39:09.676Z","avatar_url":"https://github.com/vladopajic.png","language":"Go","funding_links":["https://github.com/sponsors/vladopajic"],"categories":["Goroutines","Go"],"sub_categories":["Search and Analytic Databases","检索及分析资料库"],"readme":"# go-actor\n\n[![test](https://github.com/vladopajic/go-actor/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/vladopajic/go-actor/actions/workflows/test.yml)\n[![lint](https://github.com/vladopajic/go-actor/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/vladopajic/go-actor/actions/workflows/lint.yml)\n[![coverage](https://raw.githubusercontent.com/vladopajic/go-actor/badges/.badges/main/coverage.svg)](./.testcoverage.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/vladopajic/go-actor?cache=v1)](https://goreportcard.com/report/github.com/vladopajic/go-actor)\n[![GoDoc](https://godoc.org/github.com/vladopajic/go-actor?status.svg)](https://godoc.org/github.com/vladopajic/go-actor)\n[![Release](https://img.shields.io/github/v/release/vladopajic/go-actor?color=%23007ec6)](https://github.com/vladopajic/go-actor/releases/latest)\n\n![goactor-cover](https://user-images.githubusercontent.com/4353513/185381081-2e2a07f3-c13a-4946-a250-b2cbe6588f60.png)\n\n`go-actor` is a lightweight library for writing concurrent programs in Go using the Actor model.\n\n\n## Motivation\n\nWithout reusable design principles, maintaining a complex codebase can be challenging, as developers implement logic differently when no common practice is defined.\n\n**go-actor** aims to provide a pattern for building highly efficient programs, giving developers a straightforward approach to designing components, the building blocks of programs, using a pattern based on the **Actor Model** and **Communicating Sequential Processes (CSP)**.\n\n## Advantage\n\n- **Unified Design Principles**: Model the entire codebase using the same principles, where each actor is a fundamental building block.\n- **Natural Fit with Go**: Leverage Go's goroutines and channels, which directly translate to actors and mailboxes.\n- **Avoid Mutexes**: Design systems without the need for mutexes, reducing the potential for deadlocks and improving performance in complex components.\n- **Optimal Scheduling**: Enhance performance by optimizing for Go's goroutine scheduler.\n-  **Easy Transition**: Legacy codebases can transition to an actor-based design due to the simple interfaces provided by go-actor, allowing for seamless integration.\n- **Zero Overhead**: Ensure optimal performance in highly concurrent environments.\n\n\n## Abstractions\n\nThe core abstraction layer of go-actor consists of three primary interfaces:\n\n- `actor.Actor`: Represents any entity that implements the `Start()` and `Stop()` methods. Actors created using the `actor.New(actor.Worker)` function spawn a dedicated goroutine to execute the supplied `actor.Worker`.\n- `actor.Worker`: Encapsulates the executable logic of an actor. This is the primary interface developers need to implement to define an actor's behavior.\n- `actor.Mailbox`: An interface for message transport mechanisms between actors, created using the `actor.NewMailbox(...)` function.\n\n\n## Examples\n\nExplore the [examples](https://github.com/vladopajic/go-actor-examples) repository to see `go-actor` in action. Reviewing these examples is highly recommended, as they will greatly enhance your understanding of the library.\n\n\n```go\n// This example will demonstrate how to create actors for producer-consumer use case.\n// Producer will create incremented number on every 1 second interval and\n// consumer will print whatever number it receives.\nfunc main() {\n\tmbx := actor.NewMailbox[int]()\n\n\t// Produce and consume workers are created with same mailbox\n\t// so that produce worker can send messages directly to consume worker\n\tp := actor.New(\u0026producerWorker{mailbox: mbx})\n\tc1 := actor.New(\u0026consumerWorker{mailbox: mbx, id: 1})\n\n\t// Note: Example creates two consumers for the sake of demonstration\n\t// since having one or more consumers will produce the same result. \n\t// Message on stdout will be written by first consumer that reads from mailbox.\n\tc2 := actor.New(\u0026consumerWorker{mailbox: mbx, id: 2})\n\n\t// Combine all actors to singe actor so we can start and stop all at once\n\ta := actor.Combine(mbx, p, c1, c2).Build()\n\ta.Start()\n\tdefer a.Stop()\n\t\n\t// Stdout output:\n\t// consumed 1      (worker 1)\n\t// consumed 2      (worker 2)\n\t// consumed 3      (worker 1)\n\t// consumed 4      (worker 2)\n\t// ...\n\n\tselect {}\n}\n\n// producerWorker will produce incremented number on 1 second interval\ntype producerWorker struct {\n\tmailbox actor.MailboxSender[int]\n\tnum  int\n}\n\nfunc (w *producerWorker) DoWork(ctx actor.Context) actor.WorkerStatus {\n\tselect {\n\tcase \u003c-ctx.Done():\n\t\treturn actor.WorkerEnd\n\n\tcase \u003c-time.After(time.Second):\n\t\tw.num++\n\t\tw.mailbox.Send(ctx, w.num)\n\n\t\treturn actor.WorkerContinue\n\t}\n}\n\n// consumerWorker will consume numbers received on mailbox\ntype consumerWorker struct {\n\tmailbox actor.MailboxReceiver[int]\n\tid  int\n}\n\nfunc (w *consumerWorker) DoWork(ctx actor.Context) actor.WorkerStatus {\n\tselect {\n\tcase \u003c-ctx.Done():\n\t\treturn actor.WorkerEnd\n\n\tcase num := \u003c-w.mailbox.ReceiveC():\n\t\tfmt.Printf(\"consumed %d \\t(worker %d)\\n\", num, w.id)\n\n\t\treturn actor.WorkerContinue\n\t}\n}\n```\n\n## Add-ons\n\nWhile `go-actor` is designed to be a minimal library with lean interfaces, developers can extend its functionality with domain-specific add-ons. Some notable add-ons include:\n\n- [super](https://github.com/vladopajic/go-super-actor): An add-on for unifying the testing of actors and workers.\n- [commence](https://github.com/vladopajic/go-actor-commence): An add-on that provides a mechanism for waiting for actor execution to begin.\n\n\n## Pro Tips\n\nTo enhance code quality in projects that heavily rely on the actor model with `go-actor`, consider adhering to [best practices](./docs/best_practices.md) and reviewing [common hurdles](./docs/common_hurdles.md) for frequently encountered issues.\n\n## Design Decisions\n\nYou can find detailed design decisions [here](./docs/design_decisions.md).\n\n## Benchmarks\n\nSee library benchmarks [here](./docs/benchmarks.md).\n\n\n## Versioning\n\nThe `go-actor` library adopts a versioning scheme structured as `x.y.z`.\n\nInitially, the library will utilize the format `0.y.z` as it undergoes refinement until it attains a level of stability where fundamental interfaces and core principles no longer necessitate significant alterations. Within this semantic, the `y` component signifies a version that is not backward-compatible. It is advisable for developers to review the release notes carefully to gain insight into these modifications. Furthermore, the final component, `z`, denotes releases incorporating changes that are backward-compatible. \n\n\n## Contribution\n\nAll contributions are useful, whether it is a simple typo, a more complex change, or just pointing out an issue. We welcome any contribution so feel free to open PR or issue. \n\nContinue reading [here](./docs/contributing.md).\n\n\nHappy coding 🌞\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvladopajic%2Fgo-actor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvladopajic%2Fgo-actor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvladopajic%2Fgo-actor/lists"}