thread 0.0.2 → 0.0.3

data/README.md

@@ -1,5 +1,5 @@
-thread - various extensions to the thread stdlib
-================================================
+thread - various extensions to the thread library
+=================================================
 
 Pool
 ====
@@ -108,3 +108,19 @@ puts ~future {
   42
 } # => 42
 ```
+
+Delay
+=====
+A delay is kind of a promise, except the block is called when the value is
+being accessed and the result is cached.
+
+Example
+-------
+
+```ruby
+require 'thread/delay'
+
+puts ~delay {
+  42
+}
+```

data/lib/thread/channel.rb

@@ -10,7 +10,12 @@
 
 require 'thread'
 
+# A channel lets you send and receive various messages in a thread-safe way.
+#
+# It also allows for guards upon sending and retrieval, to ensure the passed
+# messages are safe to be consumed.
 class Thread::Channel
+	# Create a channel with optional initial messages and optional channel guard.
 	def initialize (messages = [], &block)
 		@messages = []
 		@mutex    = Mutex.new
@@ -22,6 +27,10 @@ class Thread::Channel
 		}
 	end
 
+	# Send a message to the channel.
+	#
+	# If there's a guard, the value is passed to it, if the guard returns a falsy value
+	# an ArgumentError exception is raised and the message is not sent.
 	def send (what)
 		if @check && !@check.call(what)
 			raise ArgumentError, 'guard mismatch'
@@ -35,6 +44,9 @@ class Thread::Channel
 		self
 	end
 
+	# Receive a message, if there are none the call blocks until there's one.
+	#
+	# If a block is passed, it's used as guard to match to a message.
 	def receive (&block)
 		message = nil
 
@@ -64,6 +76,9 @@ class Thread::Channel
 		message
 	end
 
+	# Receive a message, if there are none the call returns nil.
+	#
+	# If a block is passed, it's used as guard to match to a message.
 	def receive! (&block)
 		if block
 			@messages.delete_at(@messages.find_index(&block))

data/lib/thread/delay.rb

@@ -0,0 +1,73 @@
+#--
+#            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+#                    Version 2, December 2004
+#
+#            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+#   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+#
+#  0. You just DO WHAT THE FUCK YOU WANT TO.
+#++
+
+# A delay is an object that incapsulates a block which is called upon
+# value retrieval, and its result cached.
+class Thread::Delay
+	def initialize (&block)
+		@block = block
+	end
+
+	# Check if an exception has been raised.
+	def exception?
+		instance_variable_defined? :@exception
+	end
+
+	# Return the raised exception.
+	def exception
+		@exception
+	end
+
+	# Check if the delay has been called.
+	def delivered?
+		instance_variable_defined? :@value
+	end
+
+	alias realized? delivered?
+
+	# Get the value of the delay, if it's already been executed, return the
+	# cached result, otherwise execute the block and return the value.
+	#
+	# In case the block raises an exception, it will be raised, the exception is
+	# cached and will be raised every time you access the value.
+	def value
+		raise @exception if exception?
+
+		return @value if realized?
+
+		begin
+			@value = @block.call
+		rescue Exception => e
+			@exception = e
+
+			raise
+		end
+	end
+
+	alias ~ value
+
+	# Do the same as {#value}, but return nil in case of exception.
+	def value!
+		begin
+			value
+		rescue Exception
+			nil
+		end
+	end
+
+	alias ! value!
+end
+
+module Kernel
+	# Helper to create a Thread::Delay
+	def delay (&block)
+		Thread::Delay.new(&block)
+	end
+end

data/lib/thread/future.rb

@@ -10,12 +10,98 @@
 
 require 'thread/promise'
 
-class Thread::Future < Thread::Promise
+# A future is an object that incapsulates a block which is called in a
+# different thread, upon retrieval the caller gets blocked until the block has
+# finished running, and its result is returned and cached.
+class Thread::Future
 	def initialize (&block)
 		Thread.new {
-			deliver block.call
+			begin
+				deliver block.call
+			rescue Exception => e
+				@exception = e
+
+				deliver nil
+			end
 		}
 	end
+
+	# Check if an exception has been raised.
+	def exception?
+		instance_variable_defined? :@exception
+	end
+
+	# Return the raised exception.
+	def exception
+		@exception
+	end
+
+	# Check if the future has been called.
+	def delivered?
+		instance_variable_defined? :@value
+	end
+
+	alias realized? delivered?
+
+	# Get the value of the future, if it's not finished running this call will block.
+	#
+	# In case the block raises an exception, it will be raised, the exception is cached
+	# and will be raised every time you access the value.
+	def value
+		raise @exception if exception?
+
+		return @value if delivered?
+
+		mutex.synchronize {
+			cond.wait(mutex)
+		}
+
+		if exception?
+			raise @exception
+		else
+			@value
+		end
+	end
+
+	alias ~ value
+
+	# Do the same as {#value}, but return nil in case of exception.
+	def value!
+		begin
+			value
+		rescue Exception
+			nil
+		end
+	end
+
+	alias ! value!
+
+private
+	def deliver (value)
+		return if delivered?
+
+		@value = value
+
+		if cond?
+			mutex.synchronize {
+				cond.broadcast
+			}
+		end
+
+		self
+	end
+
+	def cond?
+		instance_variable_defined? :@cond
+	end
+
+	def cond
+		@cond ||= ConditionVariable.new
+	end
+
+	def mutex
+		@mutex ||= Mutex.new
+	end
 end
 
 module Kernel

data/lib/thread/pool.rb

@@ -10,17 +10,27 @@
 
 require 'thread'
 
+# A pool is a container of a limited amount of threads to which you can add
+# tasks to run.
+#
+# This is usually more performant and less memory intensive than creating a
+# new thread for every task.
 class Thread::Pool
+	# A task incapsulates a block being ran by the pool and the arguments to pass
+	# to it.
 	class Task
 		Timeout = Class.new(Exception)
 		Asked   = Class.new(Exception)
 
 		attr_reader :pool, :timeout, :exception, :thread, :started_at
 
+		# Create a task in the given pool which will pass the arguments to the
+		# block.
 		def initialize (pool, *args, &block)
-			@pool       = pool
-			@arguments  = args
-			@block      = block
+			@pool      = pool
+			@arguments = args
+			@block     = block
+
 			@running    = false
 			@finished   = false
 			@timedout   = false
@@ -32,6 +42,7 @@ class Thread::Pool
 		def timeout?;    @timedout;   end
 		def terminated?; @terminated; end
 
+		# Execute the task in the given thread.
 		def execute (thread)
 			return if terminated? || running? || finished?
 
@@ -39,7 +50,7 @@ class Thread::Pool
 			@running    = true
 			@started_at = Time.now
 
-			pool.wake_up_timeout
+			pool.__send__.wake_up_timeout
 
 			begin
 				@block.call(*@arguments)
@@ -58,6 +69,7 @@ class Thread::Pool
 			@thread   = nil
 		end
 
+		# Terminate the exception with an optionally given exception.
 		def terminate! (exception = Asked)
 			return if terminated? || finished? || timeout?
 
@@ -68,10 +80,12 @@ class Thread::Pool
 			@thread.raise exception
 		end
 
+		# Force the task to timeout.
 		def timeout!
 			terminate! Timeout
 		end
 
+		# Timeout the task after the given time.
 		def timeout_after (time)
 			@timeout = time
 
@@ -83,6 +97,13 @@ class Thread::Pool
 
 	attr_reader :min, :max, :spawned
 
+	# Create the pool with minimum and maximum threads.
+	#
+	# The pool will start with the minimum amount of threads created and will
+	# spawn new threads until the max is reached in case of need.
+	#
+	# A default block can be passed, which will be used to {#process} the passed
+	# data.
 	def initialize (min, max = nil, &block)
 		@min   = min
 		@max   = max || min
@@ -108,12 +129,26 @@ class Thread::Pool
 		}
 	end
 
+	# Check if the pool has been shut down.
 	def shutdown?; !!@shutdown; end
 
-	def auto_trim?;    @auto_trim;         end
-	def auto_trim!;    @auto_trim = true;  end
-	def no_auto_trim!; @auto_trim = false; end
+	# Check if auto trimming is enabled.
+	def auto_trim?
+		@auto_trim
+	end
+
+	# Enable auto trimming, unneeded threads will be deleted until the minimum
+	# is reached.
+	def auto_trim!
+		@auto_trim = true
+	end
 
+	# Disable auto trimming.
+	def no_auto_trim!
+		@auto_trim = false
+	end
+
+	# Resize the pool with the passed arguments.
 	def resize (min, max = nil)
 		@min = min
 		@max = max || min
@@ -121,12 +156,18 @@ class Thread::Pool
 		trim!
 	end
 
+	# Get the amount of tasks that still have to be run.
 	def backlog
 		@mutex.synchronize {
 			@todo.length
 		}
 	end
 
+	# Add a task to the pool which will execute the block with the given
+	# argument.
+	#
+	# If no block is passed the default block will be used if present, an
+	# ArgumentError will be raised otherwise.
 	def process (*args, &block)
 		unless block || @block
 			raise ArgumentError, 'you must pass a block'
@@ -151,6 +192,8 @@ class Thread::Pool
 
 	alias << process
 
+	# Trim the unused threads, if forced threads will be trimmed even if there
+	# are tasks waiting.
 	def trim (force = false)
 		@mutex.synchronize {
 			if (force || @waiting > 0) && @spawned - @trim_requests > @min
@@ -162,10 +205,12 @@ class Thread::Pool
 		self
 	end
 
+	# Force #{trim}.
 	def trim!
 		trim true
 	end
 
+	# Shut down the pool instantly without finishing to execute tasks.
 	def shutdown!
 		@mutex.synchronize {
 			@shutdown = :now
@@ -177,6 +222,7 @@ class Thread::Pool
 		self
 	end
 
+	# Shut down the pool, it will block until all tasks have finished running.
 	def shutdown
 		@mutex.synchronize {
 			@shutdown = :nicely
@@ -196,12 +242,14 @@ class Thread::Pool
 		self
 	end
 
+	# Join on all threads in the pool.
 	def join
 		@workers.first.join until @workers.empty?
 
 		self
 	end
 
+	# Define a timeout for a task.
 	def timeout_for (task, timeout)
 		unless @timeout
 			spawn_timeout_thread
@@ -214,6 +262,7 @@ class Thread::Pool
 		}
 	end
 
+	# Shutdown the pool after a given amount of time.
 	def shutdown_after (timeout)
 		Thread.new {
 			sleep timeout
@@ -224,13 +273,13 @@ class Thread::Pool
 		self
 	end
 
+private
 	def wake_up_timeout
 		if defined? @pipes
 			@pipes.last.write_nonblock 'x' rescue nil
 		end
 	end
 
-private
 	def spawn_thread
 		@spawned += 1
 
@@ -281,7 +330,7 @@ private
 		@timeout = Thread.new {
 			loop do
 				now     = Time.now
-				timeout = @timeouts.map {|task, timeout|
+				timeout = @timeouts.map {|task, time|
 					next unless task.started_at
 
 					now - task.started_at + task.timeout

data/lib/thread/promise.rb

@@ -10,11 +10,16 @@
 
 require 'thread'
 
+# A promise is an object that lets you wait for a value to be delivered to it.
 class Thread::Promise
+	# Check if a value has been delivered.
 	def delivered?
 		instance_variable_defined? :@value
 	end
 
+	alias realized? delivered?
+
+	# Deliver a value.
 	def deliver (value)
 		return if delivered?
 
@@ -31,6 +36,8 @@ class Thread::Promise
 
 	alias << deliver
 
+	# Get the value that's been delivered, if none has been delivered yet the call
+	# will block until one is delivered.
 	def value
 		return @value if delivered?
 
@@ -38,7 +45,7 @@ class Thread::Promise
 			cond.wait(mutex)
 		}
 
-		return @value
+		@value
 	end
 
 	alias ~ value

data/lib/thread/recursive_mutex.rb

@@ -10,6 +10,10 @@
 
 require 'thread'
 
+# A recursive mutex lets you lock in various threads recursively, allowing
+# you to do multiple locks one inside another.
+#
+# You really shouldn't use this, but in some cases it makes your life easier.
 class RecursiveMutex < Mutex
 	def initialize
 		@threads = Hash.new { |h, k| h[k] = 0 }
@@ -17,6 +21,7 @@ class RecursiveMutex < Mutex
 		super
 	end
 
+	# Lock the mutex.
 	def lock
 		@thread[Thread.current] += 1
 
@@ -25,6 +30,7 @@ class RecursiveMutex < Mutex
 		end
 	end
 
+	# Unlock the mutex.
 	def unlock
 		@thread[Thread.current] -= 1
 

data/thread.gemspec

@@ -1,12 +1,12 @@
 Gem::Specification.new {|s|
 	s.name         = 'thread'
-	s.version      = '0.0.2'
+	s.version      = '0.0.3'
 	s.author       = 'meh.'
 	s.email        = 'meh@schizofreni.co'
 	s.homepage     = 'http://github.com/meh/ruby-thread'
 	s.platform     = Gem::Platform::RUBY
-	s.summary      = 'Various extensions to the base thread stdlib.'
-	s.description  = 'Includes a thread pool, message passing capabilities, a recursive mutex, promise and future.'
+	s.summary      = 'Various extensions to the base thread library.'
+	s.description  = 'Includes a thread pool, message passing capabilities, a recursive mutex, promise, future and delay.'
 
 	s.files         = `git ls-files`.split("\n")
 	s.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: thread
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -12,7 +12,7 @@ cert_chain: []
 date: 2013-02-25 00:00:00.000000000 Z
 dependencies: []
 description: Includes a thread pool, message passing capabilities, a recursive mutex,
-  promise and future.
+  promise, future and delay.
 email: meh@schizofreni.co
 executables: []
 extensions: []
@@ -20,6 +20,7 @@ extra_rdoc_files: []
 files:
 - README.md
 - lib/thread/channel.rb
+- lib/thread/delay.rb
 - lib/thread/future.rb
 - lib/thread/pool.rb
 - lib/thread/promise.rb
@@ -48,5 +49,6 @@ rubyforge_project:
 rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
-summary: Various extensions to the base thread stdlib.
+summary: Various extensions to the base thread library.
 test_files: []
+has_rdoc: