acts_as_service 0.0.2

data/LICENSE

@@ -0,0 +1,20 @@
+# Copyright (c) 2010 Umamibud, Inc.
+#
+# 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.rdoc

@@ -0,0 +1,78 @@
+= acts_as_service
+
+== Overview
+
+A gem that gives you an easy way to make service-like code and spend all your
+effort on actually writing the code to get your job done.
+
+Limitations:
+* one process at a time
+* only been tested while running inside a Rails application
+  (e.g. script/runner MySrv.start). should work if you just specify a pidfile
+  explicitly, but needs a little testing
+* smooth shutdown depends on your work method returning frequently (however
+  long you run without returning from perform_work_chunk is how long it might
+  take for the service to shut down
+
+Allows you to:
+* start, stop, restart your process
+* ensures that only one of each process is running on a given machine (if this
+  is not desired, you can probably hack it or enhance to allow up to N
+  instances if you want
+* implement a method you want called over and over, and when the service is
+  supposed to shut down, it stops calling the method and exits
+* see what the PID is of the process by inspecting the pidfile
+* explicitly shutdown the process from within the service class (but you'll
+  still have to return from perform_work_chunk).
+* initiate shutdown of service externally by either calling MyService.stop or
+  adding 'shutdown' to the PID file.
+* hooks to execute methods after start or before stop
+
+== What to do
+
+require 'acts_as_service' # or add it to your Rails env as a config.gem
+
+  class MyService
+
+    acts_as_service
+
+    def self.perform_work_chunk
+      # do stuff that returns in a short period (e.g. a few seconds or less)
+    end
+
+  end
+
+you can get fancier and specify your process identifier and how long to sleep
+between calls to perform_work_chunk:
+
+  class MyService
+
+    acts_as_service
+
+    def self.service_name
+      "MyAwesomeService"
+    end
+
+    def self.sleep_time
+      5 # seconds
+    end
+
+    def self.perform_work_chunk
+      # do stuff that returns in a short period (e.g. a few seconds or less)
+    end
+
+  end
+
+== Maintaining acts_as_service
+
+Make sure you have jeweler.
+
+To build:
+
+     cd .../acts_as_service
+     rake gemspec
+     rake build
+
+To test:
+
+Sorry, little lazy here. Create a sample service class and letter rip!

data/TODO

@@ -0,0 +1,9 @@
+TODOs
+-----
+
+put things in here that could be worked on
+
+* extricate the gem from needing to run within Rails (maybe nothing to do here,
+  maybe just coming up with different pidfile default path if RAILS_ROOT
+  isn't defined. but including class can always just specify explicit path and
+  should be fine

data/acts_as_service.gemspec

@@ -0,0 +1,46 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{acts_as_service}
+  s.version = "0.0.2"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Brian Percival"]
+  s.date = %q{2010-02-18}
+  s.description = %q{A gem with a mixin to let you turn a class into something that runs like a service,
+which you can MyService.start, MyService.stop, and MyService.restart. It tracks
+its own pid. For now, pretty sure it requires that the class is running inside
+a rails context (e.g. run by script/runner MyService.start), but that could
+probably be changed without too much difficulty.
+}
+  s.email = %q{percivalatumamibuddotcom}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc",
+     "TODO"
+  ]
+  s.files = [
+    "README.rdoc",
+     "acts_as_service.gemspec",
+     "lib/acts_as_service.rb"
+  ]
+  s.homepage = %q{http://github.com/bmpercy/acts_as_service}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Makes it very easy to create a service-like class that's easy to start and stop, taken from work at discovereads.com}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end
+

data/lib/acts_as_service.rb

@@ -0,0 +1,306 @@
+# module that makes it easy to turn a class into a service, giving it methods
+# like stop, start, restart for easy cronjobbage, etc.
+#
+# simply require 'acts_as_service' in your class' file and then call
+# acts_as_service in your class definition, then implement a few required
+# and option methods:
+#  - required:
+#     - self.perform_work_chunk: do a chunk of work that the service is intended
+#                                to do. note that this method should return
+#                                periodically to enable shutdown. alternatively,
+#                                your method /could/ (but not recommended) check
+#                                the status to see if it's set to SHUTTING_DOWN
+#                                and return if so. otherwise, the shutdown
+#                                by this module will not work.
+#
+# - optional:
+#     - self.service_name: return the string name of the service.
+#                          default is the class name (without module prefixes)
+#     - self.service_pid_filename: path to the file that should contain the PID for
+#                                  the process while it's running.
+#                                  default is #{RAILS_ROOT}/tmp/pids/<underscore version of service name>
+#     - self.sleep_time: seconds to sleep between calls to peform_work_chunk
+#                        default: no sleep till brooklyn!
+#     - self.after_start: a hook to run a method after the service is started
+#                         but before first call to perform_work_chunk
+#     - self.before_stop: a hook to run a method before final shutdown (and
+#                         after last run to perform_work_chunk)
+#
+# you can also call self.shutdown() from within your perform_work_chunk
+# code to initiate a shutdown (don't just exit() because there's pidfile
+# cleanup etc. to peform).
+#
+# # my_service.rb:
+# 
+# require 'acts_as_service'
+# 
+# class MyService
+# 
+#   acts_as_service
+# 
+#   # ... define methods
+#
+# end
+#-------------------------------------------------------------------------------
+module ActsAsService
+
+  ACTS_AS_SERVICE_RUNNING = 'running'
+  ACTS_AS_SERVICE_OTHER_RUNNING = 'other running'
+  ACTS_AS_SERVICE_STOPPED = 'stopped'
+  ACTS_AS_SERVICE_SHUTTING_DOWN = 'shutting down'
+  ACTS_AS_SERVICE_PID_NO_PROCESS = 'pid no process'
+
+  def self.included(base)
+    base.extend ClassMethods
+  end
+
+  module ClassMethods
+    # starts the process if it's not already running
+    #---------------------------------------------------------------------------
+    def start
+      begin
+        if _status != ACTS_AS_SERVICE_STOPPED &&
+             _status != ACTS_AS_SERVICE_PID_NO_PROCESS
+
+          puts "#{_display_name} (#{_pid_file_pid}) is already running. Ignoring."
+        else
+          # clean out a stale pid
+          if _status == ACTS_AS_SERVICE_PID_NO_PROCESS
+            puts 'Pid file exists but process is not running. Removing old pid file.'
+            File.delete(_pid_filename)
+          end
+          puts "Starting #{_display_name} (#{_pid})...."
+          puts "Run #{name}.stop to stop\n\n"
+          File.open(_pid_filename, 'w') {|f| f.write(_pid.to_s) }
+          if self.respond_to?(:after_start)
+            after_start
+          end
+          while (_status == ACTS_AS_SERVICE_RUNNING)
+            # only sleep if asked to
+            if self.respond_to?(:sleep_time)
+              sleep sleep_time
+            end
+            perform_work_chunk
+          end
+          puts "Shutting down #{_display_name} (#{_pid})"
+          File.delete(_pid_filename)
+        end
+      # if something happens, dump an error and clean up the pidfile if
+      # it's owned by this process
+      rescue Object => e
+        puts "ERROR: #{e}\n#{e.respond_to?(:backtrace) ? e.backtrace.join("\n  ") : ''}"
+        puts "Exiting (#{_pid})\n"
+        if _process_running?
+          File.delete(_pid_filename)
+        end
+      end
+    end
+
+
+    # stops the process if it's running
+    #---------------------------------------------------------------------------
+    def stop
+      if _status == ACTS_AS_SERVICE_STOPPED
+        puts "#{_display_name} is not running"
+      elsif _status == ACTS_AS_SERVICE_PID_NO_PROCESS
+        puts 'Pid file exists but process is not running. Removing old pid file.'
+        File.delete(_pid_filename)
+      else
+        pid_to_stop = _pid_file_pid
+        puts "Stopping #{_display_name} (#{pid_to_stop})...."
+        shutdown
+        while (_status != ACTS_AS_SERVICE_STOPPED)
+          sleep(1)
+        end
+        puts "#{_display_name} (#{pid_to_stop}) stopped\n"
+      end
+    end
+
+
+    # stops the current service process and runs a new one in the current process
+    #-----------------------------------------------------------------------------
+    def restart
+      stop
+      start
+    end
+
+
+    # initiate shutdown. call this from within perform_work_chunk if the service's
+    # work is done and it should shut down (makes sense for cronjobs, say)
+    #-----------------------------------------------------------------------------
+    def shutdown
+      if self.respond_to?(:before_stop)
+        before_stop
+      end
+      # change the pid file so the original process sees this 'stop' signal 
+      File.open(_pid_filename, 'a') do |f|
+        f.write("\n#{ACTS_AS_SERVICE_SHUTTING_DOWN}")
+      end
+    end
+
+
+    # method for outside consumption of status info. hopefully not
+    # tempting method name for class-writers to conflict with...
+    #---------------------------------------------------------------------------
+    def service_running?
+      _status == ACTS_AS_SERVICE_RUNNING || _status == ACTS_AS_SERVICE_OTHER_RUNNING
+    end
+
+
+    # method for outside consumption of the pid value. hopefully not
+    # tempting method name for class-writers to conflict with...
+    #---------------------------------------------------------------------------
+    def service_pid
+      _pid_file_pid
+    end
+
+
+    #---------------------------------------------------------------------------
+    # helper methods, no real need to access these from client code
+    #---------------------------------------------------------------------------
+
+
+    # fetches the service's name, using class name as default
+    #---------------------------------------------------------------------------
+    def _display_name
+      @@_display_name ||= (respond_to?(:service_name) ?
+                           service_name :
+                           name.split("::").last)
+    end
+
+
+    # returns the pid filename
+    #---------------------------------------------------------------------------
+    def _pid_filename
+      if defined?(@@_pid_filename)
+        return @@_pid_filename
+      end
+
+      if respond_to?(:service_pid_filename)
+        @@_pid_filename = service_pid_filename
+      else
+        @@_pid_filename = File.join(RAILS_ROOT, 'tmp', 'pids',
+                                    "#{_display_name.underscore.gsub(/\s+/, '_')}.pid")
+      end
+      return @@_pid_filename
+    end
+
+
+    # the current status of the service. possible values:
+    #  ACTS_AS_SERVICE_STOPPED        : no service process is running
+    #  ACTS_AS_SERVICE_SHUTTING_DOWN  : process currently shutting down
+    #  ACTS_AS_SERVICE_RUNNING        : the current process is the service process
+    #  ACTS_AS_SERVICE_OTHER_RUNNING  : another pid is running the service
+    #  ACTS_AS_SERVICE_PID_NO_PROCESS : pidfile exists, but no process running
+    #-----------------------------------------------------------------------------
+    def _status
+      _status = nil
+
+      # logic:
+      # if the pid file doesn't exist, it's stopped
+      # otherwise, if 'shutting down', it's shutting down
+      #            or if the pidfile's pid is running, another process is running
+      #            or if the pidfile's pid matches this process, it's running
+      #            otherwise, the pidfile's there but no one's running
+      if !_pid_file_exists?  
+        _status = ACTS_AS_SERVICE_STOPPED
+      elsif Regexp.new(ACTS_AS_SERVICE_SHUTTING_DOWN) =~ _pid_file_content
+        _status = ACTS_AS_SERVICE_SHUTTING_DOWN
+      elsif _process_running?
+        _status = ACTS_AS_SERVICE_RUNNING
+      elsif _pid_file_process_running?
+        _status = ACTS_AS_SERVICE_OTHER_RUNNING
+      else
+        _status = ACTS_AS_SERVICE_PID_NO_PROCESS
+      end
+
+      return _status
+    end 
+
+
+    # indicates if the pid file exists for this service
+    #---------------------------------------------------------------------------
+    def _pid_file_exists?
+      File.exist?(_pid_filename)    
+    end
+    
+
+    # returns the entire contents of the pid file
+    #---------------------------------------------------------------------------
+    def _pid_file_content
+      begin
+        f = File.open(_pid_filename, 'r')
+        return f.blank? ? f : f.read
+      rescue Errno::ENOENT
+        return nil
+      end
+    end
+
+
+    # the pid found in the pidfile (if it exists, nil if it doesn't)
+    #---------------------------------------------------------------------------
+    def _pid_file_pid
+      /^(\d*)$/ =~ _pid_file_content
+      return $1.blank? ? nil : $1.to_i
+    end
+
+
+    # the current process' pid
+    #---------------------------------------------------------------------------
+    def _pid
+      @@_pid ||= Process.pid
+    end
+
+
+    # Checks to see if the process pointed to by the pid file is actually
+    # running Note that I couldn't find a good way to check for the status of a
+    # different process by its pid, so this checks to see if the proces has a
+    # process group id, and if the process doesn't exist, an exception is
+    # returned
+    #---------------------------------------------------------------------------
+    def _pid_file_process_running?
+      begin
+        Process.getpgid(_pid_file_pid)
+        return true
+      rescue
+        return false
+      end
+    end
+
+
+    # returns true if the current process is the pid in the pid file. false
+    # otherwise
+    #---------------------------------------------------------------------------
+    def _process_running?
+      return _pid == _pid_file_pid
+    end
+
+  end
+end
+
+# gives us the handy acts_as_service method we can declare inside any class
+#-------------------------------------------------------------------------------
+class Object
+  def self.acts_as_service
+    self.send(:include, ActsAsService)
+  end
+end
+
+
+# totally addicted to blank?
+#-------------------------------------------------------------------------------
+class File
+  def blank?
+    return self.nil?
+  end
+end
+class String
+  def blank?
+    return self.nil? || self == ''
+  end
+end
+class NilClass
+  def blank?
+    return self.nil?
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification 
+name: acts_as_service
+version: !ruby/object:Gem::Version 
+  version: 0.0.2
+platform: ruby
+authors: 
+- Brian Percival
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-02-18 00:00:00 -08:00
+default_executable: 
+dependencies: []
+
+description: |
+  A gem with a mixin to let you turn a class into something that runs like a service,
+  which you can MyService.start, MyService.stop, and MyService.restart. It tracks
+  its own pid. For now, pretty sure it requires that the class is running inside
+  a rails context (e.g. run by script/runner MyService.start), but that could
+  probably be changed without too much difficulty.
+
+email: percivalatumamibuddotcom
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+- TODO
+files: 
+- README.rdoc
+- acts_as_service.gemspec
+- lib/acts_as_service.rb
+- LICENSE
+- TODO
+has_rdoc: true
+homepage: http://github.com/bmpercy/acts_as_service
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+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: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Makes it very easy to create a service-like class that's easy to start and stop, taken from work at discovereads.com
+test_files: []
+