{"id":32529949,"url":"https://github.com/clouder0/starway","last_synced_at":"2025-10-28T11:56:03.713Z","repository":{"id":313877372,"uuid":"1053043146","full_name":"Clouder0/starway","owner":"Clouder0","description":"Python RDMA P2P communication library based on OpenUCX.","archived":false,"fork":false,"pushed_at":"2025-10-20T17:07:59.000Z","size":160,"stargazers_count":2,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-20T19:11:17.761Z","etag":null,"topics":["distributed-systems","machine-learning","networking","python","ray","rdma","ucx","ucx-py"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Clouder0.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-09-08T23:06:15.000Z","updated_at":"2025-10-20T17:08:03.000Z","dependencies_parsed_at":"2025-10-20T19:07:11.288Z","dependency_job_id":"5d757cab-2fd9-41a9-840d-d2cf59ba7e54","html_url":"https://github.com/Clouder0/starway","commit_stats":null,"previous_names":["clouder0/starway"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/Clouder0/starway","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Clouder0%2Fstarway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Clouder0%2Fstarway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Clouder0%2Fstarway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Clouder0%2Fstarway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Clouder0","download_url":"https://codeload.github.com/Clouder0/starway/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Clouder0%2Fstarway/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281433290,"owners_count":26500408,"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-10-28T02:00:06.022Z","response_time":60,"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":["distributed-systems","machine-learning","networking","python","ray","rdma","ucx","ucx-py"],"created_at":"2025-10-28T11:55:44.780Z","updated_at":"2025-10-28T11:56:03.708Z","avatar_url":"https://github.com/Clouder0.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Starway\n\nStarway is an ultra-fast communication library that wraps OpenUCX to deliver\nlock-free, asynchronous, zero-copy messaging for Python applications.\n\n## Highlights\n\n- Zero-copy transfers into preallocated NumPy buffers.\n- Full-duplex messaging with independent async send/recv APIs.\n- Choice of connection style: traditional TCP socket address or direct UCX\n  worker-address handshakes (no TCP listener required).\n- Flush primitives (`aflush`, `aflush_ep`) to force completion ordering when\n  you need delivery guarantees.\n- Built-in performance probes via `evaluate_perf` for quick transport telemetry.\n\n## Installation\n\nStarway depends on dynamic OpenUCX libraries:\n\n1. Install OpenUCX system-wide (for example via your distro's package manager\n   or an HPC toolchain), or\n2. Install the `libucx-cu12` wheel, which ships redistributable shared objects.\n\nStarway does not hard-depend on `libucx-cu12`; it is treated as an optional\nfallback.\n\nYou can use environment variable to control System/Wheel preference:\n\n```python\nimport os\n\n# Defaults to \"true\". Set to \"false\" to prefer the wheel first.\nos.environ[\"STARWAY_USE_SYSTEM_UCX\"] = \"false\"\n\nimport starway  # falls back to system UCX if the wheel is unavailable\n```\n\n## Quick Start\n\n### Socket-address workflow\n\n```python\nimport asyncio\nimport numpy as np\nfrom starway import Client, Server\n\nSERVER_ADDR, SERVER_PORT = \"127.0.0.1\", 19198\n\n\nasync def main():\n    server = Server()\n    client = Client()\n\n    server.listen(SERVER_ADDR, SERVER_PORT)\n    await client.aconnect(SERVER_ADDR, SERVER_PORT)\n\n    # Establish endpoint object on the server side\n    client_ep = next(iter(server.list_clients()))\n\n    send_buf = np.arange(4, dtype=np.uint8)\n    recv_buf = np.zeros_like(send_buf)\n\n    recv_task = server.arecv(recv_buf, tag=1, tag_mask=0xFFFF)\n    await client.asend(send_buf, tag=1)\n    await recv_task\n\n    await asyncio.gather(client.aflush(), server.aflush_ep(client_ep))\n    await asyncio.gather(client.aclose(), server.aclose())\n\n\nasyncio.run(main())\n```\n\n### Worker-address workflow\n\n```python\nimport asyncio\nimport numpy as np\nfrom starway import Client, Server\n\n\nasync def main():\n    server = Server()\n    worker_address = server.listen_address()  # bytes blob, no TCP listener\n\n    client = Client()\n    await client.aconnect_address(worker_address)\n\n    # Accept callback still fires; poll list_clients() to obtain the peer ep\n    for _ in range(100):\n        clients = server.list_clients()\n        if clients:\n            client_ep = next(iter(clients))\n            break\n        await asyncio.sleep(0.01)\n\n    recv_buf = np.zeros(4, dtype=np.uint8)\n    recv_task = server.arecv(recv_buf, tag=2, tag_mask=0xFFFF)\n    await client.asend(np.arange(4, dtype=np.uint8), tag=2)\n    await recv_task\n\n    await asyncio.gather(client.aclose(), server.aclose())\n\n\nasyncio.run(main())\n```\n\n## API Cheatsheet\n\n### `Server`\n\n- `listen(addr, port)` – create a TCP-backed listener.\n- `listen_address()` – start worker-only mode and return the local UCX worker\n  address for out-of-band distribution.\n- `set_accept_cb(callback)` – invoked for each new endpoint (both listener and\n  worker-address flows).\n- `list_clients()` – inspect active UCX endpoints.\n- `asend(client_ep, buffer, tag)` / `arecv(buffer, tag, tag_mask)` – async\n  one-sided messaging.\n- `aflush()` – wait for all server-side operations to complete.\n- `aflush_ep(client_ep)` – flush operations targeting a specific endpoint.\n- `evaluate_perf(client_ep, msg_size)` – request UCX transport estimates.\n- `get_worker_address()` – read back the cached worker address bytes.\n- `aclose()` – gracefully shut down and release resources.\n\n### `Client`\n\n- `aconnect(addr, port)` – connect to a listener.\n- `aconnect_address(worker_address)` – connect using a UCX worker address only.\n- `asend(buffer, tag)` / `arecv(buffer, tag, tag_mask)` – async messaging APIs.\n- `aflush()` – wait for in-flight client operations to finish.\n- `evaluate_perf(msg_size)` – ask UCX for local transport estimates.\n- `get_worker_address()` – shareable bytes for reciprocal connections.\n- `aclose()` – close the connection and stop the worker.\n\n### `ServerEndpoint`\n\nInspect transport metadata for debugging or topology decisions:\n\n- `.name` – UCX endpoint name.\n- `.local_addr`, `.local_port`, `.remote_addr`, `.remote_port` – socket details\n  when available (address-only mode may leave these empty).\n- `.view_transports()` – list `(device, transport)` tuples negotiated by UCX.\n\n## Flushing and Ordering\n\nUCX operations are inherently asynchronous. Starway exposes lightweight futures\non top of UCX requests and lets you opt into ordering guarantees:\n\n- `Client.aflush()` and `Server.aflush()` drain all pending operations on their\n  respective workers.\n- `Server.aflush_ep(ep)` waits for sends targeting a single endpoint.\n- All async flushes integrate with Python's event loop, making them suitable for\n  structured concurrency patterns (`await asyncio.gather(...)`).\n\n## Testing\n\nPytest drives the integration suite. Typical commands:\n\n```bash\nuv sync --group dev --group test\nuv run pytest tests/test_basic.py -vv\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclouder0%2Fstarway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclouder0%2Fstarway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclouder0%2Fstarway/lists"}