{"id":28641043,"url":"https://github.com/xorbitsai/xoscar","last_synced_at":"2026-04-25T17:04:51.580Z","repository":{"id":69903052,"uuid":"596462545","full_name":"xorbitsai/xoscar","owner":"xorbitsai","description":"Python actor framework for heterogeneous computing.","archived":false,"fork":false,"pushed_at":"2026-01-15T12:54:22.000Z","size":894,"stargazers_count":169,"open_issues_count":24,"forks_count":28,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-15T16:29:02.410Z","etag":null,"topics":["actor-model","asynchronous","distributed-computing"],"latest_commit_sha":null,"homepage":"https://xoscar.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xorbitsai.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-02-02T08:32:23.000Z","updated_at":"2026-01-15T12:22:01.000Z","dependencies_parsed_at":"2024-06-18T21:30:58.230Z","dependency_job_id":"87e595c9-6594-4db4-9d8e-a97cd38d441f","html_url":"https://github.com/xorbitsai/xoscar","commit_stats":null,"previous_names":["xorbitsai/xoscar"],"tags_count":56,"template":false,"template_full_name":null,"purl":"pkg:github/xorbitsai/xoscar","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xorbitsai%2Fxoscar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xorbitsai%2Fxoscar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xorbitsai%2Fxoscar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xorbitsai%2Fxoscar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xorbitsai","download_url":"https://codeload.github.com/xorbitsai/xoscar/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xorbitsai%2Fxoscar/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28482267,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-model","asynchronous","distributed-computing"],"created_at":"2025-06-12T20:36:45.984Z","updated_at":"2026-01-16T20:36:36.486Z","avatar_url":"https://github.com/xorbitsai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg width=\"77%\" alt=\"\" src=\"https://raw.githubusercontent.com/xprobe-inc/xoscar/main/doc/source/_static/Xoscar.svg\"\u003e\u003cbr\u003e\n\u003c/div\u003e\n\n# Python actor framework for heterogeneous computing.\n[![PyPI Latest Release](https://img.shields.io/pypi/v/xoscar.svg?style=for-the-badge)](https://pypi.org/project/xoscar/)\n[![Coverage](https://img.shields.io/codecov/c/github/xorbitsai/xoscar?style=for-the-badge)](https://codecov.io/gh/xorbitsai/xoscar)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/xorbitsai/xoscar/python.yaml?branch=main\u0026style=for-the-badge\u0026label=GITHUB%20ACTIONS\u0026logo=github)](https://actions-badge.atrox.dev/xorbitsai/xoscar/goto?ref=main)\n[![License](https://img.shields.io/pypi/l/xoscar.svg?style=for-the-badge)](https://github.com/xorbitsai/xoscar/blob/main/LICENSE)\n\n## What is actor\nWriting parallel and distributed programs is often challenging and requires a lot of time to deal with concurrency\nissues. Actor model provides a high-level, scalable and robust abstraction for building distributed applications. \nIt provides several benefits:\n- Scalability: Actors easily scale across nodes. The asynchronous, non-blocking nature of actors allows them to handle huge volumes of concurrent tasks efficiently.\n- Concurrency: The actor model abstracts over concurrency, allowing developers to avoid raw threads and locks.\n- Modularity: An actor system decomposes naturally into a collection of actors that can be understood independently. Actor logic is encapsulated within the actor itself.\n\n## Why Xoscar\nXoscar implements the actor model in Python and provides user-friendly APIs that offer significant benefits for building \napplications on heterogeneous hardware:\n- **Abstraction over low-level communication details**: Xoscar handles all communication between actors transparently,\nwhether on CPUs, GPUs, or across nodes. Developers focus on application logic rather than managing hardware resources \nand optimizing data transfer.\n- **Flexible actor models**: Xoscar supports both stateful and stateless actors. Stateful actors ensure thread safety for \nconcurrent systems while stateless actors can handle massive volumes of concurrent messages. Developers choose the \nappropriate actor model for their needs.\n- **Batch method**: Xoscar provides a batch interface to significantly improve call efficiency when an actor interface is \ninvoked a large number of times.\n- **Advanced debugging support**: Xoscar can detect potential issues like deadlocks, long-running calls, and performance\nbottlenecks that would otherwise be nearly impossible to troubleshoot in a heterogeneous environment.\n- **Automated recovery**: If an actor fails for any reason, Xoscar will automatically restart it if you want. It can monitor \nactors and restart them upon failure, enabling fault-tolerant systems.\n\n## Overview\n![architecture.png](doc/source/_static/architecture.png)\nXoscar allows you to create multiple actor pools on each worker node, typically binding an actor pool to a CPU core or \na GPU card. Xoscar provides allocation policies so that whenever an actor is created, it will be instantiated in the\nappropriate pool based on the specified policy.\n\nWhen actors communicate, Xoscar will choose the optimal communication mechanism based on which pools the actors \nbelong to. This allows Xoscar to optimize communication in heterogeneous environments with multiple processing \nunits and accelerators.\n\n## Where to get it\n\n### PyPI\nBinary installers for the latest released version are available at the [Python\nPackage Index (PyPI)](https://pypi.org/project/xoscar).\n\n```shell\n# PyPI\npip install xoscar\n```\n\n### Build from source\nThe source code is currently hosted on GitHub at: https://github.com/xorbitsai/xoscar .\n\nBuilding from source requires that you have cmake and gcc installed on your system.\n\n- cmake \u003e= 3.11\n- gcc \u003e= 8\n\n```shell\n# If you have never cloned xoscar before\ngit clone --recursive https://github.com/xorbitsai/xoscar.git\ncd xoscar/python\npip install -e .\n\n# If you have already cloned xoscar before\ncd xoscar\ngit submodule init\ngit submodule update\ncd python \u0026\u0026 pip install -e .\n```\n\n## APIs\nHere are basic APIs for Xoscar.\n#### Define an actor\n```python\nimport xoscar as xo\n\n# stateful actor, for stateless actor, inherit from xo.StatelessActor\nclass MyActor(xo.Actor):\n    def __init__(self, *args, **kwargs):\n        pass\n\n    async def __post_create__(self):\n        # called after created\n        pass\n\n    async def __pre_destroy__(self):\n        # called before destroy\n        pass\n\n    def method_a(self, arg_1, arg_2, **kw_1):  # user-defined function\n        pass\n\n    async def method_b(self, arg_1, arg_2, **kw_1):  # user-defined async function\n        pass\n```\n\n#### Create an actor\n```python\nimport xoscar as xo\n\nactor_ref = await xo.create_actor(\n    MyActor, 1, 2, a=1, b=2,\n    address='\u003cip\u003e:\u003cport\u003e', uid='UniqueActorName')\n```\n\n#### Get an actor reference\n```python\nimport xoscar as xo\n\nactor_ref = await xo.actor_ref(address, actor_id)\n```\n\n#### Invoke a method\n```python\n# send\nawait actor_ref.method_a.send(1, 2, a=1, b=2)\n# equivalent to actor_ref.method_a.send\nawait actor_ref.method_a(1, 2, a=1, b=2)\n# tell, it sends a message asynchronously and does not wait for a response.\nawait actor_ref.method_a.tell(1, 2, a=1, b=2)\n```\n### Batch method\nXoscar provides a set of APIs to write batch methods. You can simply add a `@extensible` decorator to your actor method\nand create a batch version. All calls wrapped in a batch will be sent together, reducing possible RPC cost.\n#### Define a batch method\n```python\nimport xoscar as xo\n\nclass ExampleActor(xo.Actor):\n    @xo.extensible\n    async def batch_method(self, a, b=None):\n        pass\n```\nXoscar also supports creating a batch version of the method:\n```python\nclass ExampleActor(xo.Actor):\n    @xo.extensible\n    async def batch_method(self, a, b=None):\n        raise NotImplementedError  # this will redirect all requests to the batch version\n\n    @batch_method.batch\n    async def batch_method(self, args_list, kwargs_list):\n        results = []\n        for args, kwargs in zip(args_list, kwargs_list):\n            a, b = self.batch_method.bind(*args, **kwargs)\n            # process the request\n            results.append(result)\n        return results  # return a list of results\n```\nIn a batch method, users can define how to more efficiently process a batch of requests.\n\n#### Invoke a batch method\nCalling batch methods is easy. You can use `\u003cmethod_name\u003e.delay` to make a batched call and use `\u003cmethod_name\u003e.batch` to send them:\n```python\nref = await xo.actor_ref(uid='ExampleActor', address='127.0.0.1:13425')\nresults = await ref.batch_method.batch(\n    ref.batch_method.delay(10, b=20),\n    ref.batch_method.delay(20),\n)\n```\n\n## License\n[Apache 2](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxorbitsai%2Fxoscar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxorbitsai%2Fxoscar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxorbitsai%2Fxoscar/lists"}