dramatis 0.0.1 → 0.1.1

data/History.txt

@@ -1,3 +1,7 @@
+== 0.1.1 2008-06-06
+
+* Patched alpha, sync'd up with python. No material changes to Ruby.
+
 == 0.0.1 2008-06-05
 
 * first packaged alpha

data/Manifest.txt

@@ -32,7 +32,7 @@ examples/im/single/fox.rb
 examples/im/single/wxchat.rb
 examples/pingpong/actor.rb
 examples/pingpong/actor_rec.rb
-examples/pingpong/pingpong.txt
+examples/pingpong/ruby.txt
 examples/pingpong/scala.rb
 examples/pingpong/serial.rb
 examples/pretty.txt
@@ -76,7 +76,6 @@ lib/dramatis/runtime/timer.rb
 lib/dramatis/shoes.rb
 lib/dramatis/shoes/runtime.rb
 lib/dramatis/version.rb
-log/debug.log
 script/destroy
 script/generate
 script/txt2html

data/README.txt

@@ -10,7 +10,7 @@ An actor library for dynamic languages like Ruby and Python.
 
 dramatis provides a library for writing concurrent programs using the actor programming model.
 
-This is an early version, the first release with packaging (a gem for ruby, setuptools for python).
+This is an early version, the first release with packaging (a gem for ruby, distutils for python).
 
 It's available on github to download and does come with documentation, a tutorial, and several examples, all of which (mostly) work, so it's stable enough to being to play with.
 

data/examples/pingpong/{pingpong.txt → ruby.txt}

@@ -1,4 +1,4 @@
-h1. PingPong tutorial
+h1. PingPong tutorial (Ruby version)
 
 h2. PingPong
 
@@ -148,7 +148,7 @@ dramatis has other continuation types, as will be shown below. dramatis continua
 
 h2. Concurrent PingPong
 
-So, with some background on actors, let return to our example. When we mixed in @Dramatis::Actor@, what changed in our program? First, lets look at the line that created our actors:
+So, with some background on actors, let return to our example. When we mixed in @Dramatis::Actor@, what changed in our program? First, lets look at the lines that created our actors:
 <pre><code class="ruby">
 ping = PingPong.new "ping"
 pong = PingPong.new "pong"
@@ -169,7 +169,7 @@ h2. _pass by value_
 
 Another actor issue comes in to play at this step. Actor systems are generally _pass by value_. That is, they send object values or copies, rather than references to objects. Nothing is shared between the caller and the callee. In pure actor systems, there are only values (which include actor names) and actors so nothing except actor state is mutable and actors are internally serial. 
 
-In this sense, dramatis is not a pure actor system. Since it's only a library on top of a non-actor language and virtual machine, this is pretty much guaranteed: to make a pure actor system would generally require changing either one or both. In addition to immutable values like numbers, dramatis programs have all the multiple objects found in non-concurrent program. dramatis provides mechanisms for for managing concurrency but cannot guarantee that shared objects will not have concurrent conflicts if they are used.
+In this sense, dramatis is not a pure actor system. Since it's only a library on top of a non-actor language and virtual machine, this is pretty much guaranteed: to make a pure actor system would generally require changing either one or both. In addition to immutable values like numbers, dramatis programs have all the mutable objects found in non-concurrent program. dramatis provides mechanisms for for managing concurrency but cannot guarantee that shared objects will not have concurrent conflicts if they are used.
 
 At this time, dramatis does not specify whether  actor method call arguments will be copied or not. Thus some care is required when considering objects passed to actor methods.
 
@@ -215,8 +215,7 @@ What we need is a way to call a method but not wait around for the results (if y
 
 In dramatis, we make this non-waiting call by writing
 <pre><code class="ruby">
-class PingPong
-  release( partner ).pingpong count-1, self
+release( partner ).pingpong count-1, self
 </code></pre>
 @release@ (or @Dramatis.release@ if you haven't used @include Dramatis@) takes an actor name and returns a new name. This new name acts slightly differently than the original name. It _releases_, if you will, the task created by the call. That is, it doesn't ask the task to return value and the method call returns immediately. Another way of looking at is that rather than providing the current continuation, it provides a nil continuation.
 

data/lib/dramatis/actor/interface.rb

@@ -72,6 +72,9 @@ class Dramatis::Actor::Interface
     @actor.gate.always( ( [ :object ] + Array( args ) ), value )
   end
 
+  # call-seq:
+  # enable_call_threading -> nil
+  #
   # Enables call threading for actor method calls made by this
   # actor. When call threading is enabled, method gating is modified
   # such that recursive and co-recursive calls are allowed. Normally
@@ -82,14 +85,21 @@ class Dramatis::Actor::Interface
 
   def enable_call_threading
     @actor.enable_call_threading
+    nil
   end
 
+  # call-seq:
+  #  name -> actor_name_of_actor
+  #
   # Returns the actor name for the object.
 
   def name
     @actor.name
   end
 
+  # call-seq:
+  #  yield -> nil
+  #
   # Yields the actor to allow other tasks to be executed.
   # Currently, messages are handled FIFO so the yield will
   # return when all the messages received up to the point of the
@@ -99,6 +109,7 @@ class Dramatis::Actor::Interface
   def yield
     @actor.actor_send [ :yield ], :continuation => :rpc,
                                   :nonblocking => true
+    nil
   end
 
   def timeout value, *args #:nodoc: not ready

data/lib/dramatis/actor/name/interface.rb

@@ -2,8 +2,8 @@ module Dramatis; end
 module Dramatis::Actor; end
 class Dramatis::Actor::Name; end
 
-# An Dramatis::Actor::Name::Interface object provides the ability to
-# modify the semantics of actor name and preform other actor-level operations on an
+# A Dramatis::Actor::Name::Interface object provides the ability to
+# modify the semantics of actor name and perform other actor-level operations on an
 # actor. It is typically created via Dramatis.interface.
 
 class Dramatis::Actor::Name::Interface
@@ -55,7 +55,6 @@ class Dramatis::Actor::Name::Interface
     @name
   end
 
-  
   # call-seq:
   #   future -> a_name
   # 
@@ -72,6 +71,9 @@ class Dramatis::Actor::Name::Interface
     @name
   end
 
+  # call-seq:
+  #   bind( behavior ) -> actor_name
+  # 
   # Binds the actor identified by this name to supplied behavior,
   # which should be a native ruby object.  Can only be called on
   # unbound actors, typically created with Dramatis::Actor.new().  The

data/lib/dramatis/deadlock.rb

@@ -3,121 +3,9 @@ module Dramatis; end
 class Dramatis::Error < StandardError; end
 
 # Exception raised when the runtime determines that deadlock has
-# occurred: that is, there are no executing actors and that while
+# occurred: that is, there are no executing actors and while
 # there are one or more tasks queued for one or more actors, all are
-# gated off. Note that case where there are no tasks at all signals
+# gated off. Note that case where there are no tasks at all indicates
 # normal termination.
-#
-# Inherits most methods from Exception.
-#
-# Dramatis::Deadlock (and eventually all Dramatis::Error subclasses)
-# modify the backtrace generated by native language exceptions in
-# order to put them in a more useful context:
-# 1. They chain exceptions across threads using continuation information
-# 1. They remove dramatis runtime internal information
-# See raw_backtrace.
 
 class Dramatis::Deadlock < Dramatis::Error; end
-
-class Dramatis::Deadlock_ < Dramatis::Error
-
-  # call-seq:
-  # raw_backtrace -> array of strings
-  #
-  # raw_backtrace returns the unfiltered but still chained backtrace
-  # information. It is the concatenation of the backtrace from each
-  # actor call site as an exception propagates back the continuation
-  # chain.
-  def raw_backtrace
-    @raw_backtrace
-  end
-
-  def initialize string = nil, opts = {} #:nodoc:
-    super string
-    @next = opts[:next]
-    @raw_backtrace = []
-  end
-
-  # how things stand:
-  # r18 and r19 call set_backtrace at the raise
-  # jr never calls it; instead the base class synthesizes it
-  # at the first backtrace call
-  # as far as frames go, it seems lke jr elides sends sometimes
-
-  def set_backtrace *args #:nodoc:
-    # p "sbt!"
-    # pp args[0]
-    array = @raw_backtrace = args[0]
-    if @next
-      @raw_backtrace = @next.raw_backtrace + @raw_backtrace
-      array = @next.backtrace + array
-    end
-
-    # pp "raw", @raw_backtrace
-
-    # remove the scheduler
-
-    filtered = []
-    array.each do |v|
-      file, line, func = v.split ':'
-      file =~ %r{/lib/dramatis/} or ( filtered <<  v and next )
-      func =~ %r{\Wmaybe_deadlock\W} and next
-      file =~ %r{/runtime/scheduler} and func =~ %r{\Wrun\W} and break
-      filtered <<  v
-    end
-    
-    # remove queueing delivery
-
-    array = filtered
-    filtered = []
-    skipping = false
-    array.each do |v|
-
-      # p v
-
-      file, line, func = v.split ':'
-
-      if file !~ %r{/lib/dramatis/}
-        # p "not skipping x"
-        skipping = false
-        filtered <<  v
-        next
-      end
-
-      if !skipping and 
-         ( ( file =~ %r{/runtime/task} and func =~ %r{\Wqueued\W} ) or
-           ( file =~ %r{/runtime/actor} and func =~ %r{\Wsend\W} ) or # r18, r19
-           ( file =~ %r{/runtime/actor} and func =~ %r{\Wdeliver\W} )  ) # jr
-        # p "skipping"
-        skipping = true
-        next
-      end
-
-      if file =~ %r{/dramatis/actor/name} and func =~ %r{\Wmethod_missing\W}
-        # p "not skipping"
-        skipping = false
-        next
-      end
-
-      skipping or filtered <<  v
-
-    end
-
-    # pp "filt", filtered
-    # pp args[0]
-    super filtered
-    # super args[0]
-  end
-
-  def backtrace #:nodoc:
-    if @raw_backtrace.empty?
-      bt = super
-      if bt
-        set_backtrace  bt
-      end
-    end
-    # p "d"
-    super
-  end
-
-end

data/lib/dramatis/error.rb

@@ -15,35 +15,26 @@ class Dramatis::Error::Bind < Dramatis::Error; end
 
 require 'dramatis/error/uncaught'
 
-class Dramatis::Error < StandardError
-
-  def self._traceback exception, _next = nil
-    tb = exception.instance_variable_get :@_dramatis_traceback
-    if !tb
-      tb = exception.instance_variable_set( :@_dramatis_traceback,
-                                            Traceback.new( _next ) )
-    end
-    tb
-  end
-
-end
-
-class Dramatis::Error::Traceback_
+class Dramatis::Error < StandardError; end
 
-  def initialize _next
-  end
-
-end
+# Dramatis modifies exceptions thrown within the context of an actor rpc call,
+# combinding the the backtraces generated by native language exceptions in
+# order to put them in a more useful context:
+# 1. Exceptions are chained across threads using continuation information
+# 1. Dramatis runtime internal call frames are removed
 
 class Exception
 
-  alias _dramatis_set_backtrace set_backtrace 
-  alias _dramatis_backtrace backtrace 
+  # :stopdoc:
+  alias _dramatis_backtrace backtrace
+  # :startdoc:
 
-  def set_backtrace arg
-    # p "set back #{self}"
-    _dramatis_set_backtrace arg
-  end
+  # call-seq:
+  # backtrace -> array of strings
+  #
+  # dramatis wraps and filters the native exception backtrace method in order to
+  # augment the backtrace to follow the backtrace through actor rpc calls.
+  #
 
   def backtrace
     # p "back #{self}"
@@ -54,7 +45,7 @@ class Exception
     end
   end
 
-  def _dramatis_reraise
+  def _dramatis_reraise  #:nodoc:
     # return
     # p "reraise"
     if @_dramatis_raw_backtrace
@@ -64,7 +55,7 @@ class Exception
     end
   end
 
-  def filter array
+  def filter array  #:nodoc:
 
     # pp "_", array
 

data/lib/dramatis/error/uncaught.rb

@@ -6,6 +6,9 @@ class Dramatis::Error < StandardError; end
 
 class Dramatis::Error::Uncaught < Dramatis::Error
 
+  # call-seq:
+  #   to_s -> string
+  # 
   # combines the name of all uncaught exceptions.
 
   def to_s

data/lib/dramatis/future/interface.rb

@@ -7,6 +7,9 @@ class Dramatis::Future; end
 
 class Dramatis::Future::Interface
 
+  # call-seq:
+  #   value -> object
+  # 
   # Returns the native value of the future. If the value of the future
   # is not yet available, the method blocks (with rpc gating
   # semantics) until it is.
@@ -14,7 +17,7 @@ class Dramatis::Future::Interface
   # In many cases, this method is not necessary since the
   # method_missing method on the future will catch most attempts to
   # accesses the value. This method may be necessary in corner cases,
-  # for example when usingconditionals, conversions, and
+  # for example when using conditionals, conversions, and
   # metaprogramming.
 
   def value
@@ -23,6 +26,9 @@ class Dramatis::Future::Interface
     end
   end
 
+  # call-seq:
+  #   ready? -> boolean
+  # 
   # Returns true if the future may be evaluated without
   # blocking. Returns false if the value is not yet available.
   #

data/lib/dramatis/runtime.rb

@@ -9,16 +9,22 @@ require 'thread'
 
 class Dramatis::Runtime
 
+  # call-seq:
+  # current -> current_runtime_object
+  #
   # Returns a reference to the current Dramatis::Runtime object.
 
   def self.current
     @@current ||= self.new
   end
 
+  # call-seq:
+  # reset -> nil
+  #
   # Resets the current runtime instance. Note that this method hard
-  # resets counters and ignore exceptions which is generally a bad
-  # idea. It is typical only used in unit test after methods to keep
-  # failing tests from cascading.
+  # resets counters and ignores exceptions which is generally a bad
+  # idea. It is typical only used in unit test and spec "after"
+  # methods to keep failing tests from cascading.
 
   def self.reset
     # this swallows exceptions: it's assumed to be used to clean up
@@ -32,10 +38,13 @@ class Dramatis::Runtime
     @@current = nil
   end
 
+  # call-seq:
+  # quiesce -> nil
+  #
   # Causes the runtime to suspend the current thread until there are
   # no more tasks that can be executed. If no tasks remain, returns
   # normally. If tasks remain but are gated off,
-  # Dramtis::Error::Deadlock is raised.
+  # Dramatis::Deadlock is raised.
   #
   # As a side effect, this method releases the current actor to
   # process messages but does not change the task gate.
@@ -62,7 +71,10 @@ class Dramatis::Runtime
     end
   end
 
-  # Returns the list of uncaught exceptions.
+  # call-seq:
+  # exceptions -> array_of_exceptions
+  #
+  # Returns the list of exceptions that were not caught by an actor.
 
   def exceptions 
     result = nil
@@ -72,9 +84,12 @@ class Dramatis::Runtime
     result
   end
 
-  # Clears the list of uncaught exceptions. Used in unit tests to
+  # call-seq:
+  # clear_exceptions -> nil
+  #
+  # Clears the list of uncaught exceptions. Used in unit tests and specs to
   # clear expected exceptions.  If exceptions are raised and not
-  # clear, they will be raised at the end of the program via a
+  # cleared, they will be raised at the end of the program via a
   # Dramatis::Error::Uncaught.
   
   def clear_exceptions
@@ -101,13 +116,19 @@ class Dramatis::Runtime
     end
   end
 
-  # Enables or disables printing warnings, e.g., when uncaugh
-  # exceptions are detected.
+  # call-seq:
+  # warnings = boolean -> boolean
+  #
+  # Enables or disables printing warnings, e.g., when uncaught
+  # exceptions are detected. Returns the value passed.
 
   def warnings= value
     @warnings = value
   end
 
+  # call-seq:
+  # warnings? -> boolean
+  #
   # Returns true if warnings are enabled.
 
   def warnings?

data/lib/dramatis/runtime/task.rb

@@ -58,7 +58,9 @@ class Dramatis::Runtime::Task #:nodoc: all
     when :none
       @continuation = Continuation::None.new name, @call_thread
     when :rpc
-      @continuation = Continuation::RPC.new name, @call_thread, options[:nonblocking]
+      @continuation = Continuation::RPC.new name,
+                                              @call_thread,
+                                              options[:nonblocking]
     when :future
       @continuation = Continuation::Future.new name, @call_thread
     when Proc

data/lib/dramatis/runtime/thread_pool.rb

@@ -69,7 +69,7 @@ class Dramatis::Runtime::ThreadPool #:nodoc: all
   
 end
 
-class Dramatis::Runtime::ThreadPool::PoolThread < Thread
+class Dramatis::Runtime::ThreadPool::PoolThread < Thread #:nodoc: all
 
   def initialize pool
     @pool = pool

data/lib/dramatis/version.rb

@@ -1,7 +1,7 @@
 module Dramatis
   module VERSION #:nodoc:
     MAJOR = 0
-    MINOR = 0
+    MINOR = 1
     TINY  = 1
     STRING = [MAJOR, MINOR, TINY].join('.')
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: dramatis
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
+  version: 0.1.1
 platform: ruby
 authors: 
 - Steven Parkes
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-06-05 00:00:00 -07:00
+date: 2008-06-06 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -26,7 +26,7 @@ extra_rdoc_files:
 - Manifest.txt
 - README.txt
 - examples/README.txt
-- examples/pingpong/pingpong.txt
+- examples/pingpong/ruby.txt
 - examples/pretty.txt
 - examples/telephone/3esl.txt
 files: 
@@ -64,7 +64,7 @@ files:
 - examples/im/single/wxchat.rb
 - examples/pingpong/actor.rb
 - examples/pingpong/actor_rec.rb
-- examples/pingpong/pingpong.txt
+- examples/pingpong/ruby.txt
 - examples/pingpong/scala.rb
 - examples/pingpong/serial.rb
 - examples/pretty.txt
@@ -108,7 +108,6 @@ files:
 - lib/dramatis/shoes.rb
 - lib/dramatis/shoes/runtime.rb
 - lib/dramatis/version.rb
-- log/debug.log
 - script/destroy
 - script/generate
 - script/txt2html