thread_so_safe 0.1.1 → 0.2

data/.gitignore

@@ -18,5 +18,7 @@ coverage
 rdoc
 pkg
 *.gem
+tmp/*
+.document
 
 ## PROJECT::SPECIFIC

data/README.rdoc

@@ -1,36 +1,139 @@
 = thread_so_safe
 
-thread_so_safe is a very simple gem to help keep multi-threaded environments synced.
++thread_so_safe+ is a very simple gem to help keep data accessed in multiple threads synced.
 
-== Examples
 
-  ThreadSoSafe.safeguard('My.App Users')
+== What is this thing?
+
+Well the description pretty much says it all. +thread_so_safe+ is a gem to help keep data accessed in multiple threads synced.
+
+
+== Why do I care?
+
+That's a great question! Your data is important. If your data changes during the lifecycle of your application, your application may not run properly. Oh no! That sounds terrible! Luckily we can make our code smart enough that we don't have to worry about this.
+
+
+== Are you reinventing the wheel?
+
+Absolutely not! +thread_so_safe+ is not a wheel, but I might be reinventing a thread-safety mechanism. Some approaches to thread-safety lock the data from every other thread until the current thread is finished with the data. This has the potential to slow down your app quite a bit if you have many threads. Other approaches update the data found in each thread. This works when you know what you're looking for. +thread_so_safe+ gives you the means of checking, "has my data changed or is it still safe?" and, "I've changed my data, better send an update to any other threads that might be using this data."
+
+
+== That sounds fancy, but how does it really work?
+
+When you call +register_token+ it creates a file in +/tmp/thread_so_safe+. This file contains the +Time.now.to_i+ value at the time of creation. The time value is also stored in +ThreadSoSafe+'s memory. The +in_sync?+ method checks value stored in the +ThreadSoSafe+ object against the value in the file. If they match the thread is safe, but if they don't match +in_sync?+ will return false to indicating the thread isn't safe or synced anymore. The +update!+ and +reset!+ methods update the time value in the file.
+
+At first I tried using only the timestamp of the file, but file timestamps only record hours, minutes and seconds. A lot can happen to a data source in one second. It's because of this that I decided to store the +Time.now.to_i+ value. +Time.now+ returns a time value with much greater detail than jus seconds, so it looked like a good idea.
+
+
+== Example time
+
+  # It's time to register your application or data with ThreadSoSafe!
+  # Just pass in a unique string to the register_token method to generate
+  # a new thread-safety token.
+  ThreadSoSafe.register_token('My.App Users')
+
+  # Great! Now lets capture our data
   users = User.find(:all)
-  
+
+  # Lets make a change to our data set
+  users.last.destroy
+
+  # Our data has changed so let's send an update to ThreadSoSafe so that
+  # any other piece of code using ThreadSoSafe.register_token('My.App Users')
+  # will know the data has changed.
+  ThreadSoSafe.update!
+
   # ...
-  
-  unless ThreadSoSafe.safe?
-    users = User.find(:all)
-    ThreadSoSafe.update!
+
+  # Well we've changed the data, but as anyone else in the meanwhile?
+  # We can use the in_sync? method to check.
+  if ThreadSoSafe.in_sync?
+    puts "The data is great! Keep going!"
+    # ...
   end
-  
+
   ###
-  
+
   # if you're working with multiple data sets that need to be in sync
   # you can pass the name (in the first example's case, My.App Users)
-  # into the safe? and update!
-  
-  ThreadSoSafe.safeguard('Users')
+  # into the in_sync? and update!
+
+  ThreadSoSafe.register_token('Users')
   users = User.find(:all)
-  
-  ThreadSoSafe.safeguard('Roles')
+
+  ThreadSoSafe.register_token('Roles')
   roles = Role.find(:all)
-  
+
   # ...
-  
-  unless ThreadSoSafe.safe?('Roles')
+
+  # Notice we're calling in_sync? but with a string now
+  unless ThreadSoSafe.in_sync?('Roles')
     users = User.find(:all)
+
+    # Also notice we're calling update!, but with a string as well.
     ThreadSoSafe.update!('Roles)
-  end  
+  end
+
+  ###
+
+  # We can notify other threads that data has changed with update!,
+  # but that updates our thread token as well. I've hit a case where
+  # I want to notify other threads that my data has changed AND force
+  # a reload of data in my current thread. This is why I made a reset!
+  # method. Calling reset! updates the token that all threads reference,
+  # but does not update the token stored in the gem. This results in
+  # in_sync? returning false and your code can pull the appropriate data
+  # and call update! afterwards to re-sync the threads.
+
+  class Settings < ActiveRecord::Base
+    class << self
+      def [](key)
+        load_collection
+        @settings_collection[key]
+      end
+
+      def []=(key, value)
+        item = find_or_create_by(:key => key)
+        item.value = value
+        item.save!
+
+        ThreadSoSafe.reset!
+        # We've reset the token. Next time Settings[:key] is called the
+        # load_collection method will rebuild the @settings_collection
+      end
+
+      private
+      def load_collection        
+        if @settings_collection.nil?
+          # Our @settings_collection variable doesn't exist so register your token
+          ThreadSoSafe.register_token('MyAppSettings')
+        elsif ThreadSoSafe.in_sync?
+          # If our token is already registered and we're in-sync just return and
+          # don't bother running the rest of the code
+          return
+        end  
+
+        # We've just registered our token or we're not in-sync anymore. I guess
+        # we had better reload our data
+
+        @settings_collection = {}
+
+        all.each { |s| @settings_collection[s.key] = s.value }
+
+        # We reloaded our data so lets inform the thread that we're re-synced
+        ThreadSoSafe.update!
+      end
+    end
+  end
+
+== So... I have to use this in my app?
+
+Yes. +thread_so_safe+ is just the mechanism used to keep track and inform whether or not data has changed. If have App1 using +thread_so_safe+, but App2 doesn't -- *and* manipulates the same data, your data wont be in sync. You'll need to use +thread_so_safe+ with both App1 and App2.
+
+
+== Questions/Comments
+
+Feel free to send me a message on Github or on Twitter (@daneharrigan). Thanks!
+
 
 Copyright (c) 2010 Dane Harrigan. See LICENSE for details.

data/Rakefile

@@ -1,18 +1,19 @@
 require 'rubygems'
 require 'rake'
 require 'spec/rake/spectask'
+require 'sdoc'
 
 begin
   require 'jeweler'
   Jeweler::Tasks.new do |gem|
     gem.name = "thread_so_safe"
-    gem.version = "0.1.1"
+    gem.version = "0.2"
     gem.summary = %Q{thread_so_safe is a very simple gem to help keep multi-threaded environments synced.}
     gem.description = gem.summary
     gem.email = "dane.harrigan@gmail.com"
     gem.homepage = "http://github.com/daneharrigan/thread_so_safe"
     gem.authors = ["Dane Harrigan"]
-    gem.add_development_dependency "rspec", ">= 1.2.9"
+    gem.add_development_dependency "rspec", ">= 1.3.0"
   end
   Jeweler::GemcutterTasks.new
 rescue LoadError
@@ -43,4 +44,4 @@ Rake::RDocTask.new do |rdoc|
   rdoc.title = "thread_so_safe #{version}"
   rdoc.rdoc_files.include('README*')
   rdoc.rdoc_files.include('lib/**/*.rb')
-end
+end

data/lib/thread_so_safe.rb

@@ -3,32 +3,114 @@ require 'fileutils'
 
 class ThreadSoSafe
   @@threads = {}
-  @@current_thread = nil
+  @@current_token = nil
 
   class << self
-    def safeguard(name)
-      @@current_thread = name
-      name = file_name(name)
-      path = full_path(name)
-
-      FileUtils.touch(path) unless File.exists? path
-      @@threads[name] = File.mtime(path)
+    # register_token - This method creates and/or resumes existing ThreadSoSafe
+    # sessions. register_token accepts one parameter as a string. Multiple tokens can
+    # be registered ThreadSoSafe but only one at a time. The last registered_token is
+    # stored in @@current_token. Storing the last token allows for later methods to
+    # process without needing the token passed.
+    #
+    # ==== Example
+    #   ThreadSoSafe.register_token('My.Application')
+    #   ThreadSoSafe.register_token('My.Application Users')
+    def register_token(name)
+      @@current_token = name
+      token = file_name(name)
+      @@threads[token] = set_timestamp(token)
       return
     end
 
-    def safe?(name=@@current_thread)
-      @@current_thread = name
-      name = file_name(name)
+    # in_sync? - This method returns a boolean value indicating whether or not the
+    # current thread is in sync with any other thread/application using the same
+    # token. in_sync? accepts a token, but isn't necessary if there is only one
+    # token registered in your application. If you have multiple tokens it's
+    # necessary to pass the token when checking if your thread is in-sync.
+    # 
+    # ==== Example
+    #   if ThreadSoSafe.in_sync?
+    #     puts "Good thing I'm the only token registered!"
+    #   end
+    #
+    #   # with multiple tokens
+    #   if ThreadSoSafe.in_sync?('My.Application')
+    #     puts "We're still synced"
+    #   end
+    #
+    #   if ThreadSoSafe.in_sync?('My.Application Users')
+    #     puts "Users are synced as well"
+    #   end
+    def in_sync?(name=@@current_token)
+      token = file_name(name)
+
+      @@threads[token] == File.read(full_path(token))
+    end
 
-      @@threads[name] == File.mtime("#{full_path name}")
+    # update! - This method updates the ThreadSoSafe session. Aftering being called,
+    # the in_sync? method will return true on the current thread, but false on any
+    # other thread until update! is called on it.
+    #
+    # ==== Example
+    #   # thread 1
+    #   ThreadSoSafe.register_token('My.Application Users')
+    #   users = User.find(:all)
+    #   users.last.destroy
+    #   ThreadSoSafe.update!
+    # 
+    #   if ThreadSoSafe.in_sync?
+    #     puts "Data is in sync"
+    #   end
+    #
+    #   ####
+    #
+    #   # thread 2
+    #   unless ThreadSoSafe.in_sync?
+    #     puts "Data is out of sync"
+    #     users = User.find(:all)
+    #     ThreadSoSafe.update!
+    #   end
+    def update!(name=@@current_token)
+      token = file_name(name)
+      file_content = File.read full_path(token)
+      if @@threads[token] == file_content
+        @@threads[token] = set_timestamp(token)
+      else
+        @@threads[token] = file_content
+      end
+      return
     end
 
-    def update!(name=@@current_thread)
-      name = file_name(name)
-      file = full_path(name)
+    # Update token only and notify other threads
 
-      FileUtils.touch(file) if @@threads[name] == File.mtime(file)
-      @@threads[name] = File.mtime(file)
+    # reset! - This method updates the ThreadSoSafe session. Every thread, including
+    # the current, is notified of the change. This notification causes the in_sync?
+    # method returns false until update! is called.
+    # 
+    # ==== Example
+    #   # thread 1
+    #   ThreadSoSafe.register_token('My.Application Users')
+    #   users = User.find(:all)
+    #   users.last.destroy
+    #   ThreadSoSafe.reset!
+    # 
+    #   unless ThreadSoSafe.in_sync?
+    #     puts "Data needs to be recaptured"
+    #     users = User.find(:all)
+    #     ThreadSoSafe.update!
+    #   end
+    #
+    #   ####
+    #
+    #   # thread 2
+    #   unless ThreadSoSafe.in_sync?
+    #     puts "Data is out of sync"
+    #     users = User.find(:all)
+    #     ThreadSoSafe.update!
+    #   end
+    def reset!(name=@@current_token)
+      set_timestamp file_name(name)
+      return
     end
 
     private
@@ -45,17 +127,22 @@ class ThreadSoSafe
     end
 
     def use_default_directory?
+      FileUtils.mkdir(default_directory) unless File.exists?(default_directory)
       File.writable?(default_directory)
     end
 
-    #:nordoc:
     def default_directory
       '/tmp/thread_so_safe'
     end
 
-    #:nordoc:
     def gem_directory
       File.expand_path(File.dirname(__FILE__)+'/../tmp')
     end
+
+    def set_timestamp(token)
+      timestamp = Time.now.to_f.to_s
+      File.open(full_path(token), 'w+') { |f| f.write timestamp }
+      timestamp
+    end
   end
 end

data/spec/thread_so_safe_spec.rb

@@ -2,22 +2,33 @@ require "spec_helper"
 
 describe ThreadSoSafe do
   before(:all) do
-    @app_name = 'My.Application'
+    @token = 'My.Application'
     @default_directory = '/tmp/thread_so_safe'
+
+    ThreadSoSafe.register_token(@token)
+  end
+
+  # :all works differently in rspec 1.3.0 and 2.0.
+  # :suite runs after everything is done in 2.0 like :all did in 1.3.0
+  # The Spec namespace has also been renamed to RSpec so I'm looking
+  # for Spec and if it doesn't exist then it must be RSpec 2
+  after(defined?(RSpec) ? :suite : :all) do
+    gem_directory = ThreadSoSafe.send(:gem_directory)
+  
+    FileUtils.rm_rf(@default_directory) if File.exists?(@default_directory)
+    FileUtils.rm_rf("#{gem_directory}/*")
   end
 
-  it "should be safe without passing the application name" do
-    ThreadSoSafe.safeguard(@app_name)
-    ThreadSoSafe.safe?.should == true
+  it "should be in-sync without passing the token" do
+    ThreadSoSafe.in_sync?.should == true
   end
 
-  it "should be safe with the application name passed" do
-    ThreadSoSafe.safeguard(@app_name)
-    ThreadSoSafe.safe?(@app_name).should == true    
+  it "should be in-sync with the token passed" do
+    ThreadSoSafe.in_sync?(@token).should == true
   end
 
-  it "should encode the application name with md5" do
-    ThreadSoSafe.send(:file_name,@app_name).should == Digest::MD5.hexdigest(@app_name)  
+  it "should encode the token with md5" do
+    ThreadSoSafe.send(:file_name,@token).should == Digest::MD5.hexdigest(@token)  
   end
 
   it "should return /tmp/thread_so_safe as the default directory" do
@@ -35,47 +46,82 @@ describe ThreadSoSafe do
   end
 
   it "should return the full path to the /tmp file" do
-    file_name = ThreadSoSafe.send(:file_name, @app_name)
+    file_name = ThreadSoSafe.send(:file_name, @token)
     ThreadSoSafe.send(:full_path, file_name).should == "#{@default_directory}/#{file_name}"
   end
 
-  context "when another thread updates the thread-safe token" do
+  context "when updating the thread-safe token" do
     before(:each) do
-      ThreadSoSafe.safeguard(@app_name)
+      file_name = ThreadSoSafe.send(:file_name, @token)
+      @full_path = ThreadSoSafe.send(:full_path, file_name)
+      @file_content = File.read(@full_path)
+    end
+
+    it "should update the file content in on the /tmp file with the token passed" do
+      ThreadSoSafe.update!(@token)
+      File.read(@full_path).should_not == @file_content
+    end
+
+    it "should update the file content on the /tmp file without the token passed" do
+      ThreadSoSafe.update!
+      File.read(@full_path).should_not == @file_content
+    end
 
-      file_name = ThreadSoSafe.send(:file_name, @app_name)
+    context "when the remote token is udpated by another thread" do
+      before(:each) do
+        File.open(@full_path, 'w') { |f| f.write(Time.now.to_i) }
+      end
+
+      it "should use the token stored in the /tmp file" do
+        ThreadSoSafe.update!(@token)
+        ThreadSoSafe.in_sync?.should == true
+      end
+    end
+  end
+
+  context "when another thread updates the thread-safe token" do
+    before(:all) do
+      file_name = ThreadSoSafe.send(:file_name, @token)
       full_path = ThreadSoSafe.send(:full_path, file_name)
 
-      File.stub!(:mtime).and_return(Time.now+100)
+      File.open(full_path, 'w') { |f| f.write(Time.now.to_f) }
     end
 
-    it "should not be safe without passing the application name" do
-      ThreadSoSafe.safe?.should == false
+    it "should not be safe without passing the token" do
+      ThreadSoSafe.in_sync?.should == false
     end
 
-    it "should be safe with the application name passed" do
-      ThreadSoSafe.safe?(@app_name).should == false
+    it "should be safe with the token passed" do
+      ThreadSoSafe.in_sync?(@token).should == false
     end
   end
 
-  context "when updating the thread-safe token" do
-    before(:each) do
-      ThreadSoSafe.safeguard(@app_name)
-      file_name = ThreadSoSafe.send(:file_name, @app_name)
+  context "when resetting the thread-safe token" do
+    before(:all) do
+      file_name = ThreadSoSafe.send(:file_name, @token)
       @full_path = ThreadSoSafe.send(:full_path, file_name)
+    end
 
-      @mtime = File.mtime @full_path
-      File.stub!(:mtime).and_return(Time.now+100)
+    it "should not be in sync without the token passed" do
+      ThreadSoSafe.reset!
+      ThreadSoSafe.in_sync?.should == false
     end
 
-    it "should update the mtime on the /tmp file with the application name passed" do
-      ThreadSoSafe.update!(@app_name)
-      File.mtime(@full_path).should_not == @mtime
+    it "should not be in sync with the token passed" do
+      ThreadSoSafe.reset!(@token)
+      ThreadSoSafe.in_sync?.should == false
     end
 
-    it "should update the mtime on the /tmp file without the application name passed" do
-      ThreadSoSafe.update!
-      File.mtime(@full_path).should_not == @mtime
+    it "should update the file content on the /tmp file without the token passed" do
+      file_content = File.read(@full_path)
+      ThreadSoSafe.reset!
+      File.read(@full_path).should_not == file_content
+    end
+
+    it "should update the file content on the /tmp file with the token passed" do
+      file_content = File.read(@full_path)
+      ThreadSoSafe.reset!(@token)
+      File.read(@full_path).should_not == file_content
     end
   end
 

data/thread_so_safe.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{thread_so_safe}
-  s.version = "0.1.1"
+  s.version = "0.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Dane Harrigan"]
-  s.date = %q{2010-06-27}
+  s.date = %q{2010-07-04}
   s.description = %q{thread_so_safe is a very simple gem to help keep multi-threaded environments synced.}
   s.email = %q{dane.harrigan@gmail.com}
   s.extra_rdoc_files = [
@@ -17,8 +17,7 @@ Gem::Specification.new do |s|
      "README.rdoc"
   ]
   s.files = [
-    ".document",
-     ".gitignore",
+    ".gitignore",
      "LICENSE",
      "README.rdoc",
      "Rakefile",
@@ -30,7 +29,7 @@ Gem::Specification.new do |s|
   s.homepage = %q{http://github.com/daneharrigan/thread_so_safe}
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.6}
+  s.rubygems_version = %q{1.3.7}
   s.summary = %q{thread_so_safe is a very simple gem to help keep multi-threaded environments synced.}
   s.test_files = [
     "spec/spec_helper.rb",
@@ -41,13 +40,13 @@ Gem::Specification.new do |s|
     current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
-    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
-      s.add_development_dependency(%q<rspec>, [">= 1.2.9"])
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, [">= 1.3.0"])
     else
-      s.add_dependency(%q<rspec>, [">= 1.2.9"])
+      s.add_dependency(%q<rspec>, [">= 1.3.0"])
     end
   else
-    s.add_dependency(%q<rspec>, [">= 1.2.9"])
+    s.add_dependency(%q<rspec>, [">= 1.3.0"])
   end
 end
 

metadata

@@ -1,12 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: thread_so_safe
 version: !ruby/object:Gem::Version 
+  hash: 15
   prerelease: false
   segments: 
   - 0
-  - 1
-  - 1
-  version: 0.1.1
+  - 2
+  version: "0.2"
 platform: ruby
 authors: 
 - Dane Harrigan
@@ -14,21 +14,23 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-06-27 00:00:00 -04:00
+date: 2010-07-04 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: rspec
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 27
         segments: 
         - 1
-        - 2
-        - 9
-        version: 1.2.9
+        - 3
+        - 0
+        version: 1.3.0
   type: :development
   version_requirements: *id001
 description: thread_so_safe is a very simple gem to help keep multi-threaded environments synced.
@@ -41,7 +43,6 @@ extra_rdoc_files:
 - LICENSE
 - README.rdoc
 files: 
-- .document
 - .gitignore
 - LICENSE
 - README.rdoc
@@ -60,23 +61,27 @@ rdoc_options:
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.6
+rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
 summary: thread_so_safe is a very simple gem to help keep multi-threaded environments synced.

data/.document

@@ -1,5 +0,0 @@
-README.rdoc
-lib/**/*.rb
-bin/*
-features/**/*.feature
-LICENSE