Welcome to Actuator

Code: https://github.com/bawNg/actuator \ Bugs: https://github.com/bawNg/actuator/issues

Actuator provides high precision scheduling of light weight timers for async and fibered real-time Ruby applications. Even on Windows where kernel precision is lower, average timer accuracy is ~2 us on modern high end hardware (subject to system load).

This C++ Ruby extension allows time-sensitive applications to replace native threads with jobs that run in pooled fibers.

This is an alpha release, not recommended for production use. While fairly well tested on Windows and Linux, minimal safety and error handling has been implemented in order to minimize overhead. Using the API wrong may result in a segfault.

Features

• Provides a high precision float representing the current reactor time
• High precision single threaded timer callback scheduling
• Light weight jobs can be used to replace threads with pooled fibers
• Job-based implementation of sleep, join, kill, Mutex and ConditionVariable
• Job-aware sample-based CPU profiling API and execution time warnings
• Warnings for timers that fire later than the configured threshold
• Low overhead timestamped logging API which is thread-safe

Supported platforms

• MRI Ruby 2.x (1.9 is probably compatible but has not been tested).
• High precision timer support is implemented for Windows, Linux and OSX.

Getting started

Install the gem with gem install actuator or by adding it to your bundle.

  require 'actuator'

  Actuator.run do
    # Schedule a once off timer which fires after 500 us delay
    Timer.in 0.0005 do
      Log.puts "Reactor time: #{Actuator.now}"
    end
    # Schedule a repeating timer which fires every 50ms
    Timer.every 0.05 do
      Log.puts "50ms have passed"
    end
    # Schedule a timer which we will cancel before it expires
    timer = Timer.in 0.005 do
      Log.warn "This should never be printed"
    end
    # Create a new job which executes inside a pooled fiber
    job1 = Actuator.defer do
      begin
        Log.puts "Job has started"
        # Yield from the job fiber for 200ms
        Job.sleep 0.2
        Log.warn "Job 1 finished sleeping even though it should have been killed"
      ensure
        # The stack is unwound when a job is killed so ensure blocks are executed
        Log.puts "Job 1 is ending"
      end
    end
    # Create another new job
    job2 = Actuator.defer do
      # Yield from job fiber until job1 ends
      job1.join
      Log.puts "Job 2 finished waiting for Job 1"
    end
    Job.sleep 0.001
    # Cancel the 5ms timer that we scheduled above
    timer.destroy
    Job.sleep 0.1
    # Kill job1 before it finishes sleeping
    job1.kill
    # Wait for job2 to end naturally
    job2.join
    Log.puts "Job 2 has ended"
    # Shutdown the reactor
    Actuator.stop
  end

Known issues

• Memory for active timers will not be freed when calling Actuator.stop
• The profiling API will include time spent yielded from the job. The job-aware implementation has been commented out to reduce overhead until the profiling has been rewritten in C++.
• Minimal safety checks and error handling has been implemented in order to minimize overhead. Using the API wrong may result in a segfault. Feel free to open a bug report for any such cases that you may come across.

Contributing

Actuator is an open source project and any contributions which improve the project are encouraged. Feel free to make a pull request for any contributions that you would like to see merged into the project.

After cloning the source from this repo, run rake test to build the C++ extension and run the reactor and precision tests.

Some ways that you can contribute include:

• Create new bug reports
• Reviewing and providing detailed feedback on existing issues
• Writing and improving documentation
• Writing additional tests
• Implementing new features

License

Actuator is released under the MIT License.