service 1.0.1 → 2.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 014411ad19101419e3294a47ab2ffaa3413ab578
+  data.tar.gz: 065676ea6aa57f1ea4a4597a2accd4aab16e9a1d
+SHA512:
+  metadata.gz: 8b0f6ae156be43fd61794402b4b816e181aa16a7f1a84f55f37b562d7f187f9560d832287ae802c3a7b021bfe05f9342d123e6513fbf0506c96214efc4b8ea1b
+  data.tar.gz: 05cd10eb30527a7b4131d2c5126c3e63d4844e1815d8db2f50b003d224c70f5379a0c443089823610ae40c00e5e99dd3538c67571011e95374463f3a2f981870

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2012 Ryan Scott Lewis <ryan@rynet.us>.
+Copyright (c) 2012 Ryan Scott Lewis <ryanscottlewis@gmail.com>.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,9 +1,7 @@
 # Service
 
-__serv·ice__ _noun_ _/ˈsɜr vɪs/_ __:__ The action of helping or doing work for someone.
-
-Service encapsulates an object which executes a bit of code in a loop that can be started or 
-stopped and query whether it is running or not.
+Service encapsulates an object which executes a bit of code in a loop that can be started or stopped and query whether
+it is running or not.
 
 ## Install
 
@@ -13,52 +11,65 @@ stopped and query whether it is running or not.
 
 ## Usage
 
+> See the `examples/` directory for more usage examples.
+
+### Requiring
+
+  Class/Module   | File
+-----------------|--------------------------
+ `Service`       | `service`
+ `Service::Base` | `service/base`
+
 ### Defining
 
-You can define an Object as a Service by subclassing `Service` or by including/extending 
-`Service::Base`.
+You can define an Object as a Service by subclassing `Service` or by including `Service::Base`:
 
 ```ruby
 class ServiceA < Service
 end
 
 class ServiceB
+
   include Service::Base
-end
 
-class ServiceC
-  extend Service::Base
 end
 ```
 
-A `Service` object stores it's state in the `@_service_state` instance variable as to be as 
-unobtrusive as possible when integrating with your custom objects.
+> A `Service` object stores it's state in the `@_service_state` instance variable as to be as unobtrusive as possible
+> when integrating with your custom objects.
 
-The next thing to do is define a `execute` instance method on your object:
+The next thing to do is to define an `#execute` instance method on your object:
 
 ```ruby
 class MyService < Service
+
   def execute
     # ...
   end
+
 end
 ```
 
 ### Running
 
-Service gives simply allows you to run your code that is within the `execute` method in four different ways: 
-once (`execute`), once in a new Thread (`execute!`), in a loop (`start`/`run`), or in a loop within a
-new Thread (`start!`/`run!`)
+Service simply allows you to run your code that is within the `#execute` instance method in four different ways:
+
+* Once (`#execute`)
+* Once, within a new Thread (`#execute!`)
+* Looping (`#start`/`#run`)
+* Looping, within a new Thread (`#start!`/`#run!`)
 
 ***
 
-Use the `start`/`run` instance method to call the `execute` instance method in a loop.
+Use the `#start`/`#run` instance method to call the `#execute` instance method in a loop.
 
 ```ruby
 class MyService < Service
+
   def execute
     puts "Hello"
   end
+
 end
 
 MyService.new.run
@@ -67,13 +78,15 @@ MyService.new.run
 # => ...
 ```
 
-Use `start!`/`run!` to call the `run` in a new Thread.
+Use `#start!`/`#run!` to call the `#execute` instance method in a new Thread.
 
 ```ruby
 class MyService < Service
+
   def execute
     puts "Hello"
   end
+
 end
 
 thread = MyService.new.run!
@@ -85,88 +98,58 @@ thread.join
 
 ### Stopping
 
-Use the `stop` instance method break the run loop.  
-This will also kill the Thread it is running in, if running in a Thread.
+Use the `#stop` instance method break the run loop.  
+This will also kill the Thread it is running in, if running within a Thread.
 
 ```ruby
-class MyService < Service
+class CountingService < Service
+
+  def initialize
+    @count = 0
+  end
+
   def execute
-    sleep 3
-    stop
+    puts @count
+    sleep 1
+
+    @count += 1
   end
+
 end
 
-print "Running MyService in a new Thread... "
-thread = MyService.new.run!
-thread.join
-puts "Done!"
+service = CountingService.new
+
+service.run! # Run the #execute method in a loop within a new Thread
+sleep 5
+service.stop
 ```
 
 ### Querying State
 
-Use the `started?`/`running?` or `stopped?` instance methods to determine the current state of 
+Use the `started?`/`running?` or `stopped?` instance methods to determine the current state of
 the Service instance.
 
 ```ruby
 class MyService < Service
+
   def execute
     sleep 10
   end
+
 end
 
 service = MyService.new
+
 p service.running? # => false
+
 service.run!
 sleep 1
-p service.running? # => true
-```
-
-## Example
-
-```ruby
-require 'service'
-
-class PingService < Service
-  def execute
-    sleep rand(5)
-    print 'ping'
-    stop
-  end
-end
 
-class PongService
-  include Service::Base
-  
-  def execute
-    sleep rand(5)
-    print 'pong'
-    stop
-  end
-end
-
-class ExcitementService
-  extend Service::Base
-  
-  def execute
-    sleep rand(5)
-    print '!'
-    stop
-  end
-end
-
-threads = []
-threads << PingService.new.run!
-threads << PongService.new.run!
-threads << ExcitementService.new.run!
-
-threads.each(&:join)
+p service.running? # => true
 ```
 
 ## Copyright
 
-Copyright © 2012 Ryan Scott Lewis <ryan@rynet.us>.
+Copyright © 2012 Ryan Scott Lewis <ryanscottlewis@gmail.com>.
 
 The MIT License (MIT) - See LICENSE for further details.
-
-[message_queue]: http://en.wikipedia.org/wiki/Message_queue
-[queue]: http://rubydoc.info/stdlib/thread/Queue

data/Rakefile

@@ -1,51 +1,9 @@
-require 'pathname'
+spec = eval(File.read('service.gemspec'))
 
-def require_task(path)
-  begin
-    require path
-    
-    yield
-  rescue LoadError
-    puts '', "Could not load '#{path}'.", 'Try to `rake gem:spec` and `bundle install` and try again.', ''
-  end
-end
-
-spec = Gem::Specification.new do |s|
-  
-  # Variables
-  s.name = 'service'
-  s.author = 'Ryan Scott Lewis'
-  s.email = 'ryan@rynet.us'
-  s.summary = 'A basic implementation of a Service, which has a run loop can be start and stopped or run an a new Thread.'
-  s.description = 'Service encapsulates an object which executes a bit of code in a loop that can be started or stopped and query whether it is running or not.'
-  
-  # Dependencies
-  s.add_dependency 'version', '~> 1.0'
-  s.add_development_dependency 'rake', '~> 10.0'
-  s.add_development_dependency 'guard-yard', '~> 2.0'
-  s.add_development_dependency 'rb-fsevent', '~> 0.9'
-  s.add_development_dependency 'redcarpet', '~> 2.2.2'
-  s.add_development_dependency 'github-markup', '~> 0.7'
-  
-  # Pragmatically set variables
-  s.homepage = "http://github.com/RyanScottLewis/#{s.name}"
-  s.version = Pathname.glob('VERSION*').first.read
-  s.require_paths = ['lib']
-  s.files        = `git ls-files`.lines.to_a.collect { |s| s.strip }
-  s.executables  = `git ls-files -- bin/*`.lines.to_a.collect { |s| File.basename(s.strip) }
-  
-end
-
-desc 'Generate the gemspec defined in this Rakefile'
-task :gemspec do
-  Pathname.new("#{spec.name}.gemspec").open('w') { |f| f.write(spec.to_ruby) }
-end
-
-require_task 'rake/version_task' do
-  Rake::VersionTask.new do |t|
-    t.with_git_tag = true
-    t.with_gemspec = spec
-  end
+require 'rake/version_task'
+Rake::VersionTask.new do |t|
+  t.with_git_tag = true
+  t.with_gemspec = spec
 end
 
 require 'rubygems/package_task'

data/VERSION

@@ -1 +1 @@
-1.0.1
+2.0.0

data/bin/rake

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rake", "rake")

data/examples/ping_pong.rb

@@ -0,0 +1,51 @@
+require 'service'
+
+# Generates the string "ping pong" asynchronously.
+# Calls to `sleep 5` simulate computationally intensive work.
+#
+# Example of using the `#execute!` to execute a service in a new Thread.
+# Should take ~5s (instead of ~10s)
+
+class BaseService < Service
+
+  def initialize(buffer)
+    @buffer = buffer
+  end
+
+end
+
+class PingService < BaseService
+
+  def execute
+    sleep 5
+
+    @buffer[0] = 'ping'
+  end
+
+end
+
+class PongService < BaseService
+
+  def execute
+    sleep 5
+
+    @buffer[1] = 'pong'
+  end
+
+end
+
+
+buffer  = []
+threads = []
+
+started_at = Time.now
+
+threads << PingService.new(buffer).execute!
+threads << PongService.new(buffer).execute!
+
+threads.each(&:join)
+
+result = buffer.join
+
+puts "Done: '#{result}'"
+puts "Took #{Time.now - started_at}s"

data/examples/queue.rb

@@ -0,0 +1,49 @@
+require 'service'
+# require 'thread' # For the Queue class
+
+# Running two services which transfer data to each other in a thread-safe manner.
+#
+# Example of using the `#run!` to execute a service's run loop in a new Thread.
+
+class BaseService < Service
+
+  def initialize(queue)
+    @queue = queue
+  end
+
+end
+
+# A service which counts infinitely, adding each number to the queue.
+class CountService < BaseService
+
+  def initialize(queue)
+    super
+
+    @count = 0
+  end
+
+  def execute
+    sleep rand(2)    # Simulate computationally intensive work
+    @queue << @count # Add the current count to the queue
+    @count += 1      # Increment the count
+  end
+
+end
+
+# A service which pops all values off each value and prints it each cycle
+class ReportService < BaseService
+
+  def execute
+    sleep 1                              # Wait for a bit, to allow the queue to populate
+    puts(@queue.pop) until @queue.empty? # Until the queue is empty, pop a value off the queue and print it
+  end
+
+end
+
+threads = []
+queue   = Queue.new
+
+threads << CountService.new(queue).run!
+threads << ReportService.new(queue).run!
+
+threads.each(&:join)

data/lib/service.rb

@@ -1,88 +1,74 @@
-require 'version'
-
-# Service encapsulates an object which executes a bit of code in a loop 
-# that can be started or stopped and query whether it is running or not.
-# 
-# Objects can subclass Service.
+# Service encapsulates an object which executes a bit of code in a loop that can be started or stopped and query whether
+# it is running or not.
 class Service
-  is_versioned
-  
-  # The Base module for Services.
-  # Objects can include or extend Service::Base.
+
+  VERSION = "2.0.0".freeze
+
+  # The instance methods to be mixed into a Service.
   module Base
-    
-    # The instance methods to be mixed into modules which include/extend Service::Base.
-    module InstanceMethods
-      
-      # Query if the service is currently stopped.
-      # 
-      # @returns [true, false]
-      def stopped?
-        @_service_state == :stopped
-      end
-      
-      # Query if the service is currently started.
-      # 
-      # @returns [true, false]
-      def started?
-        @_service_state == :started
-      end
-      alias_method :running?, :started?
-      
-      # The code that will be executed within the run loop.
-      # @abstract Subclass and override {#run} to implement a custom Service.
-      def execute
-        raise NotImplementedError
-      end
-      
-      # Call the {#execute} method within a new Thread.
-      # 
-      # @return [Thread]
-      def execute!
-        Thread.new { execute }
-      end
-      
-      # Stop the run loop.
-      def stop
-        @_service_state = :stopped
-      end
-      
-      # Start the run loop.
-      def start
-        @_service_state = :started
-        loop do
-          break if stopped?
-          execute
-        end
-      end
-      alias_method :run, :start
-      
-      # Start the run loop in a new Thread.
-      # 
-      # @return [Thread]
-      def start!
-        Thread.new { start }
-      end
-      alias_method :run!, :start!
-      
+
+    # Query if the service is currently stopped.
+    #
+    # @return [Boolean]
+    def stopped?
+      @_service_state == :stopped
     end
-    
-    class << self
-      
-      # Include Service::Base::InstanceMethods when Service::Base is included.
-      def included(base)
-        base.send(:include, InstanceMethods)
-      end
-      
-      # Include Service::Base::InstanceMethods when Service::Base is extended.
-      def extended(base)
-        base.send(:include, InstanceMethods)
+
+    # Query if the service is currently started.
+    #
+    # @return [Boolean]
+    def started?
+      @_service_state == :started
+    end
+    alias_method :running?, :started?
+
+    # The code that will be executed within the run loop.
+    #
+    # @abstract Override {#execute} to implement a custom Service.
+    def execute
+      raise NotImplementedError
+    end
+
+    # Call the {#execute} method within a new Thread.
+    #
+    # @return [Thread]
+    def execute!
+      Thread.new { execute }
+    end
+
+    # Stop the run loop.
+    #
+    # @return [Symbol] The current state (`:stopped`).
+    def stop
+      @_service_state = :stopped
+    end
+
+    # Start the run loop.
+    #
+    # @return [Symbol] The current state (`:started`).
+    def start
+      @_service_state = :started
+
+      loop do
+        break if stopped?
+
+        execute
       end
-      
     end
-    
+
+    alias_method :run, :start
+
+    # Start the run loop in a new Thread.
+    #
+    # @return [Thread]
+    def start!
+      Thread.new { start }
+    end
+
+    alias_method :run!, :start!
+
   end
-  
+
   include Base
-  
+
 end

data/service.gemspec

@@ -1,44 +1,19 @@
-# -*- encoding: utf-8 -*-
-
 Gem::Specification.new do |s|
-  s.name = "service"
-  s.version = "1.0.1"
-
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Ryan Scott Lewis"]
-  s.date = "2012-12-16"
-  s.description = "Service encapsulates an object which executes a bit of code in a loop that can be started or stopped and query whether it is running or not."
-  s.email = "ryan@rynet.us"
-  s.files = ["Gemfile", "LICENSE", "README.md", "Rakefile", "VERSION", "lib/service.rb", "service.gemspec"]
-  s.homepage = "http://github.com/RyanScottLewis/service"
-  s.require_paths = ["lib"]
-  s.rubygems_version = "1.8.24"
-  s.summary = "A basic implementation of a Service, which has a run loop can be start and stopped or run an a new Thread."
+  # Variables
+  s.name        = 'service'
+  s.author      = 'Ryan Scott Lewis'
+  s.email       = 'ryanscottlewis@gmail.com'
+  s.summary     = 'A basic implementation of a Service, which has a run loop can be start and stopped or run an a new Thread.'
+  s.description = 'Service encapsulates an object which executes a bit of code in a loop that can be started or stopped and query whether it is running or not.'
 
-  if s.respond_to? :specification_version then
-    s.specification_version = 3
+  # Dependencies
+  s.add_development_dependency 'version', '~> 1.0'
+  s.add_development_dependency 'rake', '~> 10.0'
 
-    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<version>, ["~> 1.0"])
-      s.add_development_dependency(%q<rake>, ["~> 10.0"])
-      s.add_development_dependency(%q<guard-yard>, ["~> 2.0"])
-      s.add_development_dependency(%q<rb-fsevent>, ["~> 0.9"])
-      s.add_development_dependency(%q<redcarpet>, ["~> 2.2.2"])
-      s.add_development_dependency(%q<github-markup>, ["~> 0.7"])
-    else
-      s.add_dependency(%q<version>, ["~> 1.0"])
-      s.add_dependency(%q<rake>, ["~> 10.0"])
-      s.add_dependency(%q<guard-yard>, ["~> 2.0"])
-      s.add_dependency(%q<rb-fsevent>, ["~> 0.9"])
-      s.add_dependency(%q<redcarpet>, ["~> 2.2.2"])
-      s.add_dependency(%q<github-markup>, ["~> 0.7"])
-    end
-  else
-    s.add_dependency(%q<version>, ["~> 1.0"])
-    s.add_dependency(%q<rake>, ["~> 10.0"])
-    s.add_dependency(%q<guard-yard>, ["~> 2.0"])
-    s.add_dependency(%q<rb-fsevent>, ["~> 0.9"])
-    s.add_dependency(%q<redcarpet>, ["~> 2.2.2"])
-    s.add_dependency(%q<github-markup>, ["~> 0.7"])
-  end
+  # Pragmatically set variables
+  s.homepage      = "http://github.com/RyanScottLewis/#{s.name}"
+  s.version       = File.read('VERSION')
+  s.require_paths = ['lib']
+  s.files         = `git ls-files`.lines.to_a.collect { |s| s.strip }
+  s.executables   = `git ls-files -- bin/*`.lines.to_a.collect { |s| File.basename(s.strip) }
 end

metadata

@@ -1,116 +1,48 @@
 --- !ruby/object:Gem::Specification
 name: service
 version: !ruby/object:Gem::Version
-  version: 1.0.1
-  prerelease: 
+  version: 2.0.0
 platform: ruby
 authors:
 - Ryan Scott Lewis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-16 00:00:00.000000000 Z
+date: 2018-01-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: version
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
-  type: :runtime
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '10.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '10.0'
-- !ruby/object:Gem::Dependency
-  name: guard-yard
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: '2.0'
-- !ruby/object:Gem::Dependency
-  name: rb-fsevent
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: '0.9'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: '0.9'
-- !ruby/object:Gem::Dependency
-  name: redcarpet
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: 2.2.2
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: 2.2.2
-- !ruby/object:Gem::Dependency
-  name: github-markup
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: '0.7'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: '0.7'
 description: Service encapsulates an object which executes a bit of code in a loop
   that can be started or stopped and query whether it is running or not.
-email: ryan@rynet.us
-executables: []
+email: ryanscottlewis@gmail.com
+executables:
+- rake
 extensions: []
 extra_rdoc_files: []
 files:
@@ -119,34 +51,33 @@ files:
 - README.md
 - Rakefile
 - VERSION
+- bin/rake
+- examples/ping_pong.rb
+- examples/queue.rb
 - lib/service.rb
 - service.gemspec
 homepage: http://github.com/RyanScottLewis/service
 licenses: []
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: 900928583881142489
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 2.6.11
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: A basic implementation of a Service, which has a run loop can be start and
   stopped or run an a new Thread.
 test_files: []