dramatis 0.0.1

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

@@ -0,0 +1,128 @@
+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
+# actor. It is typically created via Dramatis.interface.
+
+class Dramatis::Actor::Name::Interface
+
+  # call-seq:
+  #  continue nil -> a_name
+  #  continue { |retval| ... } -> a_name
+  #  continue( :exception => lambda { |exception| ... } ) { |retval| ... } -> a_name
+  #
+  # In call cases, returns a new name with the specified continuation semantics.
+  #
+  # When passed a nil argument, returns a new actor name with a nil
+  # continuation such that when used in an actor method call, the call
+  # will return nil immediately. The return value from such a call is
+  # lost. Equivalent to and usually called as Dramatis.release.
+  #
+  # The second form sets up the block passed to the function as the
+  # continuation of the call. When the continuation task is received from the
+  # target actor, the block will be executed. From senders point of
+  # view, the block is an unnamed method: it will only be
+  # scheduled when the actor is not executing any other task.
+  #
+  # Currently it is not possible to gate off block continuations.
+  #
+  # The third example is a variant on the second and is used to
+  # provide a second block to receive an exception object if the actor
+  # method call results in an exception being thrown. Otherwise, the
+  # runtime will try to deliver exceptions to a dramatis_exception
+  # actor method if defined. Otherwise it will be recored by the
+  # runtime.
+  #
+  #--
+  # this stuff is either tricky or evil; i need to lookup
+  # variable look ordering for instance_eval
+  # i'm assuming lexical scope over object scope
+  #++
+
+  def continue options = {}, &continuation
+    raise "contradictory options passed to continue" \
+        if ( options == nil and continuation ) or
+           ( options and !continuation )
+    a, o = @name.instance_eval { [ @actor, @options ] }
+    @name = Dramatis::Actor::Name.new a
+    @name.instance_eval do
+      @options = o.dup
+      @options[:continuation] = options == nil ? :none : continuation
+      options and @options[:exception] = options[:exception]
+    end
+    @name
+  end
+
+  
+  # call-seq:
+  #   future -> a_name
+  # 
+  # Returns a new actor name that when used in an actor method call will return a Dramatis::Future. Usually
+  # called via Dramatis.future rather than directly.
+
+  def future
+    a, o = @name.instance_eval { [ @actor, @options ] }
+    @name = Dramatis::Actor::Name.new a
+    @name.instance_eval do
+      @options = o.dup
+      @options[:continuation] = :future
+    end
+    @name
+  end
+
+  # 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
+  # result of the call is the actor name of the actor. The
+  # continuation semantics of the call depend on the name like a
+  # normal actor method call.
+
+  def bind behavior
+    actor_send :bind, behavior
+  end
+
+  def url #:nodoc: not done
+    "http://something"
+  end
+
+  def exception exception #:nodoc: this should be private/protected
+    actor_send :exception, exception
+  end
+
+  private
+
+  def continuation c, options
+    a, o = @name.instance_eval { [ @actor, @options ] }
+    @name = Dramatis::Actor::Name.new a
+    @name.instance_eval do
+      @actor.register_continuation c
+      @options = o.dup
+      @options[:continuation_send] = c.to_s
+      @options[:continuation] = :none
+      # FIX merge options, rather than cherry-pck
+      options[:call_thread] and @options[:call_thread] = options[:call_thread]
+    end
+    @name
+  end
+
+  def actor_send *args, &block
+    @name.instance_eval do
+      options = @options
+      if block
+        options = options.dup
+        options[:block] = block
+      end
+      @actor.actor_send args, options
+    end
+  end
+
+  def initialize name #:nodoc:
+    raise "hell: " + name.inspect \
+      if !name or !name.kind_of? Dramatis::Actor::Name
+    @name = name
+  end
+
+end
+

data/lib/dramatis/actor/name.rb

@@ -0,0 +1,44 @@
+module Dramatis; end
+module Dramatis::Actor; end
+class Dramatis::Actor::Name; end
+
+require 'dramatis/actor'
+
+# Dramatis::Actor::Names are proxy objects for actors. When a method
+# is called on an actor name, the dramatis runtime creates and
+# schedules an actor task to be run on the actors (virtual) thread.
+
+# Dramatis::Actor::Name has no user-callable methods (except for the
+# implicit method_missing). Other actor name operations are available
+# through the Dramatis::Actor::Name::Interface object, accessible via
+# Dramatis.interface.
+
+class Dramatis::Actor::Name
+
+  def to_s_off #:nodoc:
+    method_missing :to_s
+  end
+
+  def dup #:nodoc:
+    raise "hell again"
+  end
+
+  def method_missing *args, &block  #:nodoc:
+    options = @options
+    if block
+      options = options.clone
+      options[:block] = block
+    end
+    @actor.object_send args, options
+  end
+
+  private
+
+  def initialize actor #:nodoc:
+    raise "hell" if !actor or !actor.kind_of? Dramatis::Runtime::Actor
+    @actor = actor
+    @options = { :continuation => :rpc }
+    self
+  end
+
+end

data/lib/dramatis/actor.rb

@@ -0,0 +1,96 @@
+module Dramatis; end
+module Dramatis::Actor; end
+
+require 'dramatis/runtime/actor'
+
+# The Dramatis::Actor module is used to create actor classes and
+# objects. An actor class can be created by mixing Dramatis::Actor, e.g.,
+#    class MyClass
+#      include Dramatis::Actor
+#      ...
+#    end
+# or can be used to create so called _naked_ _actors_, e.g.,
+#    my_hash_actor = Dramatis::Actor.new Hash.new
+#
+# When mixed in to a class, Dramatis::Actor has two effects:
+# 1. It causes new to return a Dramatis::Actor::Name rather than an object reference
+# 1. It defines an actor method which can be used by the class to access its actor name and
+#    otherwise affect its actor semantics
+
+module Dramatis::Actor
+
+  def self.included cls #:nodoc:
+    cls.instance_eval do
+      include Dramatis
+    end
+    class << cls
+      def new *args
+        new_actor = Dramatis::Runtime::Actor.new
+        object = allocate
+        eigenclass = ( class << object; self; end )
+        eigenclass.send :define_method, :actor,
+                ( lambda { new_actor.object_interface } )
+        new_actor.bind object
+        new_actor.instance_eval { @gate.refuse :object }
+        new_actor.actor_send [ :object_initialize, *args ], 
+                               :continuation => :rpc
+        new_actor.name
+      end
+    end
+  end
+
+  if false # for docs only ...
+
+    # call-seq:
+    #  actor -> an_interface
+    #
+    # actor provides classes that have mixed in Dramatis::Actor access
+    # to a Dramatis::Actor::Interface object by which they can access
+    # their actor name and other actor operations.
+
+    def actor; end
+
+  end
+
+  # call-seq:
+  #  new( *args, &block ) -> an_actor_name
+  #  new( behavior = nil ) -> an_actor_name
+  #
+  # The first case is used when a class has mixed in
+  # Dramatis::Actor. In this case, the arguments are passed to the 
+  # initialize of method of the including class like normal.
+  #
+  # The second case is used when creating so called <em>naked
+  # actors</em>, e.g.,
+  #  my_hash = Dramatis::Actor.new Hash.new
+  # If no
+  # behavior is provided, the actor can be later bound to a behavior
+  # by calling Dramatis::Actor::Name::Interface.bind
+  #
+  # In all cases, new returns a Dramatis::Actor::Name proxy
+  # object.
+
+  def self.new behavior = nil
+    ( Dramatis::Runtime::Actor.new behavior ).name
+  end
+
+  if false
+    def self.included cls #:nodoc:
+      pp caller(0)
+      warn "Dramatis::Actor included by #{cls}"
+    end
+
+    def self.derived cls #:nodoc:
+      warn "Dramatis::Actor included by #{cls}"
+    end
+
+    def self.extended cls #:nodoc:
+      warn "Dramatis::Actor included by #{cls}"
+    end
+
+    def self.inherited cls #:nodoc:
+      warn "Dramatis::Actor included by #{cls}"
+    end
+  end
+
+end

data/lib/dramatis/deadlock.rb

@@ -0,0 +1,123 @@
+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
+# 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
+# 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/uncaught.rb

@@ -0,0 +1,19 @@
+module Dramatis; end
+
+class Dramatis::Error < StandardError; end
+
+# Exception raised when the runtime exits with uncaught exceptions.
+
+class Dramatis::Error::Uncaught < Dramatis::Error
+
+  # combines the name of all uncaught exceptions.
+
+  def to_s
+    super + ": " + @exceptions.join( " "  )
+  end
+
+  def initialize exceptions #:nodoc:
+    @exceptions = exceptions
+  end
+
+end

data/lib/dramatis/error.rb

@@ -0,0 +1,125 @@
+module Dramatis; end
+
+# The base class of all non-internal dramatis exceptions.
+
+class Dramatis::Error < StandardError; end
+
+# Raised when an attempt is made to create an interface object on an
+# object that does not define an interface class.
+
+class Dramatis::Error::Interface < StandardError; end
+
+# Raised when an attempt is made to bind an already-bound actor.
+
+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_
+
+  def initialize _next
+  end
+
+end
+
+class Exception
+
+  alias _dramatis_set_backtrace set_backtrace 
+  alias _dramatis_backtrace backtrace 
+
+  def set_backtrace arg
+    # p "set back #{self}"
+    _dramatis_set_backtrace arg
+  end
+
+  def backtrace
+    # p "back #{self}"
+    if instance_variable_defined? :@_dramatis_raw_backtrace
+      filter @_dramatis_raw_backtrace
+    else
+      _dramatis_backtrace
+    end
+  end
+
+  def _dramatis_reraise
+    # return
+    # p "reraise"
+    if @_dramatis_raw_backtrace
+      @_dramatis_raw_backtrace = backtrace + filter( caller )
+    else
+      @_dramatis_raw_backtrace = filter( backtrace ) + filter( caller )
+    end
+  end
+
+  def filter array
+
+    # pp "_", array
+
+    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
+    
+    # pp "0", filtered
+    
+    # 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]
+    filtered
+    # super args[0]
+  end
+
+end

data/lib/dramatis/future/interface.rb

@@ -0,0 +1,45 @@
+module Dramatis; end
+class Dramatis::Future; end
+
+# A Dramatis::Future::Interface object provides the ability to
+# observe and access the semantics of a future. It is typically
+# created via Dramatis.interface.
+
+class Dramatis::Future::Interface
+
+  # 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.
+  #
+  # 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
+  # metaprogramming.
+
+  def value
+    @future.instance_eval do
+      @continuation.value
+    end
+  end
+
+  # Returns true if the future may be evaluated without
+  # blocking. Returns false if the value is not yet available.
+  #
+  # Once a future is ready it cannot become unready, so once ready? returns
+  # true, it will always be true and value access will never block.
+
+  def ready?
+    @future.instance_eval do
+      @continuation.ready?
+    end
+  end
+
+  def initialize *args, &block #:nodoc:
+    @future = args.shift
+    @args = args
+    @block = block
+  end
+
+end
+

data/lib/dramatis/future.rb

@@ -0,0 +1,32 @@
+module Dramatis; end
+
+# Dramatis::Futures are proxy objects for the values returned from
+# actor method calls made with future continuations. When a method is
+# called on a future, the runtime checks to see if the future has been
+# evaluated and returned from the actor that executed the task. If it
+# has, the method is executed on the returned value as if the proxy
+# object was not there.
+#
+# If the task with the future continuation has not yet completed or
+# the continuation task has not yet been run, the method called on
+# the proxy is suspended until the reply is received. Thus, methods on
+# futures sometimes but not always block. If they block, they have
+# normal continuation gating semantics.
+#
+# Dramatis::Future has no user-callable methods (except for the
+# implicit method_missing). Other future operations are available
+# through the Dramatis::Future::Interface object, accessible via
+# Dramatis.interface.
+
+class Dramatis::Future
+
+  def method_missing *args #:nodoc:
+    @continuation.value.send( *args )
+  end
+
+  def initialize continuation #:nodoc:
+    @continuation = continuation
+  end
+
+end
+

data/lib/dramatis/runtime/actor/main.rb

@@ -0,0 +1,3 @@
+module Dramatis; end
+class Dramatis::Runtime; end
+