{"id":16904197,"url":"https://github.com/mikea/tractor","last_synced_at":"2025-10-26T10:03:44.166Z","repository":{"id":57658886,"uuid":"312385682","full_name":"mikea/tractor","owner":"mikea","description":"Actor System for Golang","archived":false,"fork":false,"pushed_at":"2022-04-09T17:14:16.000Z","size":74,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-03-20T15:37:29.175Z","etag":null,"topics":["actor-framework","actor-model","golang","golang-library"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mikea.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-11-12T20:16:31.000Z","updated_at":"2024-10-14T18:16:39.000Z","dependencies_parsed_at":"2022-08-29T10:30:27.203Z","dependency_job_id":null,"html_url":"https://github.com/mikea/tractor","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mikea/tractor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikea%2Ftractor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikea%2Ftractor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikea%2Ftractor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikea%2Ftractor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mikea","download_url":"https://codeload.github.com/mikea/tractor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikea%2Ftractor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276676405,"owners_count":25684453,"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","status":"online","status_checked_at":"2025-09-23T02:00:09.130Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-framework","actor-model","golang","golang-library"],"created_at":"2024-10-13T18:32:03.981Z","updated_at":"2025-09-24T01:21:35.598Z","avatar_url":"https://github.com/mikea.png","language":"Go","readme":"![build](https://github.com/mikea/tractor/workflows/Go/badge.svg)\n\n# Tractor\n\n*[WORK IN PROGRESS]*\n\nActor System for Golang.\n\nThe goal of the project at this stage is to design an idiomatic go api for actor programming model together with common\nservices provided by an actor system.\n\n## Documentation\n\n### Defining Actors\n\n#### Setup Handler\n\nTo define an actor the setup handler needs to be provided:\n\n```go\ntype SetupHandler func(ctx ActorContext) MessageHandler\n```\n\nThis callback is executed by the system every time new instance of the actor is created. The job of the callback is to\ninitialize all resources, send all initial requests, setup and return the message handler responsible for processing\nactor mailbox messages.\n\n#### Message Handler\n\nMessage handler callback processes the incoming message and returns a new handler to be used after the message.\n\n```go\ntype MessageHandler func(message interface{}) MessageHandler\n``` \n\nTwo special values are recognized:\n\n- `nil` - signals to use the *same* handler that was used to process the message\n- `Stopped()` - signals to the system to terminate the current actor.\n\n#### Setup Parameters\n\nTo parametrize an actor create a closure binding initialization parameters:\n\n```go\nfunc Countdown(start int) SetupHandler {\n    return func(ctx ActorContext) MessageHandler {\n        count := start\n        return func(msg interface{}) MessageHandler {\n            count = count - 1\n            if count == 0 {\n                return Stopped()\n            }\n            return nil\n        }\n    }\n}\n```\n\n### Spawning Actors\n\nAny actor can spawn a child by invoking `ctx.Spawn()` method with a setup handler:\n\n```go\nctx.Spawn(Countdown(10))\n``` \n\n### Actor Lifecycle\n\n#### Signals\n\nReceive messages related to the actor lifecycle by enabling signal delivery in the context:\n\n```go\nfunc(ctx ActorContext) MessageHandler {\n    ctx.DeliverSignals(true)\n    return func(msg interface{}) MessageHandler {\n        switch msg.(type) {\n        case PostInitSignal:\n            // first message delivered after the initialization\n        case PreStopSignal:\n            // delivered before terminating children\n        case PostStopSignal:\n            // delivered after terminating all children\n        }\n        return nil\n    }\n}\n```\n\n#### Watching Actors\n\nAny actor can be notified when any other actor is terminated:\n\n```go\nfunc(ctx ActorContext) MessageHandler {\n    ctx.Watch(ctx.Spawn(child))\n    return func(msg interface{}) MessageHandler {\n        switch msg.(type) {\n        case Terminated:\n            // child was terminated\n        }\n        return nil\n    }\n}\n```\n\nor with a custom message:\n\n```go\nctx.WatchWith(ctx.Spawn(child), \"childTerminated\")\n```\n\n### Actor Communication\n\n#### Tell\n\nSending messages to a different actor is potentially a difficult enterprise and might involve other actor creation. Thus\ncurrent actor context is required to send messsages:\n\n```go\nchild := ctx.Spawn(setupChild)\nchild.Tell(ctx, \"ping\")\n```\n\n#### Sender\n\nDuring the event processing the sender of the message is available:\n\n```\nreturn func(msg interface{}) MessageHandler {\n    if msg == \"ping\" {\n        ctx.Sender().Tell(ctx, \"pong\")\n    }\n    return nil\n}\n```\n\n#### Ask\n\nAsking an actor means sending it a message and expecting a reply back.\n`Ask()` method in context provides a bridge between go channels and actor communcation, enabling you to write blocking\ncode:\n\n```go\nreply := \u003c-ctx.Ask(ref, \"ping\")\n```\n\n### Actor System\n\n#### Starting System\n\nTo start the system you neeed to provide setup handler for the root actor:\n\n```go\nsystem := tractor.Start(Root())\n```\n\n#### Shutting Down\n\nThe system shuts down when root actor stops. You can wait for actor system to finish:\n\n```go\nsystem.Wait()\n```\n\n#### Communicating With System\n\nCommunication with the running system is done through the root actor reference and system context:\n\n```go\nsystem.Root().Tell(system.Context(), \"request\")\n```\n\n### Patterns\n\n#### Typed Reference\n\nDealing with untyped messages might be challenges to scale. A simple typed wrappers can be created that will define\npublic api:\n\n```go\ntype getAndIncrement struct{ }\n\nfunc Counter() SetupHandler {\n    return func(ctx ActorContext) MessageHandler {\n        count := 0\n        return func(m interface{}) MessageHandler {\n            switch m.(type) {\n            case getAndIncrement:\n                ctx.Sender().Tell(ctx, count)\n                count++\n            }\n            return nil\n        }\n    }\n}\n\ntype CounterRef struct {\n    Ref ActorRef\n}\n\nfunc (ref CounterRef) GetAndIncrement(ctx ActorContext) chan interface{} {\n    return ctx.Ask(ref.Ref, getAndIncrement{})\n}\n```\n\n## Development\n\nUse nix to set up development environment:\n\n```bash\nnix-shell\ngo test ./...\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikea%2Ftractor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikea%2Ftractor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikea%2Ftractor/lists"}