parallelpipes 1.0

data/lib/parallelpipes.rb

@@ -0,0 +1,2322 @@
+# = Parallel Pipes
+#
+# <b> Genuine and easy parallelization comes to Ruby! </b>
+#
+# Quick Links: PPipe, PPipe::Methods, PPipe::Controller, PPipe::Message, PPipe::Log, PPipe::Reader
+#
+# To install: <tt> gem install parallelpipes </tt>
+#
+# = Overview
+#
+# Parallel Pipes is a simple, easy to use, MPI-like implentation for Ruby, allowing you to 
+# create and send messages between multiple ruby processes and allowing your code to run on 
+# multiple processors.
+#
+# Requires Ruby 1.9 +
+#
+# Written by Edmund Highcock (Copyright 2009-10)
+#
+# Current status: Production/Stable
+#
+# Version: 0.1.0
+#
+# This is free software released under the GNU GPL. It comes with no warranty.
+# You are free to modify and release this software, as long as due credit is given to the authors.
+# 
+#
+# = Introduction
+# A PPipe (Parallel Pipe) is a communicator, which can create and pass messages between a number of processes.
+#
+# These processes are separate operating system processes; thus, Parallel Pipes enables genuine (and easy) parallelization in Ruby Programs.
+#
+#
+# A Parallel Pipe has two distinct philosophies of use: 
+# 1. <b>Simple MPI:</b> Allows creating of new parallel processes and synchronous and asynchronous messaging passing between them.
+# 2. <b>Using a Controller</b>: Allows messaging passing, and also blocking synchronization (mutexes), and controlled access to shared resources, with automatic loading and saving of those resources.
+#                    
+# === Simple MPI
+#
+# This approach will be familiar to anyone who uses MPI proper. New processes can be created by forking and messages can be passed between them. Any message contents are acceptable where <tt>eval(contents.inspect) == contents</tt>. Messages can be sent and received both synchronously and asynchronously.
+#
+# <tt>ppipe = PPipe.new(3, false)</tt>
+#
+# <tt>pipe_no = ppipe.fork do 
+#
+# 		ppipe.i_send(:aeroplanes, ["boeing", "airbus"], tp: 0)  # asynchronous; note new ruby 1.9 hash syntax at end; tp means 'to pipe' 
+#
+# 		ppipe.w_recv(:finish, fp: 0) \# synchronous
+#
+# end
+#
+# message = ppipe.i_recv(:aeroplanes, fp: pipe_no) \#  asynchronous 
+#
+# ppipe.w_send(:finish, true, tp: pipe_no) \# synchronous
+#
+# puts 'waiting for asynchronous message'
+#
+# puts message.join.inspect \# ["boeing", "airbus"]
+#
+# ppipe.finish</tt>
+# 
+#
+# MPI old-timers may prefer the non block form of fork. Here we create 8 heavy-weight processes as if we were about to run a large parallel calculation.
+#
+# <tt>
+# ppipe = PPipe.new(8)
+#
+# ppipe.fork(7)
+#
+# my_rank = ppipe.mpn 
+# 
+# \# ...big calculation
+#
+# if ppipe.is_root
+#	ppipe.finish
+# else
+#	ppipe.die
+# end
+# </tt>
+#
+# === Using a Controller
+#
+# In this mode of operation previous messages still work, but several new functions are possible:
+#
+# ==== Synchronization:
+# 
+# Synchronization ensures that the protected sections of code in different process are never executed at the same time.
+#
+# <tt> ppipe= PPipe.new(10, true) \# creates a controller and ten pipes
+#
+# ppipe.fork do
+# 	ppipe.synchronize(:sleep_sync) do # :sleep_sync identifies the mutex; it could have been any symbol
+# 		10.times do
+# 			sleep rand
+# 			$stderr.print 'z'
+# 		end
+# 	end
+# end
+# 
+# ppipe.synchronize(:sleep_sync){$stderr.puts "This will never appear in between the zs, only before or after"} 
+#
+# ppipe.waitall </tt>
+#
+# Why $stderr I hear you ask? This is because the $stdout and $stdin of all sub-processes are routed to the main process by default (this can be changed).
+#
+# ==== Shared Resources
+# 
+# The controller provides synchronized access to shared resources. Only one process can access any shared resource at any given time. Shared resources can be any object where <tt>eval(object.inspect) = object</tt>. 
+# <tt> \# ... continuing from previous
+# 
+# new_pipe = ppipe.fork do
+# 	people = ppipe.get_shared_resource(:list_of_people)
+# 	people = {}
+# 	ppipe.return_shared_resource(:list_of_people, people)
+# 	ppipe.i_send(:people_initialized, true, tp: 0)
+#
+# 	ppipe.shared_resource(:list_of_people) do |people|
+# 		people[:Bill] = "Walker"
+# 		people # The last line in the block form must be the shared resource
+# 	end 
+# end
+#
+# ppipe.w_recv(:people_initialized)
+#
+# ppipe.shared_resource(:list_of_people) do |people|
+# 	people[:Tom] = "Climber"
+# 	people # The last line in the block form must be the shared resource
+# end </tt>
+# 
+# An important point to note is that synchronization and shared resource methods do not
+# guarantee the order in which processes execute them, only that they will never be executed at the same time. That is why the <tt>:people_initialized</tt> message is necessary, to ensure the order in which the first two accesses to the shared resource happen.
+#
+# ==== Auto Load Save
+#
+# Suppose before the first access to the shared resource <tt>:list_of_people</tt> we add a call:
+# 
+# <tt>ppipe.auto_load_save(:list_of_people, 'some_file.rb') </tt>
+#
+# If the file 'some_file.rb' does not exist, it will be created the first time :list_of_people is accessed, and it will be updated at every subsequent time. If the file 'some_file.rb' exists (e.g. from a previous run of the program), it will be reloaded. Thus, :list_of_people becomes a persistant object: it is remembered from one execution to the next.
+#
+# = Threading
+# 
+# === The Good News
+#
+# PPipe fully supports being combined with Ruby Threads. All controller mutexes are automatically thread mutexes as well:
+#
+# <tt> t1 = Thread.new{ppipe.synchronize(:thread_test){print 'abraca'; sleep rand; puts "dabra ";}}
+#
+# t2 = Thread.new{ppipe.synchronize(:thread_test){print 'hippo'; sleep rand; puts "potamus ";}}
+#
+# t1.join; t2.join </tt>
+# 
+# You can also pass messages between threads, just as you can between processes:
+#
+# <tt> first_thread = Thread.new do
+# 	second_thread_id = ppipe.w_recv(:stid)
+# 	ppipe.i_send(:message_to_second_thread, "I love Ruby!!", tt: second_thread_id) # tt means 'to thread'
+# end
+#
+# second_thread = Thread.new do
+# 	ppipe.i_send(:stid, Thread.current.object_id, tt: first_thread.object_id)
+#	puts ppipe.w_recv(:message_to_second_thread, ft: first_thread.object_id) # outputs 'I love Ruby!!'; ft means 'from thread' (obviously!)
+# 
+# end
+#
+# first_thread.join; second_thread.join</tt>
+#
+# But these threads don't have to be on the same process...
+#
+# <tt> 
+# new_pipe = ppipe.fork do
+# 	first_thread = Thread.new do
+#		ppipe.i_send(:ftid, Thread.current.object_id, tp: 0) 
+# 		second_thread_id = ppipe.w_recv(:stid, fp: 0)
+# 		ppipe.i_send(:message_to_second_thread, "I love Ruby!!", tp: 0, tt: second_thread_id) # Note that the order of tt and tp doesn't matter (because they form a hash) 
+# 	end
+# 	first_thread.join
+# end
+#
+# second_thread = Thread.new do
+# 	ppipe.i_send(:stid, Thread.current.object_id, tp: new_pipe)
+#	first_thread_id = ppipe.w_recv(:ftid, fp: new_pipe)
+#	puts ppipe.w_recv(:message_to_second_thread, ft: first_thread_id, fp: new_pipe) # outputs 'I love Ruby!!'
+# 
+# end
+#
+# second_thread.join</tt>
+#
+# === The Bad News
+#
+# It should always be borne in mind that mixing threads and processes is powerful but potentially a big problem causer. The biggest problems are when you fork with more than one live thread in operation. While you think you've only got one thread in the new process, in actual fact you have all of them.
+#
+# By default, PPipe checks if you're trying to do this and raises an error. You can turn this off by setting the option <tt> :thread_check </tt> to <tt>false</tt> (see PPipe.new).
+#
+# You can also set another option: <tt>:thread_safe</tt> to <tt>true</tt>. Then, whenever you fork, PPipe will automatically kill all threads in the new process except the current one.
+# 
+# If you have both the options set to false, you're on your own! Here be dragons!
+#
+# = Modules
+#
+# The primary purpose of the modules PPipe::Methods and PPipe::Controller are to provide the methods for the class PPipe. Therefore all the method documentation specifies having a ppipe as the receiver, e.g. 
+#
+# <tt> ppipe = PPipe.new(10, false)
+#
+# new_pipe_number = ppipe.fork do
+#	ppipe.i_send(:greetings, "Hello World", tp: 0)
+# end
+# 
+# puts ppipe.w_recv(:greetings)
+#
+# ppipe.finish</tt>
+#
+# <b>However</b>, you can also include these modules at the top level. In this case you call set_up_pipes instead of PPipe.new, and you don't need to put a PPipe as the receiver:
+#
+# <tt> 
+#
+# include PPipe::Methods
+#
+# include PPipe::Controller \# if you want to use the controller methods.
+#
+# set_up_pipes(10, false)
+#
+# new_pipe_number = fork do \# NB!!! fork has been redefined. You have to use Kernel.fork for the old fork
+#	i_send(:greetings, "Hello World", tp: 0)
+# end
+# 
+# puts w_recv(:greetings)
+# 
+# finish
+# </tt>
+#
+# 
+# You can also include these modules in any class you like, and now your class has become a parallel pipe!
+#
+# <tt> class MyClass
+#
+# 	include PPipe::Methods
+#
+# 	include PPipe::Controller \# if you want to use the controller methods.
+#
+# end
+#
+# my_object = MyClass.new
+#
+# my_object.set_up_pipes(10, false)
+#
+# new_pipe_number = my_object.fork do
+#	my_object.i_send(:greetings, "Hello World", tp: 0)
+# end
+# 
+# puts my_object.w_recv(:greetings)
+#
+# my_object.finish</tt>
+#
+
+
+
+# require 'box_of_tricks'
+require 'thread'
+require 'timeout'
+
+class Symbol
+	def +(other)
+		(self.to_s + other.to_s).to_sym
+	end
+
+end
+
+			
+
+
+
+class Thread
+	@@ppipe_threads=[]
+	def self.ppipe_new(*args, &block)
+		th = new(*args, &block)
+		@@ppipe_threads.push th
+		return th
+	end
+	class PPipeIRecv < StandardError
+	end
+	def self.ppipe_join
+		@@ppipe_threads.each do |thread|
+			raise PPipeIRecv.new("i_recv call with label '#{thread[:label]}' has not returned. Please kill it or make sure it returns, before calling fork")	if thread[:ppipe_message] and thread.alive?
+			thread.join if thread.alive? and not thread == Thread.current
+		end
+	end
+# 	def Thread.idpp
+# 		return Thread.current.idpp
+# 	end
+# 	def idpp
+# 		return object_id
+# 	end
+	def Thread.ppipe_list_live_ids
+		return Thread.list.inject([]){|arr, thread| arr.push thread.object_id if thread.alive?; arr}
+	end
+
+end
+
+class Object
+	
+	# returns false unless the object is a PPipe::Message. See PPipe::Message#method_missing for an explanation.
+	
+	def is_a_ppipe_message?
+		false
+	end
+end
+
+# class IO
+# 
+# 	def non_blocking_gets(timeout=0.01)
+# 		t = Thread.ppipe_new{th = Thread.current; th[:line] = nil; th[:line] = gets}
+# 		sleep timeout; t.kill;
+# 		return t[:line]
+# 	end
+# end
+
+class ArgumentError
+	def self.check(*values, &block)
+		values.each do |name, value, test_data|
+			if block
+				raise new("#{name} failed argument correctness test (value given was '#{value.inspect}')") unless yield(value, test_data)
+			else
+				is_array = test_data.class == Array
+				raise new("#{name} was of class #{value.class} instead of #{test_data.inspect} (value given was #{value.inspect})") unless (is_array ? test_data.include?(value.class) : value.class == test_data)
+			end
+		end
+	end
+end
+#
+#
+# Quick Links: PPipe, parallelpipes.rb, PPipe::Methods, PPipe::Controller, PPipe::Message
+#
+# Parallel Pipes is a simple, easy to use, MPI-like implentation for Ruby, allowing you to 
+# create and send messages between multiple ruby processes and allowing your code to run on 
+# multiple processors.
+# 
+# Written by Edmund Highcock
+#
+# Copyright 2009
+#
+# Current status: alpha
+#
+# This is free software released under the GNU GPL. It comes with no warranty.
+# You are free to modify and release this software, as long as due credit is given to the authors.
+#
+# Requires Ruby 1.9 +
+#
+# For more information, see the detailed introduction in parallelpipes.rb, or the documentation  in PPipe::Methods or PPipe::Controller for individual methods.
+
+
+class PPipe 
+
+	class DeadMutex < StandardError
+	end
+
+	class PPipeFatal < StandardError
+	end
+
+	class DeadPipe < StandardError
+	end
+
+	class UnassignedPipe < StandardError
+	end
+
+	class ThreadingError < StandardError
+	end
+
+	class NoController < StandardError
+		def initialize(mess="")
+			super(mess + "\nYou need a controller to use this function. Make a ParallelPipe with the second argument true")
+		end
+	end
+	
+	class ControllerError < StandardError
+	end
+
+	class DeadParallelPipe < StandardError
+		def initialize(mess="")
+			super(mess + "\nError: This parallel pipe is as dead as a doornail!")
+		end
+	end
+
+	class SelfReference < StandardError
+	end
+
+	class Ambiguity < StandardError
+	end
+	
+	class RecvTimeout < StandardError
+	end
+	
+# 	class LabelError < StandardError
+# 	end
+	
+	# A rough and ready logging module. Can be used independently of PPipe
+
+	module Log
+
+		@@log_file = nil
+		@@log_io = nil
+
+		# The verbosity of the object. Only log calls with a verbosity level lower than or equal to the verbosity will execute
+		
+		attr_accessor :verbosity
+		
+		
+		def self.log_file
+			@@log_file
+		end
+		
+		# Give a log file name for logging.
+
+		def self.log_file=(file)
+			@@log_file=file
+	# 		@@io = nil
+		end
+
+		# Give an io object for logging (overrides any file given for logging).
+
+		def self.io=(_io)
+			@@log_io = _io
+		end
+
+		# Deletes the log file if there is one
+		
+		def self.clean_up
+			File.delete @@log_file if FileTest.exist? @@log_file
+		end
+
+		@@log_group_options = [:t, :v]
+		@@log_individual_options = [:i, :f, :c, :p]
+		@@log_possible_options = @@log_group_options +  @@log_individual_options
+		class BadLogOption < StandardError
+		end
+		class BadVerbosity < StandardError
+		end
+		
+		# messages can be anything that defines <tt>to_s</tt>
+		#
+		# options is either a string of letters, or an array of symbols.
+		#
+		# options are:
+		# 
+		# * i - call inspect on every message
+		# * f - add the word 'Function' before the message, and the class of the logger afterwards (which will be PPipe if a PPipe is the receiver of the call)
+		# * c - add the word 'complete' after the message
+		# * v - specify the verbosity level of the call. This is a number 0-9 which immediately follows v. The messages will not be logged unless the instance variable @verbosity is greater than or equal to the verbosity level.
+		# * p - print mpn (my pipe number) of the ppipe. (Lets you know which process logged the message)
+		#
+		# 	ppipe.log('pv4', 'main calculation') # main calculation: my_pipe_number: 3
+		#	
+		#	ppipe.log 'fv2p', :analyze # Function: analyze: PPipe : my_pipe_number: 3
+		#
+		#	ppipe.log([:c, :v, 3], 'main calculation', 'analysis') # main calculation : complete 
+		#								# analysis : complete
+		#
+		# It is possible (within a class that includes PPipe::Log) to define default verbosity levels for different combinations of options. This verbosity level will be used if none is specified in the log call.
+		#
+		#	class MyClass
+		# 		include PPipe::Log
+		#
+		#		def set_up_log(file_name)
+		#			PPipe::Log.file_name = file_name
+		#			@log_defaults ||= {}
+		#
+		#			@log_defaults[[:f, :c].sort] = 7  # the sort call is very important. Don't (obviously) include :v in the array of options
+		#		end
+		#
+		#	end
+		#
+		#	my_object = MyClass.new
+		#	my_object.set_up_log('my_log_file.txt')
+		#	my_object.verbosity = some_verbosity
+		#	my_object.log 'fc', :window_open  # Function: window_open: MyClass: complete
+		#
+		#			# will only be logged if some_verbosity >= 7
+
+
+		def log(options, *messages)
+			return unless @@log_io or @@log_file
+			raise BadVerbosity.new("#{@verbosity.class}: #{@verbosity.inspect}") unless @verbosity.class == Fixnum and @verbosity > -1
+			options_in = options
+			options = options.to_s.split(//).map{|op| op.to_sym} if options.class == String or options.class == Symbol
+			options ||= []
+
+			if options.include? :v
+				@log_defaults ||= {}
+				vi = options.index(:v)
+				used_v = nil
+				unless options[vi+1] and options[vi+1].to_s =~ /^\d$/
+					return unless @verbosity >= (@log_defaults[(options - [:v]).sort] or @log_defaults[(options - [:v]).sort] or 9)
+					options.delete_at(vi)
+				else
+	# 				$stderr.puts "verbosity required is", options[vi+1].to_s.to_i, "verbosity is: ", @verbosity
+					return unless @verbosity >= options[vi+1].to_s.to_i  
+					options.delete_at(vi)
+					options.delete_at(vi)
+				end
+				
+			end
+			raise BadLogOption.new("#{options_in.inspect} --> " + (options - @@log_possible_options).inspect) if (options - @@log_possible_options).size > 0
+			messages.each do |message|
+				message = (options - @@log_group_options).inject(message){|message, option| message = send(:log_convert_ + option, message)}
+				if @@log_io
+					@@log_io.print message.to_s + "\n"
+				else
+					File.open(@@log_file, 'a'){|file| file.print message.to_s + "\n"}
+				end
+			end
+			if options.include? :t
+				log("Traceback \n" + caller.join("\n"))
+			end
+		end
+
+		def log_convert_i(message)
+			message.inspect  
+		end
+		def log_convert_f(message)
+			"Function: " + message + ": " + self.class.to_s  
+		end
+		def log_convert_c(message)
+			message + ": complete"
+		end
+		def log_convert_p(message)
+			message + " : my_pipe_number: #@my_pipe_number"   
+		end
+
+		private :log_convert_c, :log_convert_f, :log_convert_i, :log_convert_p
+
+		
+	end
+
+
+			
+	#
+	# Quick Links: PPipe, parallelpipes.rb, PPipe::Methods, PPipe::Controller, PPipe::Message
+	#
+	#
+	# A Message object is designed to make the syntax of receiving messages as beautiful and Ruby-esque as possible. It stores the label, contents and options of the message. At all times it tries to 'be' its contents, except if you want specific information out of it, like the label, options, pipe it was sent from (fp) or thread it was sent from (ft).
+	#
+	# NB: as well as defining the following methods (see below for their documentation):
+	# 
+	#	tp, tps, tp=, pop_tps # tp means 'to pipe(s)'
+	#
+	# Message also dynamically defines 12 other methods, with very similar meanings.
+	#
+	#	ep, eps, ep=, pop_eps # ep means 'exclude pipe(s)'
+	#	tt, tts, tt=, pop_tts # tt means 'to thread(s)'
+	#	et, ets, et=, pop_ets # et means 'exclude thread(s)'
+	#
+	# Footnote: 
+	#
+	# tp, ep, tt and et make up the Message's address. A message can be given an address before it can be sent. (Although if it has no address this is not an error, as it will be sent to every pipe and every process - see Methods#i_send). Messages that have been returned by t_recv, w_recv, i_recv, i.e. messages that have arrived at their destination, do not have an address.
+
+	class Message
+		
+		instance_methods.each{|method|  undef_method method unless [:object_id, :__send__, :dup].include? method}
+		
+		# see Methods#i_send
+		attr_reader :label, :contents, :options
+		
+		# Create a new message. The arguments are identical to those for Methods#i_send
+		
+		def initialize(label, contents, options={})
+			ArgumentError.check([:label, label, [Symbol, String, Fixnum, NilClass]], [:options, options, [Hash, NilClass]])
+			ArgumentError.check(['options[:tp]', options[:tp], [Integer, Fixnum, Array, NilClass]], ['options[:ep]', options[:ep], [Integer, Fixnum, Array, NilClass]], ['options[:tt]', options[:tt], [Integer, Fixnum, Array, NilClass]], ['options[:et]', options[:et], [Integer, Fixnum, Array, NilClass]]) if options
+			@label = label
+			@contents = contents
+			@options = options
+			check_ambiguities
+		end
+		def check_ambiguities
+			return unless @options
+			raise Ambiguity.new("this message (with label: #@label) has both ep and tp specified") if @options[:tp] and @options[:ep]
+			raise Ambiguity.new("this message (#@label) has both tt and et specified") if @options[:tt] and @options[:et]
+		end
+		private :check_ambiguities
+		
+		# The number of the pipe the message came from
+		
+ 		def fp
+			return @options[:fp]
+ 		end
+
+		# The id of the thread the message came from
+		
+		def ft
+			return @options[:ft]
+		end
+		
+		
+		#NB all the following four methods are dynamically defined. This is just documentation.
+		
+		# The pipe the message is addressed to (@options[:tp])
+		
+		def tp
+		end
+		
+		# A list of pipes the message is addressed to (returns @options[:tp] if @options[:tp] is an array, and [@options[:tp]] if it is an integer)
+		
+		def tps
+		end
+		
+		# Set the pipe the message is address to (value can be an Integer or and array of integers)
+		
+		def tp=(value)
+		end
+		
+		# Return a list of pipes the message is addressed to (see tps) and delete @options[:tp]
+		
+		def pop_tps
+		end
+		
+		
+		[:tp, :ep, :tt, :et].each do |address|
+			define_method(address){ return @options[address]}
+			define_method(address + '='.to_sym) do |value|
+				ArgumentError.check( ["options[#{address}]", options[address], [Integer, Fixnum, Array, NilClass]])
+				@options[address] = value
+				check_ambiguities
+			end
+			define_method(address + :s) do
+				check_ambiguities
+				return @options[address] ? (@options[address].class == Array ? @options[address] : [@options[address]]) : nil
+			end
+			define_method(:pop_ + address + :s) do
+# 				$stderr.puts methods
+				ans = __send__(address + :s)
+				@options.delete(address) if @options[address]
+				return ans
+			end
+		end
+		
+		# Was the message sent by Methods#w_send ?
+		
+		def blocking
+			return @options[:blocking]	
+		end
+
+		# parallelpipes.rb adds a method to Object: Object#is_a_ppipe_message? This method will return false for every object except a Message:
+		#
+		#	puts message.is_a_ppipe_message? # true
+		#	
+		#	puts message.contents.is_a_ppipe_message? # false
+		#
+		# See Message#method_missing for an explanation.
+		
+		def is_a_ppipe_message?
+			true
+		end
+		
+		def self.with_listening_thread(thread) # :nodoc:
+			new(nil, nil, nil).with_listening_thread(thread)
+		end
+		
+		# Internal use only
+		
+		def with_listening_thread(thread)
+			@thread = Thread.ppipe_new do
+				thread.join
+				message = thread[:message]
+				@contents = message.contents
+				@label = message.label
+				@options = message.options
+			end
+			return self
+		end
+		
+		# Has the message arrived? (see Methods#i_recv)
+		
+		def arrived?
+# 			raise ("This message is not listening for anything: it was not created by i_recv") unless @thread 
+			return true unless @thread
+			return !@thread.alive?
+		end
+		
+		# Stop checking to see if the message has arrived. (see Methods#i_recv)
+		
+		def kill
+			raise ("This message is not listening for anything: it was not created by i_recv") unless @thread 
+			@thread.kill
+		end
+		
+		# Wait until the message has arrived. (see Methods#i_recv)
+
+		
+		def join
+			raise ("This message is not listening for anything: it was not created by i_recv") unless @thread 
+# 			return self unless @thread
+			@thread.join
+			self
+		end
+		
+		# Any other methods (except for object_id) are passed to the message's contents...
+		#
+		#	message = PPipe::Message.new(:Winnie_the_Pooh, 'I like honey', {})
+		#
+		#	puts message # I like honey
+		#
+		#	puts message.inspect # "I like honey"
+		#
+		# 	puts message + ' very much' # I like honey very much
+		#
+		# 	puts message.length # 12
+		#
+		#	puts message.sub(/honey/, 'bees') # I like bees
+		#
+		# 	puts message.class # String
+		# 
+		# So how do you tell if something is a PPipe::Message? parallelpipes.rb adds a method to Object: Object#is_a_ppipe_message? This method will return false for every object except a Message:
+		#
+		#	puts message.is_a_ppipe_message? # true
+		#	
+		#	puts message.contents.is_a_ppipe_message? # false
+		#
+		
+		def method_missing(*args)
+			@contents.send(*args)
+		end
+		
+		# Internal use only
+		SPLITTER = "PPipe:::" # :nodoc:
+# 		private :SPLITTER
+		
+		def to_transmission
+			return SPLITTER + [@label, @contents, @options].inspect + "\n"
+		end
+		def self.from_transmission(line) # :nodoc: 
+			packets = line.split(SPLITTER, -1) # in case two lines got stuck together.
+			extra = packets.shift # something put into the pipe not by ppipe.
+# 			raise PPipeFatal.new("extra is #{extra.inspect}, line was #{line.inspect}") unless extra
+			if extra == nil # line was "", a new line submitted by the user
+				extra = ""
+			elsif extra == "" # lines was "PPipe:::[etc]", a ppipe message
+				extra = nil
+			else # Line was "stuffPPipe:::[etc]", a ppipe message with some stuff in front of it, or "stuff", a line submitted by the user
+			end
+				
+			if packets.size == 1
+# 				if line =~ /^PPipe:::(?<message>.+$)/ 
+# 				message = new(*eval($~[:message]))	
+				message = new(*eval(packets[0]))
+			elsif packets.size == 0
+				message = nil
+			else
+				raise PPipeFatal.new("Corrupted message: stuck together: #{line.inspect}")
+			end	
+			return extra, message
+		end
+	end
+
+	 	Log.io = $stderr
+# 	Log.log_file = "/dev/null"
+# 	Log.log_file = "ppipe_log.txt"
+	
+# 	class_accessor :print_messages, :thread_safe
+# 	@@print_messages = false
+	
+	@@thread_safe = true
+	
+	# Set an io object to write log messages to. Useful for debugging. Can be e.g. $stderr
+	
+	def self.log_io=(io_oject)
+	    Log.io = io_object
+	end
+
+	# Set a file to write log messages to. Useful for debugging.
+	
+	def self.log_file_name=(string)
+	    Log.file_name = string
+	end
+
+	# Make a new PPipe. All this does is call Methods#set_up_pipes(*args) - see this function for documentation.
+	
+	def initialize(*args)
+		set_up_pipes(*args)
+	end
+	
+	
+	module MethodMissing
+	
+	# If redirect is on, the $stdout of any child processes is redirected to the root pipe. method_missing passes the methods to a pipe where this output is stored. Thus, if you call ppipe.gets, you will get the next thing out put by any child process.
+	
+	def method_missing(*args)
+		raise DeadParallelPipe unless @alive
+		raise PPipeFatal.new("calling this doesn't make any sense unless redirect is on") unless @redirect
+		check_messages
+		return @user_end.send(*args)
+	end
+	
+	end
+	
+	# PPipe requires a method of reading pipes that will not block even if the pipe is empty, is at eof, or has not been written to yet. configure_reader dynamically defines this method, which is called read_pipe
+	# 
+	# Reader is included in PPipe. It can also be included independently in any class
+
+	module Reader
+		include Log
+		include Timeout
+# 		class PPipeReaderError < StandardError
+# 		end
+		
+		# read_pipe is defined dynamically...
+		
+		# Read all the contents of the pipe. Return nil if the pipe is empty. Never, ever, ever, ever block!
+		
+		def read_pipe(pipe)
+		end
+		
+		# Get the next line from the pipe. Return nil if the pipe is empty or at eof. Blocks if the pipe is not empty but does not contain a complete line.
+		
+		def get_line(pipe, sep = $/)
+		end
+		
+		
+		
+		# These work on OS X 
+		
+		def read_stat_size(pipe)
+			size = pipe.stat.size
+			return nil if size == 0
+			log 'v8', 'running read_stat_size'
+			return pipe.read(size)
+		end
+		private :read_stat_size
+		
+		def read_stat_size_get_line(pipe, sep = $/)
+			return nil if pipe.stat.size == 0
+			return pipe.gets
+		end
+		private :read_stat_size_get_line
+		
+		
+
+		# These work on Linux (openSUSE tested so far)
+		
+		def set_up_joke_pipe
+			unless @joke_read
+				@joke_read, @joke_write = IO.pipe 
+				@joke_write.puts 'jokes!'
+				@joke_write.close
+			end
+		end
+		private :set_up_joke_pipe
+		
+		def read_joke_pipe_select(pipe)
+			set_up_joke_pipe
+			message = ""
+			while select([@joke_read, pipe])[0].include? pipe
+				begin
+					message += pipe.readpartial(4096)
+				rescue EOFError
+					break
+				end
+			end
+			return message.length > 0 ? message : nil
+		end
+			
+		private :read_joke_pipe_select
+		
+		def read_joke_pipe_select_get_line(pipe, sep = $/)
+			set_up_joke_pipe
+			if select([@joke_read, pipe])[0].include? pipe
+				return pipe.gets(sep)
+			else
+				return nil
+			end
+		end
+		private :read_joke_pipe_select_get_line
+		
+		
+		
+		# This method does not work! Threading issues mean that the whole process sometimes hangs on the gets even though the gets call is in a separate thread. It may work in a future version of Ruby (when they get rid of the GIL)
+		
+		def read_gets_timeout(pipe)
+			message = ""
+			loop do
+				fetched = nil
+				begin 
+					timeout(0.001){fetched = pipe.gets} 
+				rescue 
+					break
+				end
+				break unless fetched
+				message += fetched
+			end
+			log 'v8', 'read this message: ' + message if message.size > 0
+			return message.size > 0 ? message : nil
+		end
+
+		private :read_gets_timeout
+
+		# Works sometimes... but fails if a process writes to the pipe at exactly the same time as it is being read.
+
+		def read_atime_readpartial(pipe)
+	# 		p pipe.stat.mtime.to_f - pipe.stat.atime.to_f
+			return nil unless pipe.stat.mtime.to_f > pipe.stat.atime.to_f 
+			p pipe.stat.ctime.to_f, pipe.stat.mtime.to_f, pipe.stat.atime.to_f 
+			ans =  pipe.readpartial(4096)
+			p pipe.stat.ctime.to_f, pipe.stat.mtime.to_f, pipe.stat.atime.to_f 
+
+			return ans.size > 0 ? ans : nil
+		end
+
+		private :read_atime_readpartial
+
+		# Doesn't work!
+		
+		def read_ungetc_readpartial(pipe)
+	# 		log 'fv8', 'read_ungetc_readpartial'
+			ans = ""
+			loop do
+				pipe.ungetc(84)			
+				fetched = pipe.readpartial(4096)
+	# 			log 'v8', 'fetched was...',  fetched
+				if fetched.length > 1
+					log 'v8', fetched
+					ans += fetched[1, (fetched.length - 1)]
+				else
+					break
+				end
+			end
+			return ans.length > 0 ? ans : nil
+		end
+		private :read_ungetc_readpartial
+		
+		def determine_read(pipe, message)
+	# 		fetched = ""
+	# 		puts 'fetching...'
+	# 		mutex = Mutex.new
+	# 		threads = []
+			fetched = {}
+			
+			start_time = Time.now.to_f
+			while Time.now.to_f - start_time < 3.0 
+				[:read_stat_size, :read_joke_pipe_select].each do |method|
+					fetched[method] ||= ""
+					fetched[method] += (send(method, pipe) or "")
+					log 'v8i', 'fetched...' + fetched[method] if fetched[method].size > 0
+					return method if fetched[method] == message
+	# 				raise PPipeReaderError.new("Should have matched fetched: #{fetched.inspect} to message: #{message.inspect}") if fetched.size 
+					sleep 0.0001
+				end
+			end
+			raise PPipeFatal.new("Failed to determine the correct pipe reading method")
+		end
+		private :determine_read
+		
+		#The best way of defining Reader#read_pipe is operating system dependent. Work out which is the best way and then define the method read_pipe to be this method.
+		
+		def configure_reader
+			@verbosity ||= 0  # for logging purposes
+			pipes = [nil, IO.pipe]
+
+			pipe = IO.pipe
+			
+			pipes[1][1].sync = true
+			pipe[1].sync = true
+
+			my_pipes = []
+
+			pid = Kernel.fork
+			
+			if pid
+				pipe[1].close
+				my_pipes.push pipe[0]
+				pipes[1][0].close
+				pipes[1] = pipes[1][1]
+	# 			pipes[1].puts
+	# 			sleep 0.002
+				log 'v8', 'sending pears'
+				pipes[1].sync = true
+				pipes[1].print('pears' + "\n")
+	# 			cmd = [2].pack("S")
+	# 			pipes[1].ioctl(5, cmd)
+	# 			sleep 1
+				log 'v8',  'waiting for apples...'
+				method = determine_read(my_pipes[0], "apples\nare\nnice\n")
+				log 'v8', method
+				self.class.send(:alias_method, :read_pipe, method)
+				self.class.send(:alias_method, :get_line, method + :_get_line)
+				my_pipes[0].close
+				pipes[1].close
+				return method
+			else
+				pipes[1][1].close
+				my_pipes.push pipes[1][0]
+				pipes[1] = nil
+				pipe[0].close
+				pipes[0] = pipe[1]
+				pipes[0].sync = true
+				log 'v8', pipes.inspect
+	# 			sleep 0.5
+				log 'v8', 'waiting for pears'
+				log 'v8', determine_read(my_pipes[0], "pears\n")
+				
+					
+				log 'v8', 'sending apples'
+				pipes[0].print("apples\nare\nnice" + "\n")
+				pipes[0].flush
+				exit
+			end
+		end
+	end
+
+# 	if $0 == __FILE__
+# 		Log.io = $stderr
+# 		include PPipeReader
+# 		@verbosity = 9
+# 		100.times{$stderr.puts "\n\n", configure_reader}
+# 	end
+
+	#
+	# Quick Links: PPipe, parallelpipes.rb, PPipe::Methods, PPipe::Controller, PPipe::Message
+	#
+	# The primary purpose of this module is to provide the methods for the class PPipe.
+	# Therefore all the method documentation specifies having a PPipe as the receiver. However, it is perfectly possible to use this module as a module in its own right; see the section Modules in parallelpipes.rb
+	
+	module Methods
+		
+	include Reader
+	
+	include Log
+
+	# my pipe number - the pipe number of the PPipe
+	attr_reader :mpn
+	
+
+	# is the ppipe the root ppipe (the first one to be created)?
+	attr_reader :is_root 
+	
+	# see set_up_pipes
+	attr_reader :thread_safe, :tt_required, :tp_required, :redirect
+
+	
+	# Set a number of pipes, and (optionally) start the controller. The parallel pipe will be able to fork one fewer times than the number of pipes you give it (the first one is for itself). There is a maximum number of pipes you can have open in any one process (this set by Ruby, or the operating system). This number includes all pipes opened by every PPipe, and any pipes opened elsewhere. The number is about 100
+	#
+	# If use_controller is set to true, a separate controller process will be created, allowing synchronization and access to shared resources (see Controller in the head notes).
+	#
+	# Options are:
+	#
+	# * controller_refresh - set the refresh rate of the controller. Higher rates mean faster performance but more CPU usage. See PPipe#controller_refresh= for some stats.
+	# * thread_check - true or false; default true (see parallelpipes.rb)
+	# * thread_safe - true or false; default false (see parallelpipes.rb)
+	# * redirect - true or false; default true. Should the $stdin and $stdout of the child process be hooked up to the parent PPipe?  
+	# * verbosity - 0 to 9; how much debug info do you want PPipe to print into log_io or log_file_name ? Useful settings are 1 (just prints received messages), 2 (prints sent messages as well) and 7 (prints every function call). See PPipe::Log.
+	#
+	# e.g.
+	#
+	# if using the class PPipe
+	#
+	#	ppipe = PPipe.new(20, true)
+	#	ppipe = PPipe.new(10, false, thread_check: false, log_io: $stderr)
+	#
+	# if using the module PPipe::Methods:
+	#	
+	#	set_up_pipes(20, true)
+	#	set_up_pipes(10, false, thread_check: false, log_io: $stderr)
+
+	
+	def set_up_pipes(num_pipes, use_controller, options={})
+		ArgumentError.check([:num_pipes, num_pipes, Fixnum], [:options, options, Hash], [:use_controller, use_controller, [TrueClass, FalseClass]])
+		raise PPipeFatal.new("Only the root PPipe can set up pipes (otherwise chaos would ensue!)") unless @is_root == true or @is_root == nil
+		raise PPipeFatal.new("Attempting to set up pipes when this ppipe is already set up (call die or finish first if you want to set up a bunch of new pipes)") if @alive
+		
+		@alive = true
+		@pipes = [nil] + (1...num_pipes).to_a.map{|a| IO.pipe}
+		@pipe_counter = 1 # 0 is the root process
+		@my_pipes = []
+		@mutexes = {}
+		@messages = {}
+		@user_end, @my_end = IO.pipe
+		@is_root = true
+		@mpn = 0
+		@max_mutex_id =  0
+		@envelope = 0
+		@pids = {}
+		@redirect = true unless options[:redirect] == false
+		@controller_asleep = false
+		@thread_mutexes = {}
+		@shared_resource_mutexes = {}
+		@weak_synchronization = options[:weak_synchronization]
+		@check_messages_mutex = Mutex.new
+		@thread_safe = options[:thread_safe] 
+		@thread_check = true unless options[:thread_check] == false
+# 		@print_messages = options[:print_messages] 
+		@tt_required = options[:tt_required] 
+		@tp_required = options[:tp_required] 
+# 		@fvb = 6
+		@last_segment = ""
+		@verbosity = (options[:verbosity] or $log_verbosity or 0)
+		@log_defaults = {}
+		@log_defaults[[:f, :p].sort] = 7
+		@log_defaults[[:f, :p, :c].sort] = 7
+		@message_counter = 0
+		@finished_pipes = {}
+
+		#These parts must happen after initialization of variables
+		configure_reader
+		begin
+			controller_refresh = (options[:controller_refresh] or 0.001)
+			start_controller(controller_refresh) if use_controller
+		rescue NoMethodError => err
+			log 'v3', err
+			log 'v3', err.class, err.backtrace
+			raise PPipeFatal.new("Tried to use a controller without including the Controller module")
+		end
+	end
+
+	# Create a new process. If num_forks is unspecified, creates one new process, and returns the pipe number of that process. If num_forks is specified, creates num_forks new processes and returns an array of pipe numbers. 
+	#
+	# If a block is given, the child process(es) will execute the block and then exit
+	#
+	# If there is no controller, only the root PPipe can fork. (Otherwise there is no way to prevent two processes forking at the same time).
+
+	def fork(num_forks=nil, &block)
+ 		ArgumentError.check([:num_forks, num_forks, [NilClass, Fixnum]])
+		raise DeadParallelPipe unless @alive
+		raise PPipeFatal.new("Only the root parallel pipe can fork (you can test this with .is_root), unless there is a controller. Otherwise it is impossible to synchronize forking, and to provide unique ids to all new processes.") unless @is_root or @controller
+		forks = []
+		lock(:ppipe_fork_mutex) if @controller 
+		(num_forks or 1).times do
+			log 'fpv', :fork
+ 			log 'v9', 'about to check messages before forking'
+			check_messages
+			raise PPipeFatal.new("insufficient pipes") if @pipe_counter >= @pipes.size
+ 			log 'v9', 'checked messages before forking'
+			pipe_counter 	= @pipe_counter
+			new_pipe = IO.pipe
+			@pipes[@mpn] = new_pipe[1]
+			cur_pid = Process.pid
+			begin
+			  Thread.ppipe_join
+			rescue => err
+			  (unlock(:ppipe_fork_mutex) if @controller; raise err)
+			end
+			Thread.list.each{|th| (unlock(:ppipe_fork_mutex) if @controller; raise ThreadingError.new("Must have only one live thread when calling fork, if PPipe.thread_safe == true (suggest you join all other threads before calling). PPipe.thread_safe can be set to false, but this can lead to many errors if forks are made with multiple live threads.")) if th.alive? and not th == Thread.current} if @thread_check
+			pid = Process.fork
+			if not pid
+				Thread.list.each{|th| th.kill if th.alive? and not th == Thread.current} if @thread_safe
+				@is_root = false
+				@mpn = pipe_counter
+				log 'pv3', :forked
+				log 'v9', "My New Pipe No is: #{pipe_counter}"
+				@pipes[pipe_counter][1].close
+				@my_pipes = [[cur_pid, @pipes[pipe_counter][0]]]	
+				@pipes[pipe_counter] = nil #@pipes[pipe_counter][0] 
+				@user_end, @my_end = IO.pipe
+				if @redirect
+					$stdout = @pipes[0]
+					$stdin = self #@user_end
+				end
+ 				log 'v9', 'about to yield', @mpn
+				@thread_mutexes = {}
+				@shared_resource_mutexes = {}
+				@messages = {}
+				@old_controllers = {}
+				@message_counter = 0
+				(block.call; exit) if block
+				return nil
+			end
+# 				@my_pipes.each{|(pid, pipe)| pipe.close}
+# 				@pipes.slice(0...@mpn).each{|pipe| next unless pipe; pipe.close}
+			@my_pipes.push [pid, new_pipe[0]]
+			new_pipe[1].close
+			i_send(:add_pid, [pipe_counter, pid], {evaluate: true, tc: true})
+			i_send(:increase_pipe_counter, true, {evaluate: true, tc: true})
+			forks.push pipe_counter
+		end
+		unlock(:ppipe_fork_mutex) if @controller 
+		return num_forks ? forks : forks[0]
+	end
+
+	def add_pid(array)
+		ArgumentError.check([:pid_array, array, Array])
+		@pids[array[0]] = array[1]
+	end
+	private :add_pid
+	def increase_pipe_counter(contents=nil)
+# 		ArgumentError.check([:pid_array, array, Array])
+		raise DeadParallelPipe unless @alive
+		log 'fpv', :increase_pipe_counter 
+		log 'v7', 'pipe_counter currently', @pipe_counter
+		if @pipe_counter == @mpn
+			@pipe_counter+=1
+		else
+			unless @finished_pipes[@pipe_counter] # i.e. the process finished before this process heard about its existence
+				@pipes[@pipe_counter][0].close
+				@pipes[@pipe_counter] = @pipes[@pipe_counter][1]
+			end
+	# 		@pipes[@pipe_counter].puts "testing"
+			@pipe_counter += 1
+		end
+		
+	end
+	private :increase_pipe_counter
+# 	def gets
+# 		raise DeadParallelPipe unless @alive
+# 		check_messages
+# 		return @user_end.non_blocking_gets
+# 	end
+	
+
+	def check_messages(check_options={})
+		log 'v9', :check_messages
+		raise DeadParallelPipe unless @alive
+		@check_messages_mutex.lock
+		@last_segments ||= {}
+		@my_pipes.each_with_index do |(pid, pipe), index|
+			input = read_pipe(pipe)
+			next unless input
+			@last_segments[pid] ||= ""
+			
+			@old_last_segment = @last_segments[pid] #for debugging only
+
+			lines = (@last_segments[pid] + input).split("\n", -1)
+			@last_segments[pid] = lines.pop
+
+ 			log 'v8', "input: #{input.inspect}\nlines: #{lines.inspect}\n@last_segment: #{@last_segments[pid].inspect}\n@old_last_segment: #{@old_last_segment.inspect}\n"
+# 			raise PPipeFatal.new("problem with lines: #{lines.inspect} (input was #{input.inspect}, @last_segment was #{@old_last_segment.inspect}); should have size greater than 0") unless lines.size > 0
+			next unless lines.size > 0
+			lines.each do |line|
+# 				packets = 
+				extra, message = Message.from_transmission(line)
+				@my_end.puts extra if extra # extra will be something put into the pipe by the user, and not by PPipe
+
+# 				messages.each do |message| #note intentional assignment, not equality test!!
+				next unless message
+					log 'v1', @mpn.to_s + ": " + line #if @print_messages
+					if message.options[:evaluate]
+						send(message.label, message.contents) if !message.tt or message.tt == tid
+					else
+						to_threads = (message.pop_tts or (Thread.ppipe_list_live_ids - (message.pop_ets or [])))
+						to_threads.each do |id|
+							@messages[id] ||= {}
+							@messages[id][message.label] ||= {}
+							@messages[id][message.label][message.fp] ||= {} #fp = from pipe number
+							@messages[id][message.label][message.fp][message.ft] ||= []
+							
+							@messages[id][message.label][message.fp][message.ft].push message
+						end
+					end
+# 				end
+			end
+		end
+		@check_messages_mutex.unlock
+		log 'v9c', :check_messages
+		return @messages[tid]
+	end
+	private :check_messages
+
+	# returns Thread.current.object_id
+
+	def tid
+		return Thread.current.object_id
+	end
+
+	# When a new process is created, there is a delay before that new process has a pipe assigned to it in every other process. This method checks whether the new process (with pipe number equal to pipe_no) has had its pipe assigned in the calling process.
+	#
+	# pipe_no can be the pipe number of the calling process
+	
+	def assigned?(pipe_no)
+		raise PPipeFatal.new("tried to call assigned? for pipe #{pipe_no} when the highest pipe number is #{@pipes.size - 1} (remember pipe numbers are 0 based)") if pipe_no >= @pipes.size  
+		check_messages
+		return @pipe_counter > pipe_no
+	end
+	
+	# args is a list of pipe numbers. Wait till Methods#assigned?(pipe_no) is true for each pipe_no.
+	#
+	# e.g.
+	#
+	#	wait_till_assigned(2,5,9)
+	#
+	# or
+	#
+	# 	ppipe = PPipe.new(7, false)
+	# 	pipe_numbers = ppipe.fork(6) # pipe_numbers is [1,2,3,4,5,6] 
+	#	wait_till_assigned(*pipe_numbers)
+	# 	
+	
+	def wait_till_assigned(*args)
+		args.each do |pipe_no|
+			until assigned?(pipe_no)
+				sleep 0.01
+			end
+		end
+	end
+
+
+	# <tt>i_send(label, contents, options={})
+	#
+	# i_send(message, options={})</tt>
+	#
+	# Immediate Send
+	#
+	# Send a message and don't wait for the destination pipe(s) to confirm they have received it (i.e. this call will return immediately)
+	#
+	# * <i>label</i> must be a Symbol, String or Integer
+	# * <i>contents</i> can be any object where <tt>eval(contents.inspect) == contents</tt>, except for <tt>nil</tt> or <tt>false</tt>
+	# * <i>message</i> must be a PPipe::Message
+	# Possible options are:
+	#
+	# One of:
+	#
+	# * <i>tp</i> (Integer or Array): the pipe to send the message to or a list of pipes to send the message to 
+	# * <i>ep</i> (Integer or Array): a pipe <i>not</i> to send the message to or a list of pipes <i>not</i> to send the message to
+	#
+	# Note: if you don't specify tp, the message will be sent to every currently assigned pipe (excluding pipes in ep if it is specified) (think broadcast in standard MPI) . However, be warned: a new process that you have just created may not yet be known about yet in every other process. Therefore, if you send a message to every pipe just after you have called fork in a different process, the newly created process might not get the message. See Methods#wait_till_assigned.
+	#
+	# One of:
+	#
+	# * <i>tt</i> (Integer or Array): the thread id to send the message to or a list of thread ids to send the message to 
+	# * <i>et</i> (Integer or Array): a thread id <i>not</i> to send the message to or a list of thread ids <i>not</i> to send the message to	#
+	#
+	# Note: if you specify neither, the message will be sent to every thread 
+	#
+	# Any of:
+	# 
+	# * <i>reject_unassigned</i> (true or false, default false): when a new process is created, its existence is not known immediately to every other process (a message is send out automatically and is processed at some point). If you send a message to a pipe that is currently unassigned to a process, PPipe will assume that you know such a process is about to be created, and wait till it has been informed that the new process has been created. If that process is never created, i_send will hang. You can change this behaviour by setting reject_unassigned to true. If you do, PPipe will return an error if the pipe is unassigned.
+	# * <i>blocking</i> (true or false, default false): wait until the other process(es) or thread(s) have received the message. To make your code more clear, it is recommended that you do not use this option, and instead use Methods#w_send. 
+	# * <i>tc</i> (true or false, default false): If no tp or tps is specified, the message will be sent to every pipe, except the controller - unless tc == true. Not needed for normal use (used mostly for internal messages).
+	# 
+	# e.g.
+	# 	i_send(:trees, ['birch', 'pine'], tp: 5)
+	#
+	# 	i_send(:heroes, ['David', 'Perseus'], tp: [2,5,21], tt: 6346023, reject_unassigned: true)
+	#
+	# 	i_send(:greeting, 'Hello every other pipe')
+	#
+
+	def i_send(*args)
+		log 'fpv', :i_send
+		@message_counter += 1
+		message = nil
+		case args.size
+		when 3
+			
+			message = Message.new(*args)
+		when 2
+			case args[0].class
+			when PPipe::Message
+				message = args[0]
+				message.options[:fp] = nil; message.options[:ft] = nil
+				args[1].each{|key, value| message.options[key] = value}
+			else
+				message = Message.new(*args)
+			end
+		when 1
+			raise ArgumentError.new("Argument to i_send must be a PPipe::Message if only one argument provided") unless args[0].is_a_ppipe_message?
+			message = args[0]
+			message.options[:fp] = nil; message.options[:ft] = nil
+		when 0
+			raise ArgumentError.new("No argument supplied to i_send")
+		end
+		raise ArgumentError.new("Specifying fp or ft when sending messages is redundant; did you mean to specify tp or tt?") if message.fp or message.ft 
+		raise DeadParallelPipe unless @alive
+		raise ArgumentError.new("Contents cannot be nil or false; label #{label}; pipe_no #{pipe_no}") unless message.contents
+		log 'v9', "To pipe_no: " + message.tp.to_s
+		broadcast = message.tps ? false : true
+
+# 		to_pipes = message.tp ? (message.tp.class == Array ? message.tp : [message.tp]) :  (0...@pipes.size).to_a
+		message.options[:fp] = @mpn #fp = from pipe number
+		message.options[:ft] = tid #ft = from thread
+
+# 		$stderr.puts 'calling broadcast' if broadcast
+		to_pipes = (message.pop_tps or ((0...@pipes.size).to_a - (message.pop_eps or [])))
+		to_pipes.each do |pipe_no|
+			next if @controller and pipe_no == @controller and broadcast and not message.options[:tc]
+			if pipe_no == @mpn #tp = to pipe number
+				if message.options[:evaluate]
+					log 'v9', 'evaluating locally...'
+					send(message.label, message.contents) if !message.tt or message.tt == tid
+				else
+					
+					to_threads = (message.tts or (Thread.ppipe_list_live_ids - (message.ets or [])))
+						to_threads.each do |id|
+						@messages[id] ||= {}
+						@messages[id][message.label] ||= {}
+						@messages[id][message.label][@mpn] ||= {} 
+
+						@messages[id][message.label][@mpn][message.ft] ||= [] 
+						@messages[id][message.label][@mpn][message.ft].push message
+					end
+				end
+			elsif @pipes[pipe_no].class == IO
+				begin
+# 					$stderr.puts message.class
+					(message.options[:re] = @envelope; @envelope+=1) if message.blocking #re = return envelope
+					log 'v2', "#@mpn->#{pipe_no}: #{message.to_transmission}"
+					@pipes[pipe_no].print message.to_transmission
+					if message.blocking
+						if message.tts 
+							message.tts.each do |thread_id| 
+								w_recv(message.label + message.options[:re].to_s.to_sym, fp: pipe_no, ft: thread_id, timeout: message.options[:timeout])
+							end
+						else
+							w_recv(message.label + message.options[:re].to_s.to_sym, fp: pipe_no, timeout: message.options[:timeout])
+						end
+					
+	# 					@messages[tid].delete(@messages[tid].key(label + no.to_s))
+					end
+						
+				rescue Errno::EPIPE
+					pipe_finished(pipe_no)
+# 					i_send(:pipe_finished, pipe_no, evaluate: true, tp: @mpn) 
+					i_send(:pipe_finished, pipe_no, evaluate: true, tc: true) 
+# 					@pipes[pipe_no] = nil; @pids.delete(pipe_no)
+					raise DeadPipe.new("This pipe: #{pipe_no} is dead; probably the process it corresponds to has terminated or called die") unless broadcast
+
+				end
+			elsif pipe_no >= @pipes.size
+				raise PPipeFatal.new("Pipe #@mpn tried to send a message to pipe #{pipe_no} out of only #{@pipes.size} pipes")
+			elsif @finished_pipes[pipe_no]
+				raise DeadPipe.new("This pipe: #{pipe_no} is finished; probably the process it corresponds to has terminated or called die") unless broadcast
+			elsif !@pipes[pipe_no]
+				pipe_finished(pipe_no)
+				i_send(:pipe_finished, pipe_no, evaluate: true, tc: true)
+				raise DeadPipe.new("This pipe: #{pipe_no} is dead; probably the process it corresponds to has terminated") unless broadcast
+			elsif @pipes[pipe_no].class == Array
+				if message.options[:reject_unassigned]
+					raise UnassignedPipe.new("Pipe #@mpn attempted to write to a pipe that has not yet been assigned to a process") unless broadcast 
+				elsif !broadcast
+					sleep 0.001
+					check_messages
+# 					$stderr.puts 'Houston, we would have had a problem'; exit
+					redo
+				end
+			else
+				raise PPipeFatal.new("Unknown error in i_send from pipe #@mpn: @pipes evaluted at the requested pipe_no is neither a pipe, nil or an array")
+			end
+		end
+		log 'fpcv6', :i_send
+	end
+
+	# Wait Send
+	#
+	# Calls i_send with <i>blocking</i> set to <tt>true</tt>.
+	#
+	# The call will not return until the other process(es) or thread(s) has received the message. Thus, doing a w_send, w_recv is a way of ensuring that two processes are at a given place at the same time.
+	#
+	# If you specify more than one pipe for a blocking message to be sent to, it will wait till <i>all</i> the destination processes have confirmed they have received it. (NB Specifying ep or neither ep or tp (see i_send) means that you are potentially sending the message to more than one process).
+	#
+	# With threads, it is slightly different. If you specify tt, it will wait till all the threads you specified have confirmed receiving the message. However, if you specify et or neither et or tt, it will return when the <i>first</i> thread confirms it has received it. This is so one doesn't have to specify tt every time a blocking message is sent (which would be tedious!).
+
+	def w_send(*args)
+		message = nil
+		case args.size
+		when 3
+			message = Message.new(*args)
+		when 2
+			case args[0].class
+			when PPipe::Message
+				message = args[0]
+				args[1].each{|key, value| message.options[key] = value}
+			else
+				message = Message.new(*args)
+			end
+		when 1
+			raise ArgumentError.new("Argument to w_send must be a PPipe::Message if only one argument provided") unless args[0].is_a_ppipe_message?
+			message = args[0]
+		when 0
+			raise ArgumentError.new("No argument supplied to w_send")
+		else 
+			raise ArgumentError.new("Number of arguments supplied to w_send should be 1, 2 or 3")
+		end
+		message.options[:blocking] = true
+# 		$stderr.puts message.inspect, message.class
+		i_send(message)
+	end
+#	private :w_send
+# 	alias :w_send :w_send
+
+	# Try Receive
+	#
+	# Try to receive a message with the given <i>label</i>. If no message has arrived return <tt>nil</tt> immediately. 
+	#
+	# Possible options are:
+	#
+	# One of:
+	#
+	# * <i>fp</i> (Integer): the pipe number the message is coming from 
+	# * <i>fps</i> (Array): a list of pipe numbers the message might come from  
+	#
+	# Note: if you specify neither, the method will return the first message with the correct label from any pipe.
+	#
+	# One of:
+	#
+	# * <i>ft</i> (Integer): the thread id the message is coming from 
+	# * <i>fts</i> (Array): a list of thread ids the message might come from  
+	#
+	# Note: if you specify neither, the method will return the first message with the correct label from any thread.
+	#
+ 
+	
+	
+	def t_recv(label, options={}) # => nil or PPipe::Message
+		ArgumentError.check([:label, label, [Symbol, String, Fixnum]], [:options, options, Hash])
+		
+		raise DeadParallelPipe unless @alive
+# 		$stderr.puts options.class
+		raise ArgumentError.new("Specifying tp or tt when receiving messages is redundant; did you mean to specify fp or ft?") if options[:tt] or options[:tp]
+		if options[:fp]
+			raise Ambiguity.new("specified fp and fps simultaneously") if options[:fps]
+			fps = [options[:fp]]
+		elsif options[:fps]
+			fps = options[:fps]
+		else
+			fps = nil
+		end
+		if options[:ft]
+			raise Ambiguity.new("specified fp and fps simultaneously") if options[:fts]
+			fts = [options[:ft]]
+		elsif options[:fts]
+			fts = options[:fts]
+		else
+			fts = nil
+		end
+
+		message = nil
+		index = nil
+
+		check_messages
+#   		$stderr.puts @messages.inspect
+		return nil unless @messages[tid] and @messages[tid][label] 
+		search_by_pipe = fps ? @messages[tid][label].values_at(*fps).compact : @messages[tid][label].values.compact
+		search_by_pipe.each do |list|
+			next unless list
+			search_by_thread = fts ? list.values_at(*fts).compact : list.values.compact
+			search_by_thread.each{|th_list| message = th_list.shift if th_list.size > 0}
+			break if message				
+		end
+
+
+		if message and message.blocking
+# 			$stderr.puts 'found blocking message', message.label
+			loop do
+				begin
+					i_send((message.label+message.options[:re].to_s).to_sym, true, {tt: message.ft, tp: message.fp})
+					break
+				rescue UnassignedPipe
+					log 'v3', 'rescued unassigned pipe in w_recv, retrying...'
+					check_messages
+				end
+			end
+		end
+		return message
+	end
+
+	#
+	# Wait Receive
+	#
+	# Receive a message with the given <i>label</i>. Does not return until the message has been received. 
+	# 
+	# Possible options
+	#
+	# * timeout (seconds): raise a PPipe::RecvTimeout error if the message has not arrived after the give number of seconds
+	# * refresh_time (seconds, default is 0.001): The time between rechecking to see if the message has arrived.
+	#
+	# For other possible <i>options</i>, see t_recv .
+	#
+	# NB: all this does is keep calling t_recv in a loop!
+	
+	def w_recv(label, options={})
+		ArgumentError.check([:label, label, [Symbol, String, Fixnum]], [:options, options, Hash])
+		log 'fpv', :w_recv
+		time = Time.now.to_f
+ 		message = nil
+		loop do
+# 			$stderr.puts "trying to get #{label.inspect} from #{options[:fp]}" 
+			message = t_recv(label, options)
+			break if message
+			raise RecvTimeout.new("breaking w_recv on timeout") if options[:timeout] and (Time.now.to_f > time + options[:timeout])
+			sleep (0.001 or options[:refresh_time])
+		end
+# 		$stderr.puts "got message #{message}"
+		return message
+	end
+# 	alias :w_recv :w_recv
+
+	# Immediate Receive
+	#
+	# Receive a message with the given <i>label</i>. Returns a PPipe::Message immediately. The message has an internal thread which keeps checking if the message has arrived. 
+	#
+	# You can find out if the message has arrived by calling Message#arrived?. You can wait for the message to arrive by calling Message#join. You can stop the message checking by calling Message#kill.
+	#
+	# NB You cannot fork (in this process) until the message has arrived (or been killed) - otherwise two processes will be checking for the same message. 
+	#
+	# See t_recv for possible options.
+	
+	def i_recv(label, options={})
+		th = Thread.ppipe_new do
+			thread = Thread.current
+			thread[:ppipe_message] = true
+			thread[:label] = label
+			thread[:message]= w_recv(label, options)
+		end
+		return Message.with_listening_thread(th)
+	end
+
+	# Send something to the $stdin of the child process with pipe number pipe_no (if redirect is on). If pipe_no = nil call Kernel.puts. Can be called by any other process.
+	
+	def puts(pipe_no, *args)
+		raise PPipeFatal.new("calling this doesn't make any sense unless redirect is on") unless @redirect
+		return Kernel.puts(*args) unless pipe_no
+		@pipes[pipe_no].puts(*args)
+	end
+	
+	# Read all output from pipe. Return nil if there is no output. Never, ever blocks. (This calls a special function read_pipe which PPipe#Methods use to read pipes.) 
+	#
+	# If no argument is given:
+	# * if it is a child process or root process, read everything that has been put into its pipe.
+	# * if it is the root process, in addition, reads everything that child pipes have written to their standard out (if redirect is on)
+
+
+	def read_all(pipe=@user_end)
+		check_messages
+		return read_pipe(pipe)
+	end
+	
+	# Gets next line written to this process. 
+	# * if it is a child process or root process, read the next line that has been put into its pipe.
+	# * if it is the root process, may read the next line that child pipes have written to their standard out (if redirect is on)
+
+	
+	def gets(sep = $/)
+		check_messages
+		until ans = get_line(@user_end, $/)
+			check_messages
+			sleep 0.001
+		end
+		return ans
+	end
+	
+	# If redirect is on, the $stdout of all other processes is connected to the root process. Any output from these processes ends up in a pipe called @user_end. So if this is the root ppipe then this method provides access to that output. This method also causes PPipe to process input, flushing any input that is not a PPipe message into @user_end. 
+	#
+	# Notes:
+	# * Only the root ppipe can call this function.
+	# * This function will raise an error if redirect == false
+	# * The pipe @user_end contains output from every other process, in no order
+	# 
+	# If the PPipe has not yet processed the output from the child pipe, it will be stored internally in PPipe, and not in @user_end. Therefore a call such as 
+	#
+	#	ppipe.user_end.gets
+	#
+	# may block forever.
+	#
+	# It is recommended that instead something is written like:
+	# 	
+	#	while input = ppipe.read_all(ppipe.user_end) # read_all never blocks
+	#		#... process input
+	#	end
+	#
+	def user_end
+		raise PPipeFatal.new("redirect is off - calling user_end makes no sense") unless @redirect
+		raise PPipeFatal.new("Only the root pipe can call user_end") unless @is_root
+		check_messages
+		@user_end
+	end
+
+	# Return a hash of {pipe_number => pid} - allows you to know the pid that each pipe number corresponds to.
+	
+
+	def pids
+		return @pids.dup
+	end
+
+	# Wait for all other processes to either finish or call ppipe.die - see wait
+	#
+	# NB If more than one process calls waitall, both will wait for each other and hang forever!
+	
+	def waitall #(wait_remote_child=false, *args)
+		log 'fpv', 'waitall'
+		raise DeadParallelPipe unless @alive
+# 		raise PPipeFatal.new("Only the root process (ppipe.is_root == true) can call waitall if there is no controller") unless @controller or @is_root
+# 		stop_controller if @controller
+		loop do
+			@pids.keys.each do |pipe_no|
+				log 'v5', 'waiting for pipe_no', pipe_no
+				must_wait = !(pipe_no == @mpn or (@controller and pipe_no == @controller))
+				wait(pipe_no) if must_wait
+# 				must_wait
+# 				arr.push status if status 
+			end
+			log 'iv8', '@pids = ', @pids
+			check_messages
+			break unless @pids.keys.find{|pipe_no| !(pipe_no == @mpn) and (!@controller or !(pipe_no == @controller))}
+		end
+	end
+	
+	# Wait for another process (whose pipe number is pipe_no) to either call Methods#die or to exit (whichever is sooner). 
+	#
+	# If the process did not call die before it finished, then it sees if the process is dead by checking if its pipe is broken. However this may not work on all operating systems (so it's much better to make every process call die before it exits).
+
+	def wait(pipe_no) #, wait_remote_child=false, *args)
+		raise DeadParallelPipe unless @alive
+		raise ControllerError.new("Attempted to wait for the controller (would never return). Use stop_controller if you want the controller to finish") if @controller and pipe_no == @controller
+		raise SelfReference.new("Attempted to wait for self") if pipe_no == @mpn
+		check_messages
+		return if @finished_pipes[pipe_no]
+		unless @pipes[pipe_no]
+# 			@finished_pipes.push[pipe_no]
+# 			@pids.delete(pipe_no)
+			i_send(:pipe_finished, pipe_no, {evaluate: true, tc: true})
+			return
+		end
+		begin
+			loop do
+				check_messages
+				return  if @finished_pipes[pipe_no]   
+				sleep 0.4
+				@pipes[pipe_no].puts
+			end
+		rescue Errno::EPIPE
+			# If the pipe is broken we deduce that the corresponding process has exited or called die
+			i_send(:pipe_finished, pipe_no, evaluate: true, tc: true)
+# 			@finished_pipes.push[pipe_no]
+			return
+		end
+	end
+
+	def pipe_finished(pipe_no)
+		return if @finished_pipes[pipe_no]
+		begin
+			case @pipes[pipe_no]
+			when Array
+				@pipes[pipe_no][0].close
+				@pipes[pipe_no][1].close
+			when IO
+				@pipes[pipe_no].close
+			else
+			end
+		rescue
+		end
+		@pids.delete(pipe_no)
+		@pipes[pipe_no] = nil
+		@finished_pipes[pipe_no] = true
+	end
+	private :pipe_finished
+	
+	# Close all pipes and terminate all communication with every other process. Send a message to every other process letting them know this process has terminated communication. 
+	#
+	# It's good practice to call this in every process before the process exits.
+	#
+	# NB If you pass a block to Methods#fork, it will call die automatically when the block is finished, so die only needs to be called if the process exits midway through the block (consider using Methods#exit instead of Kernel.exit in this case)
+	
+	def die
+		raise DeadParallelPipe unless @alive
+		i_send(:pipe_finished, @mpn, {evaluate: true, tc: true})
+		@alive = false
+		@pipes.each do |pipe|
+			next unless pipe
+			begin
+# 				$stderr.puts 'closing',  i
+				if pipe.class == IO
+					pipe.close
+				else
+					pipe[0].close; pipe[1].close
+				end
+			rescue IOError, NoMethodError
+				next		
+
+			end
+		end
+		@pipes = nil
+		@mutexes = nil
+		@pid=nil
+	end
+	
+	# Calls Methods#die (if the ppipe is still alive) then calls Kernel.exit
+	
+	def exit
+		die if @alive
+		Kernel.exit
+	end
+
+	# Calls Methods#waitall, stops the controller if there is a controller and then calls Methods#die
+	
+	def finish
+		waitall
+		stop_controller if @controller
+		die
+# 		return statuses
+	end
+
+
+	
+	# Suddenly and violently terminate every process except the current one. Messy and unpredictable. An emergency measure only.
+	#
+	# Doesn't kill the controller if kill_controller is set to false.
+	
+	def kill_all(kill_controller=@controller) #(force=false)
+#  		stop_controller if @controller and not force
+		raise NoController.new("Tried to kill controller but no controller") if kill_controller and not @controller
+		@pids.each do |pipe_no, pid|
+			next if @controller and pipe_no == @controller
+			begin
+				kill_pipe(pipe_no) unless pid == Process.pid
+			rescue DeadPipe
+				next
+			end
+		end
+		Process.kill('TERM', @pids[@controller]) if kill_controller
+# 		die
+	end
+
+	# Suddenly terminate the process corresponding to pipe_no.
+
+	def kill_pipe(pipe_no, signal='TERM')
+		raise ControllerError.new("Can't kill controller: use stop_controller instead") if @controller and pipe_no == @controller
+ 		log '', 'killing pipe: ', pipe_no
+		begin
+			@pipes[pipe_no].puts
+		rescue PPipe::DeadPipe
+			raise DeadPipe.new("This pipe (#{pipe_no}) is already dead")
+		end
+		begin 
+			Process.kill(signal, @pids[pipe_no])
+		rescue Errno::ESRCH
+			raise DeadPipe.new("The process corresponding to this pipe (#{pipe_no}) is already dead")
+		end
+		pipe = @pipes[pipe_no] 
+		begin
+# 				$stderr.puts 'closing',  i
+			if pipe.class == IO
+				pipe.close
+			else
+				pipe[0].close; pipe[1].close
+			end
+		rescue IOError, NoMethodError
+		end
+		@pipes[pipe_no] = nil
+		@pids.delete(pipe_no)
+	end
+
+	end #module Methods
+
+	
+	#
+	# Quick Links: PPipe, parallelpipes.rb, PPipe::Methods, PPipe::Controller, PPipe::Message
+	#
+	#
+	# The primary purpose of this module is to provide the methods for the class PPipe.
+	# Therefore all the method documentation specifies having a PPipe as the receiver. However, it is perfectly possible to use this module as a module in its own right; see the section Modules in parallelpipes.rb
+	#
+	# For a general introduction to using the controller, see parallelpipes.rb
+	
+	
+	module Controller
+	
+	include Methods
+
+	# the pipe number of the controller (nil if there is no controller)
+	attr_reader :controller
+	
+	# Start a controller process. Raises an error if there already is one. controller_refresh is the delay between the controller dealing with requests. A shorter refresh time means the controller runs faster, but consumes more CPU (typically a controller consumes about 1-6% of CPU). 
+	
+	def start_controller(controller_refresh=0.001)
+		raise DeadParallelPipe unless @alive
+		raise ControllerError.new("This parallel pipe already has a controller") if @controller
+		parent = [mpn, tid]
+		@controller = fork do
+			log 'v4', 'Started Controller...'
+			@controller_refresh = controller_refresh
+			@messages[tid] ||= {}
+			@messages[tid][CON] = {}
+			@controller_status = {}
+			@resource_status = {}
+			@resources = {}
+			@resource_file_names = {}
+# 			@resource_accessed = {}
+			log 'v5', 'commencing controller...'
+			i_send(:controller_started, true, tp: parent[0], tt: parent[1])
+			run_controller
+			log 'v5', 'controller exiting...'
+		end
+		w_recv(:controller_started, fp: @controller)
+# 		broadcast(:set_controller, @controller, {evaluate: true})
+	end
+	
+	# Stop the controller. The controller sends out an exit warning to all processes. No new lock, synchronize, get_shared_resource or shared_resource resource commands can be issued once that warning has been received. However, the controller will not exit until all existing locks on mutexes have been unlocked and all shared_resources have been returned.
+	
+	def stop_controller
+		raise NoController unless @controller
+		raise DeadParallelPipe unless @alive
+		controller = @controller
+		w_send(:exit, true, tp: @controller)
+		w_recv(:exited, fp: controller)
+		Process.wait(@pids[controller])
+		@pids.delete(controller)
+# 		$stderr.puts '@controller is', @controller.inspect
+		@controller = nil
+	end
+	
+	# Change the controller refresh time. controller_refresh is the delay between the controller dealing with requests. A shorter refresh time means the controller runs faster, but consumes more CPU (typically a controller consumes about 1-6% of CPU). Default is 0.001. There is no point having it smaller than 0.0001 - there is no improvement in performance.
+	#
+	# Benchmarks <i>(2GHz AMD 64 (32bit OS))</i>
+	#
+	# Time taken to lock and unlock a mutex twice 
+	#
+	# controller_refresh : time taken
+	#
+	# * 0.1: 0.313996553421021               
+	# * 0.01: 0.132316589355469              
+	# * 0.001: 0.0158429145812988            
+	# * 0.0001: 0.00638794898986816          
+	# * 1.0e-05: 0.0312449932098389
+	# 
+	# Footnote: 
+	#
+	# Consuming 1-6% of CPU seems like a lot. However, PPipe is aiming to bring the multi-core,  multi-process world to Ruby. Most new computers have at least two CPU cores nowadays, many have more and the number will rise in the future. 1-6% of 1 processor is not much when the computer has 4, 8 or 16 processors.
+	#
+	# Having said which, if someone finds a better way of doing what the controller does, please share it!
+	#
+	# And finally, if this overhead is unacceptable, PPipe run without a Controller (see Methods#set_up_pipes) is still a powerful parallelization tool.
+	
+	def controller_refresh=(value)
+		raise NoController unless @controller
+		raise DeadParallelPipe unless @alive
+		i_send(:set_controller_refresh, value, tp: @controller, evaluate: true)
+	end
+
+	def set_controller_refresh(value)
+		@controller_refresh = value
+	end
+	private :set_controller_refresh
+
+	def set_controller(value)
+		@controller = (value == :off ? nil : value)
+	end
+	private :set_controller
+
+	CON = :controller_switch  #_GHAkxsadf0a0s98
+
+	# Lock a mutex named mutex_name. If the mutex did not exist before, create it. No other process or thread can lock this mutex until it has been unlocked. 
+	#
+	# mutex_name must be a symbol or an integer.
+	#
+	# Note, every different mutex_name corresponds to a different mutex. Thus, it is easy to create vast numbers of mutexes. However, there is a memory and processor overhead associated with each mutex. Although this is small, creating very large numbers of mutexes is not a good idea.
+	#
+	# Mutexes cannot be destroyed.
+	
+	def lock(mutex_name)
+		ArgumentError.check([:mutex_name, mutex_name, [Symbol, Integer, Fixnum]])
+		log 'fpv', :lock
+# 		$stderr.puts "#@mpn thinks controller is #@controller"
+		@thread_mutexes[mutex_name] ||= Mutex.new
+		@thread_mutexes[mutex_name].lock
+		check_messages
+		raise NoController unless @controller
+		raise DeadParallelPipe unless @alive
+# 		check_for_exit_signal
+		@old_controllers ||= {}
+		@old_controllers[mutex_name] = @controller
+		i_send(CON,  [mutex_name, :lock], tp: @controller)
+		w_recv(mutex_name, fp: @controller)
+		log 'fpvc', :lock
+	end
+
+	# Unlock a mutex. See Controller#lock
+	#
+	# If the process and thread calling unlock did not previously lock the mutex, this call will hang forever.
+	
+	def unlock(mutex_name)
+		ArgumentError.check([:mutex_name, mutex_name, [Symbol, Integer, Fixnum]])
+		log 'fpv', :unlock
+# 		check_messages
+		raise NoController.new("Controller dead, or a lock call has not been issued with the name #{mutex_name} from this process") unless @old_controllers[mutex_name]
+		raise DeadParallelPipe unless @alive
+		i_send(CON,  [mutex_name, :unlock], tp: @old_controllers[mutex_name])
+		w_recv(mutex_name, fp: @old_controllers[mutex_name])
+		@old_controllers.delete(mutex_name)
+		@thread_mutexes[mutex_name].unlock
+		log 'fpvc', :unlock
+	end
+	
+	# Lock the mutex, call the block and then unlock the mutex. See Controller#lock.
+	#
+	# 	ppipe.synchronize(:sentence){print 'a fragmented sen'; sleep rand; print "tence\n"}
+	#
+	# Is identical to:
+	#
+	#	ppipe.lock(:sentence)
+	#	print 'a fragmented sen'; sleep rand; print "tence\n"
+	#	ppipe.unlock(:sentence)
+
+	def synchronize(mutex_name, &block)
+		ArgumentError.check([:mutex_name, mutex_name, [Symbol, Integer, Fixnum]])
+		log 'fpv', :synchronize
+		raise DeadParallelPipe unless @alive
+		lock(mutex_name)
+		yield
+		unlock(mutex_name)
+		log 'fpvc', :synchronize
+	end
+	
+	# Is the mutex  called <i>mutex_name</i> locked? Returns [pipe_no, thread_id] of the locking thread and process if locked, nil if it is not locked.
+	
+	def mutex_locked?(mutex_name)
+		ArgumentError.check([:mutex_name, mutex_name, [Symbol, Integer, Fixnum]])
+		log 'fpv', :locked?
+		check_messages
+		raise NoController unless @controller
+		raise DeadParallelPipe unless @alive
+		i_send(CON,  [mutex_name, :mutex_locked?], tp: @controller)
+		ans = w_recv(mutex_name, fp: @controller)[0]
+		log 'fpvc', :mutex_locked?
+		return ans
+	end
+
+	# Get a shared resource from the controller. No other process or thread can access the resource until this process has returned it.
+	#
+	# resource_name must be a Symbol or Integer
+	#
+	# A shared resource can be any object where 
+	#
+	#	eval(object.inspect) == object
+	#
+	# If the resource has not been accessed before it is initialized to nil.
+	#
+	#	ppipe = PPipe.new(5, true)
+	#	savings = ppipe.get_shared_resource(:savings)
+	#
+	# 
+
+	def get_shared_resource(resource_name)
+		ArgumentError.check([:resource_name, resource_name, [Symbol, Integer, Fixnum]])
+
+		log 'fpv', :get_shared_resource
+		@shared_resource_mutexes[resource_name] ||= Mutex.new
+		@shared_resource_mutexes[resource_name].lock
+		check_messages
+		raise NoController unless @controller
+		raise DeadParallelPipe unless @alive
+		@old_resource_controllers ||= {}
+		@old_resource_controllers[resource_name] = @controller
+
+# 		check_for_exit_signal
+		i_send(CON,  [resource_name, :fetch], tp: @controller)
+# 		$stderr.puts 'request sent'
+		ans = w_recv(resource_name, fp: @controller)
+# 		$stderr.puts 'got answer'
+		log 'fpvc', :get_shared_resource
+		return ans[0]
+	end
+
+	# Return a shared resource.
+	#	
+	# If the process and thread calling return_shared_resource did not previously call get_shared_resource, this call will hang forever.
+	#
+	#	savings += 20.03
+	#	ppipe.return_shared_resource(:savings, savings)
+	
+	def return_shared_resource(resource_name, resource)
+		ArgumentError.check([:resource_name, resource_name, [Symbol, Integer, Fixnum]])
+		log 'fpv', :return_shared_resource
+
+# 		check_messages
+		raise NoController unless @old_resource_controllers[resource_name]
+		raise DeadParallelPipe unless @alive
+# 		check_for_exit_signal
+		i_send(CON,  [resource_name, resource], tp: @old_resource_controllers[resource_name])
+		w_recv(resource_name, fp: @old_resource_controllers[resource_name])
+		@old_resource_controllers.delete(resource_name)
+		@shared_resource_mutexes[resource_name].unlock
+		log 'fpvc', :return_shared_resource
+	end
+
+	# Fetch a shared resource, edit it and then return it. The resource is passed as the parameter to the block.
+	#
+	# 	ppipe.shared_resource(:savings) do |savings|
+	#		savings += 102.96
+	#		# ... some other calculations
+	#		savings
+	#	end
+	#
+	# NB The shared resource to be returned <b> must be the last line</b> of the block
+	
+	def shared_resource(resource_name, &block)
+		ArgumentError.check([:resource_name, resource_name, [Symbol, Integer, Fixnum]])
+		log 'fpv', :shared_resource
+		resource = get_shared_resource(resource_name)
+		resource = yield(resource)
+		return_shared_resource(resource_name, resource)
+		log 'fpvc', :shared_resource
+	end
+
+	# Is the shared resource  called <i>resource_name</i> locked? Returns [pipe_no, thread_id] of the locking thread and process if locked, nil if it is not locked.
+	
+	def resource_locked?(resource_name)
+		ArgumentError.check([:resource_name, resource_name, [Symbol, Integer, Fixnum]])
+		log 'fpv', :locked?
+		check_messages
+		raise NoController unless @controller
+		raise DeadParallelPipe unless @alive
+		i_send(CON,  [resource_name, :resource_locked?], tp: @controller)
+		ans = w_recv(resource_name, fp: @controller)[0]
+		log 'fpvc', :resource_locked?
+		return ans
+	end
+
+	
+	# Maintain the shared resource automatically in the file <i>file_name</i>. 
+	#
+	# If the file <i>file_name</i> does not exist, it will be created the first time the shared resource is accessed, and it will be updated at every subsequent access. If the file <i>file_name</i> exists (e.g. from a previous run of the program), it will be reloaded. Thus, the shared resource becomes a persistant object: it is remembered from one execution to the next.
+	#
+	# auto_load_save must be called before any access to the shared resource.
+	#
+	#	ppipe.auto_load_save(:savings, 'my_savings_file.txt')
+# 	
+	def auto_load_save(resource_name, file_name)
+		ArgumentError.check([:resource_name, resource_name, [Symbol, Integer, Fixnum]])
+		log 'fpv', :auto_load_save
+		raise NoController unless @controller
+		raise DeadParallelPipe unless @alive
+		i_send(:auto_load_save, [resource_name, file_name], tp: @controller)
+		reply = w_recv(:auto_load_save_ + resource_name, fp: @controller)
+		raise ControllerError.new("if auto_load_save is called it must be before any access to a shared resource (#{resource_name})") if reply == :already_accessed
+		raise ControllerError.new("another thread or process has already called auto_load_save for #{resource_name}") if reply == :already_opened
+		log 'fpvc', :auto_load_save
+	end
+
+	# If the controller will not be need for a while, put it to sleep for <i>sleep_time</i> seconds. If <i>wait_for_waking</i> is false, wake up automatically. If it is a number, check for a wake up call every <i>wait_for_waiting</i> seconds.
+	#
+	# Experimental.
+	
+	def put_controller_to_sleep(sleep_time, wait_for_waking)
+		raise NoController unless @controller
+		raise DeadParallelPipe unless @alive
+		w_send(:sleep, [sleep_time, wait_for_waking], tp: @controller)
+	end
+
+	# Wake up the controller
+	#
+	# Experimental
+	
+	def wake_controller
+		raise NoController unless @controller
+		raise DeadParallelPipe unless @alive
+		w_send(:wake, true, tp: @controller)
+	end
+
+	# Returns true if the controller is awake, false if it is asleep. Currently hangs if the controller has not been told to sleep.
+	#
+	# Experimental
+	
+	def controller_woken?(wait_till_woken=false)
+		#blocks unless controller has been put to sleep. Returns true immediately if controller is asleep. Returns false immediately if controller has been put to sleep and woken
+		raise NoController unless @controller
+		raise DeadParallelPipe unless @alive
+		check_messages
+		while @messages[tid][:controller_sleep_switch][@controller].values[0].size > 2
+			2.times{@messages[tid][:controller_sleep_switch][@controller].values[0].shift}
+		end
+		unless @controller_asleep
+			w_recv(:controller_sleep_switch, fp: @controller)
+			@controller_asleep = true
+		else
+			if wait_till_woken
+				@controller_asleep = w_recv(:controller_sleep_switch, fp: @controller)
+			else
+				@controller_asleep = !t_recv(:controller_sleep_switch, fp: @controller)
+			end
+		end
+	end
+
+	# Is there a controller? 
+	
+	def controller_alive?
+		check_messages
+		return @controller ? true : false
+	end
+
+	def run_controller
+		log 'fpv', 'run_controller'
+		exit_caller = false; sent_exit = false
+		loop do
+			log 'v9', 'controller up and running'
+
+			reply = t_recv(:sleep)
+			if reply
+				i_send(:controller_sleep_switch, true)
+				initial_sleep_time = reply[0]
+# 				$stderr.puts :initial_sleep_time, initial_sleep_time
+				sleep initial_sleep_time
+				if reply[1]
+					loop do
+						break if t_recv(:wake)
+						sleep reply[1]
+					end
+				end
+				i_send(:controller_sleep_switch, true)
+			end
+ 			reply = t_recv(:exit)
+			exit_caller = reply.fp if reply
+			if exit_caller 
+				if sent_exit and (@controller_status.values + @resource_status.values).inject(true){|bool, value| bool and !value} #ie no resources are currently locked	
+					w_send(:exited, true, tp: exit_caller)
+					Kernel.exit
+				elsif not sent_exit
+					i_send(:set_controller, :off, evaluate: true); sleep 0.01
+					sent_exit = true 
+				elsif sent_exit
+					log 'v9', (@controller_status.values + @resource_status.values).inspect
+				end
+			end
+ 			check_messages
+			@messages[tid][:auto_load_save] ||= {}
+			@messages[tid][:auto_load_save].each do |pipe_no, thread_list|
+				thread_list.each do |thread_no, requests|
+					requests.each do |message|
+						options = message.options
+						name, file_name = message.contents
+						if @resource_file_names[name]
+							i_send(:auto_load_save_ + name, :already_opened, tp: pipe_no, tt: thread_no)
+						elsif @resources.keys.include? name
+							i_send(:auto_load_save_ + name, :already_accessed, tp: pipe_no, tt: thread_no)
+						else
+							@resource_file_names[name] = file_name
+							@resources[name] = eval(File.read(file_name)) if FileTest.exist?(file_name)
+							i_send(:auto_load_save_ + name, :loaded, {tp: pipe_no, tt: thread_no}) #warning - this will cause the same problems as i_send later in controller - fix!
+						end
+					end
+				end
+			end
+			@messages[tid][:auto_load_save] = {}
+			@messages[tid][CON].each do |pipe_no, thread_list|
+				thread_list.each do |thread_no, requests|
+					@messages[tid][CON][pipe_no][thread_no] = []
+# 					ungranted_requests = []
+					requests.each do |message|
+						options = message.options
+						name, request = message.contents
+						request_granted = false
+# 																					@rescued_messages ||=[]
+# 						log 'pv3', "considering #{name}, #{request} from #{pipe_no}, #{thread_no}" if @rescued_messages.include? message
+						log 'pv9', "considering #{name}, #{request} from #{pipe_no}, #{thread_no}" 
+	# 					@controller_status[name] = :unlocked unless @controller_status[name]
+						case request
+						when :lock
+							unless @controller_status[name]
+	# 							$stderr.puts "locking #{name} from #{pipe_no}"
+								@controller_status[name] = [pipe_no, thread_no]
+								request_granted = true
+							end
+						when :unlock
+							if @controller_status[name] == [pipe_no, thread_no] or (@controller_status[name] and @weak_synchonization)
+								@controller_status[name] = nil
+								request_granted = true
+							end
+						when :mutex_locked?
+							request_granted = [@controller_status[name]]
+						when :fetch
+							unless @resource_status[name]
+	# 		$stderr.puts "#@mpn thinks controller is #@controller"
+
+	# 							$stderr.puts "considering fetch: #{name}"
+								@resource_status[name] = [pipe_no, thread_no]
+								@resources[name] ||= nil
+								request_granted = [(@resources[name])]
+	# 							$stderr.puts request_granted.inspect
+							end
+						when :resource_locked?
+							request_granted = [@resource_status[name]]
+						else #a shared resource is being returned
+							if @resource_status[name] == [pipe_no, thread_no] or (@resource_status[name] and @weak_synchonization)
+								@resource_status[name] = nil
+								@resources[name] = request
+								File.open(@resource_file_names[name], 'w'){|f| f.puts @resources[name].inspect} if @resource_file_names[name]
+								request_granted = true
+							end
+	# 					else						
+	# 						raise PPipeFatal.new("Bad request to controller: #{request.inspect}")
+						end
+						if request_granted
+	# 						$stderr.puts 'granted to', pipe_no, request_granted
+# 							loop do
+# 								begin
+									i_send(name, request_granted, tp: pipe_no, tt: thread_no)
+# 									break
+# 								rescue UnassignedPipe #the request has come from a new pipe before the controller received the news about the new pipe's existence (the message :increase_pipe_counter)
+	# 								@messages[tid][CON][pipe_no][thread_no].push message								
+# 									check_messages
+# 									log 'v3', "rescued unassigned pipe...", "@messages is now... " + @messages.inspect 
+	# 								@rescued_messages.push message
+	# 								ungranted_requests.push message
+	
+# 								end
+# 							end
+	# 						w_send(0, :random, true)
+	# 						$stderr.puts 'reply sent'
+						else
+							@messages[tid][CON][pipe_no][thread_no].push message
+# 							ungranted_requests.push message
+						end
+					end
+# 					@messages[tid][CON][pipe_no][thread_no] = ungranted_requests
+				end
+			end
+			sleep @controller_refresh
+		end
+	end
+	private :run_controller
+
+	end #module Controller
+
+	
+	
+	
+	
+# 
+	include Log
+	include Reader
+	include Methods
+	include Controller
+	include MethodMissing
+
+end
+
+
+
+
+