{"id":15576418,"url":"https://github.com/njsmith/perpetuo","last_synced_at":"2025-09-05T20:31:54.413Z","repository":{"id":154446306,"uuid":"631791894","full_name":"njsmith/perpetuo","owner":"njsmith","description":"Stall tracking for Python's GIL and Trio tasks","archived":false,"fork":false,"pushed_at":"2025-05-06T22:05:11.000Z","size":181,"stargazers_count":22,"open_issues_count":4,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-06T22:34:00.840Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/njsmith.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}},"created_at":"2023-04-24T04:15:43.000Z","updated_at":"2025-05-06T22:07:10.000Z","dependencies_parsed_at":null,"dependency_job_id":"28f162d4-6091-4139-8ef0-01770a603343","html_url":"https://github.com/njsmith/perpetuo","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/njsmith/perpetuo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njsmith%2Fperpetuo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njsmith%2Fperpetuo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njsmith%2Fperpetuo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njsmith%2Fperpetuo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/njsmith","download_url":"https://codeload.github.com/njsmith/perpetuo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njsmith%2Fperpetuo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273815665,"owners_count":25173278,"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-05T02:00:09.113Z","response_time":402,"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":[],"created_at":"2024-10-02T18:48:57.105Z","updated_at":"2025-09-05T20:31:54.389Z","avatar_url":"https://github.com/njsmith.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Perpetuo\n\n\u003e *perpetuo*, verb: To cause to continue uninterruptedly, to proceed with\n\u003e continually\n\nPerpetuo is a stall tracker for Python. Specifically, it can detect when:\n\n- One thread is holding the GIL for too long, blocking other threads from having\n  a chance to run (requires an instrumented version of CPython)\n\n- One Trio task is running too long without checkpointing, blocking other tasks\n  from having a chance to run\n\nThe actual monitoring is done from a separate process, using a customized\nversion of [py-spy](https://github.com/benfred/py-spy). So the monitoring is\nvery low overhead and should not interfere with the monitored process at all.\nThe goal is to be able to use this in production.\n\n\n## Quickstart\n\n1. `pip install perpetuo`\n2. Optional: patch CPython (see below)\n3. `import perpetuo`\n4. If you're using Trio: call `perpetuo.dwim()` inside `trio.run`\n\n   If you're not using Trio: call `perpetuo.dwim()` anywhere \n5. Optional: log `perpetuo.dwim()`'s return value to see what it did\n\n\n## Available API\n\n`perpetuo.start_watcher()`: Spawns the monitoring process in the background. \n\n`perpetuo.instrument_gil()`: Enables GIL instrumentation, or raises\n`RuntimeError` if you don't have the patched version of CPython.\n\n`perpetuo.instrument_trio()`: Enables Trio instrumentation. Must be called\ninside `trio.run`.\n\n`perpetuo.dwim()`: Attempts to call all the above functions as appropriate, and\nreturns a list of strings describing which operations it actually performed. If\nyou're using Trio, make sure to call it inside `trio.run`.\n\n`StallTracker`: Low-level class that allows you to add custom instrumentation to\nother things. See source for details.\n\n\n## Patching CPython to instrument the GIL\n\nThere are patches available for:\n\nCPython version 3.10.*:\n\n  https://github.com/python/cpython/compare/3.10...njsmith:cpython:njs/perpetuo-gil.diff\n\nCPython version 3.11:\n\n  https://github.com/python/cpython/compare/3.11...njsmith:cpython:njs/perpetuo-gil-3.11.diff\n\nCPython version 3.12:\n\n  https://github.com/python/cpython/compare/3.12...njsmith:cpython:njs/perpetuo-gil-3.12.diff\n\n## Bonus\n\n[Niccolò Paganini's *Moto Perpetuo*, performed by Antal Zalai](https://www.youtube.com/watch?v=D-TAO7U6rtg)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnjsmith%2Fperpetuo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnjsmith%2Fperpetuo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnjsmith%2Fperpetuo/lists"}