actuator 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 459b67293c89bd2854e96adbaf484ec950774fc2
+  data.tar.gz: cdea3e412329800ae7d1553fae14dd509a0c03cc
+SHA512:
+  metadata.gz: 0b25766398cac34c1ec62b3ac959381850517afcae1cbbd4b59ef7cd8a67b1c0e3de2bcae698007023a47cec6711a1e523c8b1824a0fc000147c42efb6a981b8
+  data.tar.gz: c9972bc77b4e58b94ca2c74367aa1cf116629cf5b916c7a41de5623320ffb2c76dabcff0f856f01296410e87dd609839c143a1e4b6b144e9db7f1ff418a6ed75

data/.autotest

@@ -0,0 +1,13 @@
+# -*- ruby -*-
+
+require "autotest/restart"
+
+Autotest.add_hook :initialize do |at|
+  at.add_mapping(/.*\.c/) do |f, _|
+    at.files_matching(/test_.*rb$/)
+  end
+end
+
+Autotest.add_hook :run_command do |at|
+  system "rake clean compile"
+end

data/History.txt

@@ -0,0 +1,3 @@
+=== 0.0.1 / 2018-01-23
+
+* Initial alpha release. Simple and efficient high precision timer scheduling implemented in C++.

data/Manifest.txt

@@ -0,0 +1,28 @@
+.autotest
+README.md
+History.txt
+Manifest.txt
+Rakefile
+lib/actuator.rb
+lib/actuator/fiber.rb
+lib/actuator/fiber_pool.rb
+lib/actuator/job.rb
+lib/actuator/mutex.rb
+lib/actuator/mutex/replace.rb
+ext/actuator/extconf.rb
+ext/actuator/actuator.h
+ext/actuator/actuator.c
+ext/actuator/clock.h
+ext/actuator/clock.c
+ext/actuator/debug.h
+ext/actuator/debug.c
+ext/actuator/ruby_helpers.h
+ext/actuator/ruby_helpers.c
+ext/actuator/reactor.h
+ext/actuator/reactor.cpp
+ext/actuator/timer.h
+ext/actuator/timer.cpp
+ext/actuator/log.h
+ext/actuator/log.cpp
+test/setup_test.rb
+test/test_actuator.rb

data/README.md

@@ -0,0 +1,105 @@
+## 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.
+
+  ```ruby
+  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](https://github.com/bawNg/actuator/issues/new)
+- Reviewing and providing detailed feedback on existing [issues](https://github.com/bawNg/actuator/issues/new)
+- Writing and improving documentation
+- Writing additional tests
+- Implementing new features
+
+#### License
+
+Actuator is released under the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,23 @@
+# -*- ruby -*-
+
+require "rubygems"
+require "hoe"
+require 'rake/extensiontask'
+
+Hoe.plugin :clean
+
+Hoe.spec "actuator" do
+  developer 'bawNg', 'bawng@intoxicated.co.za'
+  license 'MIT'
+  self.urls = 'https://github.com/bawNg/actuator'
+
+  self.extra_dev_deps << ['rake-compiler', '>= 0']
+  self.extra_dev_deps << ['minitest', '>= 0']
+  self.spec_extras = { extensions: ['ext/actuator/extconf.rb'] }
+
+  Rake::ExtensionTask.new('actuator', spec) do |ext|
+    ext.lib_dir = File.join('lib', 'actuator')
+  end
+end
+
+Rake::Task[:test].prerequisites << :clean << :compile

data/ext/actuator/actuator.c

@@ -0,0 +1,2 @@
+#include <ruby.h>
+#include "actuator.h"

data/ext/actuator/actuator.h

@@ -0,0 +1,16 @@
+#ifndef ACTUATOR_H
+#define ACTUATOR_H
+
+#include "clock.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+extern VALUE ActuatorClass;
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

data/ext/actuator/clock.c

@@ -0,0 +1,81 @@
+#include <stdint.h>
+#include "clock.h"
+#include "debug.h"
+
+#if !defined(__APPLE__) && !defined(_WIN32)
+#define HAVE_POSIX_TIMER
+#include <time.h>
+#ifdef CLOCK_MONOTONIC
+#define CLOCKID CLOCK_MONOTONIC
+#else
+#define CLOCKID CLOCK_REALTIME
+#endif
+#endif
+
+#ifdef __APPLE__
+#define HAVE_MACH_TIMER
+#include <mach/mach_time.h>
+#endif
+
+#if defined(_WIN32) || defined(_MSC_VER)
+#define HAVE_WIN32_TIMER
+#include <windows.h>
+
+#ifdef _MSC_VER
+#include <Strsafe.h>
+#endif
+#endif
+
+static uint64_t last_count;
+static uint64_t frequency;
+
+void clock_init()
+{
+#ifdef HAVE_POSIX_TIMER
+    struct timespec freq, time;
+    clock_getres(CLOCKID, &freq);
+    clock_gettime(CLOCKID, &time);
+    frequency = 1000000000LL * freq.tv_nsec;
+    last_count = time.tv_sec * 1000000000LL + time.tv_nsec;
+#endif
+#ifdef HAVE_MACH_TIMER
+    mach_timebase_info_data_t frequency_nsec;
+    mach_timebase_info(&frequency_nsec);
+    frequency = 1000000000LL * frequency_nsec.numer / frequency_nsec.denom;
+    last_count = mach_absolute_time();
+#endif
+#ifdef HAVE_WIN32_TIMER
+    {
+        LARGE_INTEGER tmp;
+        QueryPerformanceFrequency(&tmp);
+        frequency = tmp.QuadPart;
+        QueryPerformanceCounter(&tmp);
+        last_count = tmp.QuadPart;
+    }
+#endif
+    //puts("Timer resolution: %g ns", 1e9 / (double)frequency);
+}
+
+double clock_time()
+{
+    uint64_t now;
+    double delta;
+#ifdef HAVE_POSIX_TIMER
+    struct timespec time;
+    clock_gettime(CLOCKID, &time);
+    now = time.tv_sec * 1000000000LL + time.tv_nsec;
+    delta = (now - last_count) / (double)frequency;
+#endif
+#ifdef HAVE_MACH_TIMER
+    now = mach_absolute_time();
+#endif
+#ifdef HAVE_WIN32_TIMER
+    {
+        LARGE_INTEGER tmp;
+        QueryPerformanceCounter(&tmp);
+        now = tmp.QuadPart;
+        delta = (now - last_count) / (double)frequency;
+    }
+#endif
+    return delta;
+}

data/ext/actuator/clock.h

@@ -0,0 +1,15 @@
+#ifndef ACTUATOR_CLOCK_H
+#define ACTUATOR_CLOCK_H
+
+#ifdef __cplusplus
+extern "C"{
+#endif
+
+void clock_init();
+double clock_time();
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

data/ext/actuator/debug.c

@@ -0,0 +1,4 @@
+#include "debug.h"
+
+FILE *debug_file = 0;
+FILE *log_file = 0;

data/ext/actuator/debug.h

@@ -0,0 +1,56 @@
+#ifndef ACTUATOR_DEBUG_H
+#define ACTUATOR_DEBUG_H
+
+#include <stdio.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define DEBUG 0
+
+#ifdef DEBUG
+#define puts(...) do { \
+    fprintf(stdout, __VA_ARGS__); \
+    fprintf(stdout, "\n"); \
+    fflush(stdout); \
+} while (0)
+#else
+#define puts(...)
+#endif
+
+#ifdef DEBUG
+#define debug(...) do { \
+    if (!debug_file) debug_file = fopen("debug.txt", "w"); \
+    fprintf(debug_file, __VA_ARGS__); \
+    fflush(debug_file); \
+} while (0)
+#define DEBUG_LOG(...) do { \
+    if (!debug_file) debug_file = fopen("debug.txt", "w"); \
+    fprintf(debug_file, __VA_ARGS__); \
+    fflush(debug_file); \
+} while (0)
+#else
+#define debug(...)
+#define DEBUG_LOG(...)
+#endif
+
+#define INFO(...) do { \
+    fprintf(log_file, "%010.3f INFO ", clock_time() * 1000); \
+    fprintf(log_file, __VA_ARGS__); \
+    fprintf(log_file, "\n"); \
+    fflush(log_file); \
+} while (0)
+
+#define WARN(...) do { \
+    fprintf(log_file, "%010.3f WARN ", clock_time() * 1000); \
+    fprintf(log_file, __VA_ARGS__); \
+    fprintf(log_file, "\n"); \
+    fflush(log_file); \
+} while (0)
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

data/ext/actuator/extconf.rb

@@ -0,0 +1,5 @@
+require 'mkmf'
+
+$CXXFLAGS += " -std=c++11 "
+
+create_makefile 'actuator/actuator'

data/ext/actuator/log.cpp

@@ -0,0 +1,134 @@
+#include <ruby.h>
+#include "reactor.h"
+
+enum class LogLevel
+{
+    None,
+    Error,
+    Warn,
+    Info,
+    Debug
+};
+
+FILE *Log::debug_file = 0;
+FILE *Log::log_file = 0;
+
+static VALUE LogClass;
+static LogLevel Level = LogLevel::Info;
+
+static void Print(const char *tag, const char *format, va_list args)
+{
+    if (!Log::log_file) return;
+    fprintf(Log::log_file, "%010.3f %s ", clock_time() * 1000, tag);
+    vfprintf(Log::log_file, format, args);
+    fprintf(Log::log_file, "\n");
+    fflush(Log::log_file);
+}
+
+static VALUE Log_Debug(VALUE self, VALUE message)
+{
+    Log::Debug("%s", StringValueCStr(message));
+}
+
+static VALUE Log_Info(VALUE self, VALUE message)
+{
+    Log::Info("%s", StringValueCStr(message));
+}
+
+static VALUE Log_Warn(VALUE self, VALUE message)
+{
+    Log::Warn("%s", StringValueCStr(message));
+}
+
+static VALUE Log_Error(VALUE self, VALUE message)
+{
+    Log::Error("%s", StringValueCStr(message));
+}
+
+static VALUE Log_SetFilePath(VALUE self, VALUE path)
+{
+    if (NIL_P(path)) {
+        Log::log_file = 0;
+    } else if (SYMBOL_P(path) && SYM2ID(path) == rb_intern("stdout")) {
+        Log::log_file = stdout;
+    } else if (RB_TYPE_P(path, T_STRING) && CLASS_OF(path) == rb_cString) {
+        Log::log_file = fopen(rb_id2name(SYM2ID(path)), "w");
+    } else {
+        rb_raise(rb_eRuntimeError, "path must be a string, :stdout or nil");
+    }
+    return Qnil;
+}
+
+static VALUE Log_SetLevel(VALUE self, VALUE level)
+{
+    if (SYMBOL_P(level)) {
+        if (SYM2ID(level) == rb_intern("debug")) {
+            Level = LogLevel::Debug;
+            return Qnil;
+        }
+        if (SYM2ID(level) == rb_intern("info")) {
+            Level = LogLevel::Info;
+            return Qnil;
+        }
+        if (SYM2ID(level) == rb_intern("warn")) {
+            Level = LogLevel::Warn;
+            return Qnil;
+        }
+        if (SYM2ID(level) == rb_intern("error")) {
+            Level = LogLevel::Error;
+            return Qnil;
+        }
+    }
+    rb_raise(rb_eRuntimeError, "level must be :debug, :info, :warn or :error");
+    return Qnil;
+}
+
+void Log::Setup()
+{
+    log_file = stdout;
+
+    LogClass = rb_define_module("Log");
+
+    rb_define_singleton_method(LogClass, "debug", RUBY_METHOD_FUNC(Log_Debug), 1);
+    rb_define_singleton_method(LogClass, "puts", RUBY_METHOD_FUNC(Log_Info), 1);
+    rb_define_singleton_method(LogClass, "warn", RUBY_METHOD_FUNC(Log_Warn), 1);
+    rb_define_singleton_method(LogClass, "error", RUBY_METHOD_FUNC(Log_Error), 1);
+    rb_define_singleton_method(LogClass, "file_path=", RUBY_METHOD_FUNC(Log_SetFilePath), 1);
+    rb_define_singleton_method(LogClass, "level=", RUBY_METHOD_FUNC(Log_SetLevel), 1);
+}
+
+void Log::Debug(const char *format, ...)
+{
+    if (Level < LogLevel::Debug) return;
+    va_list args;
+    va_start(args, format);
+    Print("DEBUG", format, args);
+    va_end(args);
+}
+
+void Log::Info(const char *format, ...)
+{
+    if (Level < LogLevel::Info) return;
+    va_list args;
+    va_start(args, format);
+    Print("INFO", format, args);
+    va_end(args);
+}
+
+void Log::Warn(const char *format, ...)
+{
+    if (Level < LogLevel::Warn) return;
+    va_list args;
+    va_start(args, format);
+    Print("WARN", format, args);
+    va_end(args);
+}
+
+void Log::Error(const char *format, ...)
+{
+    if (Level < LogLevel::Error) return;
+    va_list args;
+    va_start(args, format);
+    Print("ERROR", format, args);
+    va_end(args);
+}