psched 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 58946f4a0c8a49837d18022f99a4f98c99cf3117
+  data.tar.gz: c1d675d5dba069199d49420407694171855261e1
+SHA512:
+  metadata.gz: 47cbf71e0f1f5c47c58980105761bfd0d65dd68a3d9b1fe39f5b54efbbe4ec7e72b10d897e9151bcee797c24319653b916b1a8de07591ac0d8473cb9f2e7c103
+  data.tar.gz: a0e0a9d007693cda71f86ae85b8c6280f4fc873fa2f4288520e9382d25eaae0682b532dda4c77a1dbf58824d2b009bceb1d76c3f680172bb56e73fada7b62d69

data/.document

@@ -0,0 +1,3 @@
+- 
+ChangeLog.md
+LICENSE.txt

data/.gitignore

@@ -0,0 +1,6 @@
+/.bundle
+/.yardoc/
+/Gemfile.lock
+/doc/
+/pkg/
+/vendor/cache/*.gem

data/.rspec

@@ -0,0 +1 @@
+--colour --format documentation

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown --title "psched Documentation" --protected

data/ChangeLog.md

@@ -0,0 +1,4 @@
+### 0.1.0 / 2017-12-13
+
+* Initial release:
+

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'kramdown'
+end

data/LICENSE.txt

@@ -0,0 +1,23 @@
+Copyright (c) 2017, Paolo Bosetti
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,44 @@
+# psched
+
+- [Homepage](https://rubygems.org/gems/psched)
+- [Documentation](http://rubydoc.info/gems/psched/frames)
+- [Email](mailto:paolo.bosetti at unitn.it)
+
+## Description
+
+TODO: Description
+
+## Features
+
+TODO: Features
+
+## Examples
+
+    require 'psched'
+    op = PSched::Operation.new(0.5)
+    op.start(10) do |i|
+      puts "Ping #{i}"
+    end
+
+    Signal.trap("SIGINT") do
+      print "Stopping recurring process..."
+      op.stop
+      puts "done!"
+    end
+
+    sleep(0.2) while op.active?  # waits for scheduling to complete
+
+## Requirements
+FFI gem and an OS supporting semaphores.
+
+## Install
+
+```
+$ gem install psched
+```
+
+## Copyright
+
+Copyright (c) 2017 Paolo Bosetti
+
+See {file:LICENSE.txt} for details.

data/Rakefile

@@ -0,0 +1,25 @@
+# encoding: utf-8
+
+require 'rubygems'
+
+begin
+  require 'bundler/setup'
+rescue LoadError => e
+  abort e.message
+end
+
+require 'rake'
+
+
+require 'rubygems/tasks'
+Gem::Tasks.new
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+
+task :test    => :spec
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new  
+task :doc => :yard

data/lib/psched/version.rb

@@ -0,0 +1,4 @@
+module Psched
+  # psched version
+  VERSION = "0.1.0"
+end

data/lib/psched.rb

@@ -0,0 +1,192 @@
+#!/usr/bin/env ruby
+# psched.rb
+
+# Created by Paolo Bosetti on 2011-04-21.
+# Copyright (c) 2011 University of Trento. All rights reserved.
+
+require 'ffi'
+require 'psched/version'
+
+
+# A module and a class ({PSched::Operation}) for implementing a recurring
+# call as deterministic as possible.
+#
+# See {PSched::Operation} for usage details. Module functions are FFI
+# wrappers and are not intended to be used directly.
+# @author Paolo Bosetti
+# @todo Are there better ways?
+module PSched
+  extend FFI::Library
+  ffi_lib FFI::Library::LIBC
+  # @!method ualarm(useconds, interval)
+  #   The `ualarm()` function waits a count of useconds before asserting the
+  #   terminating signal `SIGALRM`.  System activity or time used in processing
+  #   the call may cause a slight delay.
+  #   If the interval argument is non-zero, the `SIGALRM` signal will be sent to
+  #   the process every interval microseconds after the timer expires
+  #   (e.g.,after useconds number of microseconds have passed).
+  #   @param [Fixnum] useconds initial delay in microseconds
+  #   @param [Fixnum] interval recurring interval in microseconds
+  #   @return [Fixnum] the amount of time left on the clock
+  attach_function :ualarm, [:uint, :uint], :uint
+
+  # @!method alarm(seconds)
+  #   Set a timer to deliver the signal `SIGALRM` to the calling process after
+  #   the specified number of seconds
+  #   @param [Fixnum] seconds delay in microseconds
+  #   @return [Fixnum] the amount of time left on the clock from a previous
+  #                    call to alarm()
+  attach_function :alarm, [:uint], :uint
+
+  enum :which, [
+    :prio_process,	0,
+    :prio_pgrp,
+    :prio_user,
+    :prio_darwin_thread,
+    :prio_darwin_process
+  ]
+
+  # @!method setpriority(which, who, prio)
+  #   Set the scheduling priority of the current process
+  #   @param [Fixnum] which The type of priority, as for the enum `which`
+  #   @param [Fixnum] who The process, group, user or thread
+  #   @param [Fixnum] prio The priority level, from -20 to 20
+  #   @return [0|-1] 0 if no error, -1 if error
+  attach_function :setpriority, [:which, :uint, :int], :int
+
+  # Implements a recurring operation.
+  # @example General usage. Note the `sleep` call.
+  #   op = PSched::Operation.new(0.5)
+  #   op.start(10) do |i|
+  #     puts "Ping #{i}"
+  #   end
+  #
+  #   Signal.trap("SIGINT") do
+  #     print "Stopping recurring process..."
+  #     op.stop
+  #     puts "done!"
+  #   end
+  #
+  #   sleep(0.2) while op.active?  # THIS IS IMPORTANT!!!
+  #
+  # @author Paolo Bosetti
+  class Operation
+    # Changes scheduling priority of the current process
+    # @param [Fixnum] nice sets the nice level (-20..+20)
+    # @todo better return message and error management
+    def self.prioritize(nice = -20)
+      result = PSched.setpriority(:prio_process,0,nice)
+      puts "Setting max priority: #{result == 0 ? 'success' : 'failure (missing sudo?)'}"
+    end
+
+    # @!attribute [rw] strict_timing
+    #   If true, raise a {RealTimeError} when `TET >= step`
+    #   (default to `false`)
+    attr_accessor :strict_timing
+
+    # @!attribute [r] tet
+    #   The Task Execution Time
+    # @!attribute [r] step
+    #   The time step in seconds
+    attr_reader :step, :tet
+    # Initializer
+    # @param [Numeric] step the timestep in seconds
+    def initialize(step)
+      @step          = step
+      @active        = false
+      @lock          = false
+      @strict_timing = false
+      @tet           = 0
+    end
+
+    # Sets the time step (in seconds) and reschedule pending alarms.
+    # @param [Numeric] secs Timestep in seconds
+    def step=(secs)
+      @step = secs
+      self.schedule
+    end
+
+    # Updates scheduling of pending alarms.
+    # @note Usually, there's no need to call this, since {#step=} automatically
+    #       calls it after having set the +@step+ attribute.
+    def schedule
+      usecs = @step * 1E6
+      PSched::ualarm(usecs, usecs)
+    end
+
+    # Tells id the recurring operation is active or not.
+    # @return [Boolean] the status of the recurring alarm operation
+    def active?; @active; end
+
+    # Starts a recurring operation, described by the passed block.
+    # If the block returns the symbol :stop, the recurrin operation gets
+    # disabled.
+    # @param [Fixnum,nil] n_iter the maximum number of iterations.
+    #   If nil it loops indefinitedly
+    # @yieldparam [Fixnum] i the number of elapsed iterations
+    # @yieldparam [Numeric] tet the Task Execution Time of previous step
+    # @raise [ArgumentError] unless a block is given
+    # @raise [RealTimeError] if TET exceeds @step
+    def start(n_iter=nil)
+      @active = true
+      i = 0
+      raise ArgumentError, "Need a block!" unless block_given?
+      Signal.trap(:ALRM) do
+        # If there is still a pending step, raises an error containing
+        # information about the CURRENT step
+        if @lock then
+          if @strict_timing
+            @lock = false
+            raise RealTimeError.new({:tet => @tet, :step => @step, :i => i, :time => Time.now})
+          end
+        else
+          start = Time.now
+          @lock = true
+          result = yield(i, @tet)
+          i += 1
+          self.stop if (n_iter and i >= n_iter)
+          self.stop if (result.kind_of? Symbol and result == :stop)
+          @tet = Time.now - start
+          @lock = false
+        end
+      end
+      self.schedule
+    end
+
+    # Stops the recurring process by resetting alarm and disabling management
+    # of `SIGALRM` signal.
+    def stop
+      PSched::ualarm(0, 0)
+      Signal.trap(:ALRM, "DEFAULT")
+      @active = false
+      @lock = false
+    end
+  end
+end
+
+class RealTimeError < RuntimeError
+  attr_reader :status
+  def initialize(status)
+    @status = status
+  end
+  def ratio
+    (@status[:tet] / @status[:step]) * 100
+  end
+end
+
+if $0 == __FILE__ then
+  PSched::Operation.prioritize
+
+  op = PSched::Operation.new(0.01)
+  op.start(10) do |i|
+    puts "Ping #{i}"
+  end
+
+  Signal.trap("SIGINT") do
+    print "Stopping recurring process..."
+    op.stop
+    puts "done!"
+  end
+
+  sleep while op.active?
+end

data/psched.gemspec

@@ -0,0 +1,38 @@
+# -*- encoding: utf-8 -*-
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'psched/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "psched"
+  gem.version       = Psched::VERSION
+  gem.summary       = %q{Precise scheduling of recurring tasks}
+  gem.description   = %q{Precise scheduling of recurring tasks using semaphores (not supported on Windows!)}
+  gem.license       = "0BSD"
+  gem.authors       = ["Paolo Bosetti"]
+  gem.email         = "paolo.bosetti@unitn.it"
+  gem.homepage      = "https://rubygems.org/gems/psched"
+
+  gem.files         = `git ls-files`.split($/)
+
+  `git submodule --quiet foreach --recursive pwd`.split($/).each do |submodule|
+    submodule.sub!("#{Dir.pwd}/",'')
+
+    Dir.chdir(submodule) do
+      `git ls-files`.split($/).map do |subpath|
+        gem.files << File.join(submodule,subpath)
+      end
+    end
+  end
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ['lib']
+  gem.add_dependency 'ffi', '~>1.9'
+
+  gem.add_development_dependency 'bundler', '~> 1.10'
+  gem.add_development_dependency 'rake', '~> 10.0'
+  gem.add_development_dependency 'rspec', '~> 3.0'
+  gem.add_development_dependency 'rubygems-tasks', '~> 0.2'
+  gem.add_development_dependency 'yard', '~> 0.8'
+end

data/spec/psched_spec.rb

@@ -0,0 +1,8 @@
+require 'spec_helper'
+require 'psched'
+
+describe Psched do
+  it "should have a VERSION constant" do
+    expect(subject.const_get('VERSION')).to_not be_empty
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,4 @@
+require 'rspec'
+require 'psched/version'
+
+include Psched

metadata

@@ -0,0 +1,144 @@
+--- !ruby/object:Gem::Specification
+name: psched
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Paolo Bosetti
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-12-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubygems-tasks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+description: Precise scheduling of recurring tasks using semaphores (not supported
+  on Windows!)
+email: paolo.bosetti@unitn.it
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".document"
+- ".gitignore"
+- ".rspec"
+- ".yardopts"
+- ChangeLog.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/psched.rb
+- lib/psched/version.rb
+- psched.gemspec
+- spec/psched_spec.rb
+- spec/spec_helper.rb
+homepage: https://rubygems.org/gems/psched
+licenses:
+- 0BSD
+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.13
+signing_key: 
+specification_version: 4
+summary: Precise scheduling of recurring tasks
+test_files:
+- spec/psched_spec.rb
+- spec/spec_helper.rb