{"id":22797332,"url":"https://github.com/bawng/actuator","last_synced_at":"2025-04-19T15:13:00.535Z","repository":{"id":62552974,"uuid":"117801857","full_name":"bawNg/actuator","owner":"bawNg","description":"High precision scheduling of light weight timers for async and fibered Ruby applications","archived":false,"fork":false,"pushed_at":"2018-01-23T19:15:26.000Z","size":23,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-17T09:02:46.022Z","etag":null,"topics":["async","fibers","high-performance","high-precision","reactor","ruby","ruby-extension","timers"],"latest_commit_sha":null,"homepage":null,"language":"C++","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/bawNg.png","metadata":{"files":{"readme":"README.md","changelog":"History.txt","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":"2018-01-17T07:37:31.000Z","updated_at":"2022-08-25T19:07:17.000Z","dependencies_parsed_at":"2022-11-03T04:01:14.891Z","dependency_job_id":null,"html_url":"https://github.com/bawNg/actuator","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bawNg%2Factuator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bawNg%2Factuator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bawNg%2Factuator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bawNg%2Factuator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bawNg","download_url":"https://codeload.github.com/bawNg/actuator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249723810,"owners_count":21316114,"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":["async","fibers","high-performance","high-precision","reactor","ruby","ruby-extension","timers"],"created_at":"2024-12-12T06:05:45.213Z","updated_at":"2025-04-19T15:13:00.518Z","avatar_url":"https://github.com/bawNg.png","language":"C++","readme":"## Welcome to Actuator\n\nCode: https://github.com/bawNg/actuator \\\nBugs: https://github.com/bawNg/actuator/issues\n\nActuator provides high precision scheduling of light weight timers for async and fibered real-time Ruby applications.\nEven on Windows where kernel precision is lower, average timer accuracy is ~2 us on modern high end hardware (subject to system load). \n\nThis C++ Ruby extension allows time-sensitive applications to replace native threads with jobs that run in pooled fibers.\n\nThis is an alpha release, not recommended for production use. While fairly well tested on Windows and Linux, minimal safety \nand error handling has been implemented in order to minimize overhead. Using the API wrong may result in a segfault.\n\n#### Features\n\n* Provides a high precision float representing the current reactor time\n* High precision single threaded timer callback scheduling\n* Light weight jobs can be used to replace threads with pooled fibers\n* Job-based implementation of sleep, join, kill, Mutex and ConditionVariable\n* Job-aware sample-based CPU profiling API and execution time warnings\n* Warnings for timers that fire later than the configured threshold\n* Low overhead timestamped logging API which is thread-safe\n\n#### Supported platforms\n\n* MRI Ruby 2.x (1.9 is probably compatible but has not been tested).\n* High precision timer support is implemented for Windows, Linux and OSX.\n\n#### Getting started\n\n  Install the gem with `gem install actuator` or by adding it to your bundle.\n\n  ```ruby\n  require 'actuator'\n  \n  Actuator.run do\n    # Schedule a once off timer which fires after 500 us delay\n    Timer.in 0.0005 do\n      Log.puts \"Reactor time: #{Actuator.now}\"\n    end\n    # Schedule a repeating timer which fires every 50ms\n    Timer.every 0.05 do\n      Log.puts \"50ms have passed\"\n    end\n    # Schedule a timer which we will cancel before it expires\n    timer = Timer.in 0.005 do\n      Log.warn \"This should never be printed\"\n    end\n    # Create a new job which executes inside a pooled fiber\n    job1 = Actuator.defer do\n      begin\n        Log.puts \"Job has started\"\n        # Yield from the job fiber for 200ms\n        Job.sleep 0.2\n        Log.warn \"Job 1 finished sleeping even though it should have been killed\"\n      ensure\n        # The stack is unwound when a job is killed so ensure blocks are executed\n        Log.puts \"Job 1 is ending\"\n      end\n    end\n    # Create another new job\n    job2 = Actuator.defer do\n      # Yield from job fiber until job1 ends\n      job1.join\n      Log.puts \"Job 2 finished waiting for Job 1\"\n    end\n    Job.sleep 0.001\n    # Cancel the 5ms timer that we scheduled above\n    timer.destroy\n    Job.sleep 0.1\n    # Kill job1 before it finishes sleeping\n    job1.kill\n    # Wait for job2 to end naturally\n    job2.join\n    Log.puts \"Job 2 has ended\"\n    # Shutdown the reactor\n    Actuator.stop\n  end\n  ```\n\n#### Known issues\n- Timer precision is much worse on OSX. This is most likely due to threads taking too long to wake up.\n  I don't have an OSX machine to be able to test, hopefully someone else can investigate and submit a patch.\n- Memory for active timers will not be freed when calling Actuator.stop\n- The profiling API will include time spent yielded from the job.\n  The job-aware implementation has been commented out to reduce overhead until the profiling has been rewritten in C++.\n- Minimal safety checks and error handling has been implemented in order to minimize overhead. Using the API wrong may result in a segfault.\n  Feel free to open a bug report for any such cases that you may come across.\n\n\n#### Contributing\n\nActuator is an open source project and any contributions which improve the project are encouraged.\nFeel free to make a pull request for any contributions that you would like to see merged into the project.\n\nAfter cloning the source from this repo, run `rake test` to build the C++ extension and run the reactor and precision tests.\n\nSome ways that you can contribute include:\n- Create new [bug reports](https://github.com/bawNg/actuator/issues/new)\n- Reviewing and providing detailed feedback on existing [issues](https://github.com/bawNg/actuator/issues/new)\n- Writing and improving documentation\n- Writing additional tests\n- Implementing new features\n\n#### License\n\nActuator is released under the [MIT License](https://opensource.org/licenses/MIT).","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbawng%2Factuator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbawng%2Factuator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbawng%2Factuator/lists"}