gnomon 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 991d919e3c0f3196568199c69f36ced61f8f9213
+  data.tar.gz: 10bf4317d05abb7f974f5ab70d16f80042a0188c
+SHA512:
+  metadata.gz: 48bd31e3ff530439e32fdaaee93c9c9577584ec85e20d0645070cbf6794fd9a803a088bfad4c352153d039368b9cfae8eb68340cd9a490f4ef6be37fff0d2d92
+  data.tar.gz: 4ba79e9a4fa976dca8ed416ddaca6ff0a8646f9b441a23aa2f63a95c21e8536e2d5269b41b257831820b93acb78560c9ea61e8c5f24102eeaa1e2973d0127fb8

data/.gitignore

@@ -0,0 +1,3 @@
+.idea
+Gemfile.lock
+pkg

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Paul Duncan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,175 @@
+# Gnomon
+
+Simple event scheduling for Ruby
+
+## Presentation
+
+This library provides an easy-to-use event scheduler for Ruby.
+This allows easy development of asynchronous time-based triggers.
+Both intervals and points are available for scheduling.
+
+## Installation
+
+### Gemfile
+```ruby
+gem 'gnomon'
+```
+
+### Terminal
+```bash
+gem install -V gnomon
+```
+
+## Usage
+
+### Introduction
+
+First, a *Gnomon* scheduler should be created:
+
+```ruby
+require 'gnomon'
+sched = Gnomon.new
+```
+
+### Managing the scheduler
+
+The scheduler itself is a simple [Runify](https://rubygems.org/gems/runify) service which can be controlled via the typical methods (_startup_, _shutdown_, _restart_).
+
+```ruby
+sched.startup			# Start the Scheduler Service
+sched.restart			# Re-Start the Scheduler Service
+sched.shutdown			# Stop the Scheduler Service
+```
+
+Events can then be scheduled by using either the _schedule_ generic method, or one of the three shortcut methods _schedule_at_, _schedule_in_, _schedule_every_.
+
+All four methods take an _id_ argument, which can be used to later de-schedule an event (or a group of events).
+
+Each method also accepts a _block_, which will be executed when the event triggers.
+Finally, the _*args_ argument will be passed as-is to the _block_ upon trigger.
+
+Any time an event triggers, a new thread is created around the event's _block_, to which is passed the event's _*args_.
+
+### Granularity
+
+Internally, the scheduler checks the system clock at regular intervals, and compares the next event in the queue to determine whether it's time to trigger.
+This means that the scheduler has an inherent "minimal time resolution" - events can not be triggered at smaller intervals than this minimum resolution.
+So why not set this directly to an infinitesimal value? Simply because the scheduler would basically spend most of its time (and the host's CPU cycles) just checking the system clock.
+
+By default, the granularity is set to *1 second*, which is fine for most usages.
+For sub-second scheduling (or very wide scheduling), the granularity can be set to any value by passing it as argument to the constructor:
+
+```ruby
+require 'gnomon'
+sched_ms = Gnomon.new 0.001		# Create a Scheduler with milli-second granularity
+sched_h = Gnomon.new 3600		# Create a Scheduler with hour granularity
+```
+
+### Scheduling events
+
+#### *schedule* _id_, _mode_, _mode_options_, _timespec_, _*args_, _&block_
+
+The _mode_ argument can be one of the following:
+* *:at*    -> Trigger the event _once_ at a given date/time (provided by the _timespec_ argument)
+* *:in*    -> Trigger the event _once_ after a certain amount of time has passed (provided by the _timespec_ argument)
+* *:every* -> Trigger the event _periodically_ at regular intervals (provided by the _timespec_ argument)
+
+Any event scheduled in *:at* or *:in* mode will trigger only once, and is _automatically de-scheduled_ after triggering.
+
+The shortcut methods presented below do not perform anything other than call the _schedule_ method with the correct _mode_ argument set.
+
+#### *schedule_at* _id_, _date_time_, _*args_, _&block_
+
+The _schedule_at_ method schedules _&block_ to be run *once*, at exactly _date_time_, which can be any string representation of a date/time.
+
+#### *schedule_in* _id_, _time_, _*args_, _&block_
+
+The _schedule_in_ method schedules _&block_ to be run *once*, in exactly _time_ seconds.
+
+#### *schedule_every* _id_, _interval_, _async_, _*args_, _&block_
+
+The _schedule_every_ method schedules _&block_ to be run *periodically*, once every _interval_ seconds.
+The _async_ argument determines when the next run is scheduled for each run:
+* *async = true* -> The next trigger is scheduled *as soon as the event triggers* (before running the event's _block_).
+* *async = false* -> The next trigger is scheduled *as soon as the event _block_ completes*.
+
+### De-scheduling events
+
+Previously-scheduled events can be de-scheduled through the _deschedule_ method, by specifying the *id* used during initial scheduling of the event.
+An optional _keep_running_ argument can be set to true to indicate that any "next scheduled trigger" should remain in the event queue.
+
+## Examples
+
+### Basic scheduling
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'gnomon'
+
+# Create Scheduler
+sched = Gnomon.new
+
+# Events can be scheduled before running the scheduler
+sched.schedule_at(nil, "April 1 2000 10:00 AM") { puts 'April fool\'s day!' }
+
+# Start Scheduler
+sched.startup
+
+# Events can be scheduled while the scheduler is running
+sched.schedule_in(nil, 5.5) { puts 'Five and half seconds have passed :)' }
+sched.schedule_every(nil, 0.1, false) { puts 'Refreshing something...' }
+
+# Do something while scheduler is running...
+
+# Shutdown Scheduler
+sched.shutdown
+```
+
+### Self-de-scheduling event
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'gnomon'
+
+# Create Scheduler
+sched = Gnomon.new
+
+# Start Scheduler
+sched.startup
+
+# Run this every second, but five times only (have the event de-schedule itself after 5 triggers)
+counter = 0
+sched.schedule_every(:foo_task, 1, false) { puts "Run ##{counter}"; sched.deschedule :foo_task if counter >= 5 }
+
+# Shutdown Scheduler
+sched.shutdown
+```
+
+### Passing arguments
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'gnomon'
+
+# Create Scheduler
+sched = Gnomon.new
+
+# Start Scheduler
+sched.startup
+
+# Events can be scheduled while the scheduler is running
+sched.schedule_in(nil, 5.5, 'Hello world!') { |s| puts "Five and half seconds have passed, time to say \"#{s}\"" }
+sched.schedule_in(nil, 10, :users, [:foo, :bar]) { |category, entities| puts "Refreshing #{category}: #{entities.join ', '}" }
+
+# Do something while scheduler is running...
+
+# Shutdown Scheduler
+sched.shutdown
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,9 @@
+require 'rake/testtask'
+require 'bundler/gem_tasks'
+
+Rake::TestTask.new do |t|
+	t.libs << 'test'
+	t.pattern = 'test/**/test*.rb'
+end
+
+task :default => :test

data/gnomon.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'gnomon/version'
+
+Gem::Specification.new do |spec|
+	spec.name = 'gnomon'
+	spec.version = Gnomon::VERSION
+	spec.authors = ['Eresse']
+	spec.email = ['eresse@eresse.net']
+
+	spec.summary = 'Simple event scheduling for Ruby'
+	spec.description = 'Provides a simple, easy-to-use, event scheduler'
+	spec.homepage = 'http://redmine.eresse.net/projects/gnomon'
+	spec.license = 'MIT'
+
+	spec.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+	spec.require_paths = ['lib']
+
+	spec.add_development_dependency 'bundler'
+	spec.add_development_dependency 'rake'
+	spec.add_runtime_dependency 'minitest'
+	spec.add_runtime_dependency 'runify'
+end

data/lib/gnomon.rb

@@ -0,0 +1,148 @@
+# Gnomon
+# by Eresse <eresse@eresse.net>
+
+# Internal Includes
+require 'gnomon/version'
+
+# External Includes
+require 'date'
+require 'thread'
+require 'runify'
+
+# Gnomon Class
+class Gnomon
+
+	# Defaults
+	DEFAULT_GRANULARITY = 1
+
+	# Runify
+	include Runify
+
+	# Construct
+	def initialize granularity = DEFAULT_GRANULARITY
+
+		# Set Granularity
+		@granularity = granularity
+
+		# Create Event Queue
+		@equeue = []
+
+		# Create Event Schedule
+		@esched = []
+
+		# Create Lock
+		@lock = Mutex.new
+	end
+
+	# Schedule Event
+	def schedule id, mode, mode_options, timespec, *args, &block
+
+		# Synchronize
+		@lock.synchronize do
+
+			# Create Event
+			e =  {
+				id: id,
+				ts: timespec,
+				mode: mode,
+				mopt: mode_options,
+				args: args,
+				blck: block
+			}
+
+			# Register Event Scheduling
+			@esched << e
+
+			# Enqueue Next Run
+			enqueue_next_run e
+		end
+	end
+
+	# Schedule Event at a given date/time
+	def schedule_at id, date_time, *args, &block
+		schedule id, :at, {}, date_time, *args, &block
+	end
+
+	# Schedule Event in a given number of seconds
+	def schedule_in id, time, *args, &block
+		schedule id, :in, {}, time, *args, &block
+	end
+
+	# Schedule Event at a given interval (seconds)
+	def schedule_every id, interval, async, *args, &block
+		schedule id, :every, { async: async }, interval, *args, &block
+	end
+
+	# De-schedule
+	def deschedule id, keep_running = false
+
+		# Synchronize
+		@lock.synchronize do
+
+			# De-schedule Event
+			@esched.delete_if { |e| e[:id] == id }
+
+			# De-queue any next run
+			@equeue.delete_if { |e| e[:event][:id] == id } unless keep_running
+		end
+	end
+
+	# Privates
+	private
+
+	# Enqueue Next Run
+	def enqueue_next_run event
+		next_run = next_run event[:mode], event[:ts]
+		pos = @equeue.index { |p| p[:next_run] >= next_run } || 0
+		@equeue.insert pos, { next_run: next_run, event: event }
+	end
+
+	# Determine Next Run
+	def next_run mode, ts
+		case mode
+			when :at
+				DateTime.parse(ts).to_time.to_f
+			when :every
+			when :in
+				Time.at(Time.now.to_f + ts.to_f).to_f
+			else
+				raise "Unknown scheduling mode [#{mode}]"
+		end
+	end
+
+	# Run
+	def run
+		update until @stop
+	end
+
+	# Update
+	def update
+
+		# Synchronize { Trigger Next Event in Queue }
+		@lock.synchronize { trigger @equeue.shift[:event] if @equeue.first && @equeue.first[:next_run] <= Time.now.to_f }
+
+		# Sleep
+		sleep @granularity
+	end
+
+	# Trigger Event
+	def trigger event
+
+		# Spawn Thread around Event's Block
+		Thread.new do
+
+			# De-schedule non-periodic events
+			@esched.delete event unless event[:mode] == :every
+			@equeue.delete_if { |e| e[:event] == event } unless event[:mode] == :every
+
+			# Enqueue next run BEFORE calling block for asynchronous periodic events
+			enqueue_next_run event if event[:mode] == :every && event[:mopt][:async]
+
+			# Pass Event Args to Event Block
+			event[:blck].call *(event[:args])
+
+			# Enqueue next run AFTER calling block for synchronous periodic events
+			enqueue_next_run event if event[:mode] == :every && !(event[:mopt][:async])
+		end
+	end
+end

data/lib/gnomon/version.rb

@@ -0,0 +1,9 @@
+# Gnomon
+# by Eresse <eresse@eresse.net>
+
+# Gnomon Class
+class Gnomon
+
+	# Version
+	VERSION = '0.1.0'
+end

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: gnomon
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Eresse
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-01-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: runify
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Provides a simple, easy-to-use, event scheduler
+email:
+- eresse@eresse.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- gnomon.gemspec
+- lib/gnomon.rb
+- lib/gnomon/version.rb
+homepage: http://redmine.eresse.net/projects/gnomon
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.10
+signing_key: 
+specification_version: 4
+summary: Simple event scheduling for Ruby
+test_files: []