gamelan 0.3

data/README.rdoc

@@ -0,0 +1,27 @@
+= Gamelan
+
+Gamelan is a good-enough soft real-time event scheduler especially for music
+applications. It exposes a simple API for executing Ruby code at a required
+time. Uses include sending MIDI or OSC messages to external applications or
+hardware.
+
+Gamelan also makes life easier by supporting logical time. Logical time is
+reflected in the scheduler's phase. The unit in logical time is the beat, and
+the Scheduler's phase will increment by 1.0 with every beat.
+
+Logical time varies with real time according to the tempo, which is specified
+in bpm. For example, the Scheduler's phase will increment by 2.0 for every
+second that elapses when using the default tempo of 120bpm. Applications are
+free to alter the tempo at any time, including from within tasks.
+
+= Notes
+
+The author admits that Ruby is not at all friendly to realtime applications.
+No guarantees are made about the scheduler's performance. It will not drift
+(it will always stay in sync with the system clock), but jitter is inevitable.
+This is minimized by using a hybrid spinlock implementation to wait between
+dispatches, and by using a reasonably efficient priority queue to store Tasks.
+
+The design is an elaboration of Topher Cyll's Timer implementation from his
+book, <em>Practical Ruby Projects</em>, and the Priority Queue implementation
+comes from Brian Amberg.

data/lib/gamelan.rb

@@ -0,0 +1,15 @@
+# Gamelan is a good-enough soft real-time event scheduler, 
+# written in Ruby, especially for music applications.
+#
+# Copyright (c) 2008 Jeremy Voorhis <jvoorhis@gmail.com>
+#
+# This code released under the terms of the MIT license.
+
+def jruby?
+  defined?(JRUBY_VERSION)
+end
+
+require 'rubygems'
+require 'gamelan/scheduler'
+require 'gamelan/task'
+

data/lib/gamelan/queue.rb

@@ -0,0 +1,56 @@
+module Gamelan
+
+  if jruby?
+    
+    class Queue
+      include Java
+      include_package 'java.util.concurrent'
+      
+      def initialize(sched)
+        @scheduler = sched
+        comparator = lambda { |a,b| a.delay <=> b.delay }
+        @queue     = PriorityBlockingQueue.new(10000, &comparator)
+        @lock      = Mutex.new
+      end
+      
+      def push(task)
+        @lock.synchronize { @queue.add(task) }
+      end
+      alias << push
+      
+      def pop
+        @lock.synchronize { @queue.remove }
+      end
+      
+      def ready?
+        @queue.peek && @queue.peek.delay < @scheduler.phase
+      end
+    end
+    
+  else
+    
+    require 'priority_queue/c_priority_queue'
+    require 'priority_queue'
+    
+    class Queue
+      def initialize(sched)
+        @scheduler = sched
+        @queue     = ::PriorityQueue.new
+      end
+      
+      def push(task)
+        @queue.push(task, task.delay)
+      end
+      alias << push
+      
+      def pop
+        @queue.delete_min[0]
+      end
+      
+      def ready?
+        @queue.min && @queue.min[1] < @scheduler.phase
+      end
+    end
+
+  end
+end

data/lib/gamelan/scheduler.rb

@@ -0,0 +1,28 @@
+require 'gamelan/timer'
+require 'gamelan/queue'
+
+module Gamelan
+  # The scheduler allows the user to schedule tasks, represented by +Gamelan::Task+.
+  class Scheduler < Timer
+    
+    # Construct a new scheduler. +Scheduler#run+ must be called explicitly once a Scheduler is created. Accepts two options, +:tempo+ and +:rate+.
+    # [+:tempo+] The tempo's scheduler, in bpm. For example, at +:tempo => 120+, the scheduler's logical +phase+ will advance by 2.0 every 60 seconds.
+    # [+:rate+]  Frequency in Hz at which the scheduler will attempt to run ready tasks. For example, The scheduler will poll for tasks 100 times in one
+    #            second when +:rate+ is 100.
+    def initialize(options = {})
+      super
+      @queue     = Gamelan::Queue.new(self)
+    end
+    
+    # Schedule a task to be performed at +delay+ beats.
+    def at(delay, *params, &task)
+      @queue << Task.new(self, delay.to_f, *params, &task)
+    end
+    
+    protected
+      # Run all ready tasks.
+      def dispatch
+        @queue.pop.run while @queue.ready?
+      end
+  end
+end

data/lib/gamelan/task.rb

@@ -0,0 +1,25 @@
+require 'forwardable'
+
+module Gamelan
+
+  # Tasks run by the Scheduler. A task is a combination of a block to be
+  # run, a delay, in beats, that specifies when to run the Task, and an
+  # optional list of args. A reference to the Scheduler is also stored, so it
+  # can be manipulatd by tasks.
+  class Task
+    extend Forwardable
+    def_delegators :@scheduler, :at, :phase, :rate, :time
+    attr_reader :delay, :args, :scheduler
+    
+    # Construct a Task with a Scheduler reference, a delay in beats, an
+    # optional list of args, and a block.
+    def initialize(sched, delay, *args, &block)
+      @scheduler, @delay, @proc, @args = sched, delay, block, args
+    end
+    
+    # The scheduler will invoke Task#run is called with the Task's +delay+ at
+    # the scheduled time. Any optional +args+, if given, will follow.
+    # are yielded to the block.
+    def run; @proc[@delay, *@args] end
+  end
+end

data/lib/gamelan/timer.rb

@@ -0,0 +1,62 @@
+module Gamelan
+  # The Timer is responsible for executing code at a fixed rate. Users must
+  # subclass +Gamelan::Timer+. See +Gamelan::Scheduler+ for an example.
+  class Timer
+    attr_reader :phase, :rate, :time
+    
+    # Construct a new timer. +Timer#run+ must be called explicitly once a Timer
+    # is created. Accepts two options, +:tempo+ and +:rate+.
+    # [+:tempo+] The timer's tempo, in bpm. For example, at +:tempo => 120+,
+    # the timer's logical +phase+ will advance by 2.0 every 60 seconds.
+    # [+:rate+]  Frequency in Hz at which the scheduler will dispatch.
+    def initialize(options = {})
+      self.tempo = options.fetch(:tempo, 120)
+      @rate      = 1.0 / options.fetch(:rate, 1000)
+      @sleep_for = rate / 10.0
+    end
+    
+    # Initialize the scheduler's clock, and begin executing tasks.
+    def run
+      return if @running
+      @running  = true
+      @thread   = Thread.new do
+        @phase  = 0.0
+        @origin = @time = Time.now.to_f
+        loop { dispatch; advance }
+      end
+    end
+    
+    # Halt the scheduler. Note that the scheduler may be restarted, but is
+    # not resumable.
+    def stop
+      @running = false
+      @thread.kill
+    end
+    
+    # Current tempo, in bpm.
+    def tempo
+      @tempo * 60.0
+    end
+    
+    # Set the tempo in bpm.
+    def tempo=(bpm)
+      @tempo = bpm / 60.0
+    end
+
+    def join; @thread.join end
+    
+    private
+      # Advances the internal clock time and spins until it is reached.
+      def advance
+        @time   += @rate
+        @phase  += (@time - @origin) * @tempo
+        @origin  = @time
+        sleep(@sleep_for) until Time.now.to_f >= @time
+      end
+      
+      # Run all ready tasks.
+      def dispatch
+        raise NotImplementedError, "subclass responsibility"
+      end
+  end
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification 
+name: gamelan
+version: !ruby/object:Gem::Version 
+  version: "0.3"
+platform: ruby
+authors: 
+- Jeremy Voorhis
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-01-21 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: PriorityQueue
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.1.2
+    version: 
+description: 
+email: jvoorhis@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- lib/gamelan/queue.rb
+- lib/gamelan/scheduler.rb
+- lib/gamelan/task.rb
+- lib/gamelan/timer.rb
+- lib/gamelan.rb
+- README.rdoc
+has_rdoc: true
+homepage: http://github.com/jvoorhis/gamelan
+post_install_message: 
+rdoc_options: 
+- --title
+- Gamelan
+- --main
+- README.rdoc
+- --line-numbers
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: gamelan
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Gamelan is a good-enough soft real-time event scheduler, written in Ruby, especially for music applications.
+test_files: []
+