rumai 3.1.0 → 3.2.0

data/lib/rumai.rb

@@ -8,8 +8,8 @@ gem 'inochi', '~> 1'
 require 'inochi'
 
 Inochi.init :Rumai,
-  :version => '3.1.0',
-  :release => '2009-10-02',
+  :version => '3.2.0',
+  :release => '2009-11-17',
   :website => 'http://snk.tuxfamily.org/lib/rumai/',
   :tagline => 'Ruby interface to the wmii window manager',
   :develop => {

data/lib/rumai/fs.rb

@@ -16,7 +16,7 @@ module Rumai
 
   begin
     # We use a single, global connection to wmii's IXP server.
-    IXP_AGENT = IXP::Agent.new UNIXSocket.new(IXP_SOCK_ADDR)
+    IXP_AGENT = IXP::Agent.new(UNIXSocket.new(IXP_SOCK_ADDR))
 
   rescue => error
     error.message << %{
@@ -71,7 +71,11 @@ module Rumai
     # Returns the names of all files in this directory.
     #
     def entries
-      IXP_AGENT.entries @path rescue []
+      begin
+        IXP_AGENT.entries @path
+      rescue IXP::Error
+        []
+      end
     end
 
     ##
@@ -205,9 +209,10 @@ module Rumai
     end
   end
 
-  # We use extend() AFTER all methods have been defined in the class so
-  # that the Externalize* module can do its magic.  If we include()d
-  # the module instead before all methods in the class have been
-  # defined, then the magic would only apply to SOME of the methods!
+  # NOTE: We use extend() **AFTER** all methods have been defined
+  #       in the class so that the ExportInstanceMethods module
+  #       can do its magic.  If, instead, we include()d the module
+  #       before all methods in the class had been defined, then
+  #       the magic would only apply to **SOME** of the methods!
   Node.extend ExportInstanceMethods
 end

data/lib/rumai/ixp/message.rb

@@ -66,7 +66,7 @@ module Rumai
       # Transforms this object into a string of 9P2000 bytes.
       #
       def to_9p
-        @fields.inject('') {|s,f| s << f.to_9p(@values) }
+        @fields.inject([]) {|s,f| s << f.to_9p(@values) }.join
       end
 
       ##
@@ -85,7 +85,9 @@ module Rumai
       #
       def self.included target
         class << target
+          ##
           # Returns a list of fields which compose this Struct.
+          #
           def fields
             @fields ||=
               if superclass.respond_to? :fields
@@ -101,22 +103,24 @@ module Rumai
           # [args] arguments for Field.new()
           #
           def field name, format = nil, *args
-            c = Field.factory(format)
-            f = c.new(name.to_sym, format, *args)
-            fields << f # register field as being part of this structure
+            klass = Field.factory(format)
+            field = klass.new(name.to_sym, format, *args)
+
+            # register field as being part of this structure
+            fields << field
 
             # provide accessor methods to field values
-            self.class_eval %{
-              def #{f.name}
-                @values[#{f.name.inspect}]
+            self.class_eval <<-EOS, __FILE__, __LINE__
+              def #{field.name}
+                @values[#{field.name.inspect}]
               end
 
-              def #{f.name}= value
-                @values[#{f.name.inspect}] = value
+              def #{field.name}= value
+                @values[#{field.name.inspect}] = value
               end
-            }
+            EOS
 
-            return f
+            field
           end
 
           ##
@@ -323,7 +327,10 @@ module Rumai
       field :version , 4
       field :path    , 8
 
-      # from http://swtch.com/usr/local/plan9/include/libc.h
+      ##
+      # The following constant definitions originate from:
+      # http://swtch.com/usr/local/plan9/include/libc.h
+      #
       QTDIR       = 0x80       # type bit for directories
       QTAPPEND    = 0x40       # type bit for append only files
       QTEXCL      = 0x20       # type bit for exclusive use files
@@ -355,7 +362,10 @@ module Rumai
       field :gid    , String
       field :muid   , String
 
-      # from http://swtch.com/usr/local/plan9/include/libc.h
+      ##
+      # The following constant definitions originate from:
+      # http://swtch.com/usr/local/plan9/include/libc.h
+      #
       DMDIR       = 0x80000000 # mode bit for directories
       DMAPPEND    = 0x40000000 # mode bit for append only files
       DMEXCL      = 0x20000000 # mode bit for exclusive use files
@@ -435,8 +445,9 @@ module Rumai
       field     :msize   , 4
       field     :version , String
 
-      VERSION = '9P2000'.freeze
-      MSIZE = 8192 # magic number defined in Plan9 for [TR]version and [TR]read
+      VERSION   = '9P2000'.freeze
+      MSIZE     = 8192              # magic number defined in Plan9
+                                    # for [TR]version and [TR]read
     end
 
     # size[4] Rversion tag[2] msize[4] version[s]
@@ -510,7 +521,10 @@ module Rumai
       field     :fid     , 4
       field     :mode    , 1
 
-      # from http://swtch.com/usr/local/plan9/include/libc.h
+      ##
+      # The following constant definitions originate from:
+      # http://swtch.com/usr/local/plan9/include/libc.h
+      #
       OREAD       = 0          # open for read
       OWRITE      = 1          # write
       ORDWR       = 2          # read and write
@@ -688,7 +702,7 @@ class String
   # given 9P2000 byte stream and returns the instance.
   #
   def self.from_9p stream
-    stream.read(stream.read_9p(2))
+    stream.read stream.read_9p(2)
   end
 end
 

data/lib/rumai/ixp/transport.rb

@@ -5,30 +5,29 @@
 #++
 
 require 'rumai/ixp/message'
-require 'thread' # for Mutex
+require 'thread' # for Mutex and Queue
 
 module Rumai
   module IXP
     ##
-    # A thread-safe proxy that multiplexes many
+    # A thread-safe channel that multiplexes many
     # threads onto a single 9P2000 connection.
     #
+    # The send/recv implementation is based on the XCB cookie approach:
+    # http://www.x.org/releases/X11R7.5/doc/libxcb/tutorial/#requestsreplies
+    #
     class Agent
       attr_reader :msize
 
+      ##
+      # [stream]
+      #   I/O stream on which a 9P2000 server is listening.
+      #
       def initialize stream
-        @stream   = stream
-        @send_lock = Mutex.new
-        @recv_bays = Hash.new {|h,k| h[k] = Queue.new } # tag => Queue(message)
-
-        # background thread which continuously receives
-        # and dispatches messages from the 9P2000 server
-        Thread.new do
-          while true
-            msg = Fcall.from_9p @stream
-            @recv_bays[msg.tag] << msg
-          end
-        end.priority = -1
+        @stream = stream
+
+        @recv_buf = {} # tag => message
+        @recv_lock = Mutex.new
 
         @tag_pool = RangedPool.new(0...BYTE2_MASK)
         @fid_pool = RangedPool.new(0...BYTE4_MASK)
@@ -71,7 +70,9 @@ module Rumai
           @pool = Queue.new
         end
 
+        ##
         # Returns an unoccupied range member from the pool.
+        #
         def obtain
           begin
             @pool.deq true
@@ -94,38 +95,79 @@ module Rumai
           end
         end
 
+        ##
         # Marks the given member as being unoccupied so
         # that it may be occupied again in the future.
+        #
         def release member
           @pool << member
         end
       end
 
       ##
-      # Sends the given message (Rumai::IXP::Fcall) and returns its response.
+      # Sends the given request (Rumai::IXP::Fcall) and returns
+      # a ticket that you can use later to receive the reply.
       #
-      # This method allows you to perform a 9P2000 transaction without
-      # worrying about the details of tag collisions and thread safety.
-      #
-      def talk request
-        # send the request
+      def send request
         tag = @tag_pool.obtain
-        bay = @recv_bays[tag]
 
         request.tag = tag
-        output = request.to_9p
-        @send_lock.synchronize do
-          @stream << output
+        @stream << request.to_9p
+
+        tag
+      end
+
+      ##
+      # Returns the reply for the given ticket, which was previously given
+      # to you when you sent the corresponding request (Rumai::IXP::Fcall).
+      #
+      def recv tag
+        loop do
+          reply = @recv_lock.synchronize do
+            if @recv_buf.key? tag
+              @recv_buf.delete tag
+            else
+              # reply was not in the receive buffer, so wait
+              # for the next reply... hoping that it is ours
+              msg = Fcall.from_9p(@stream)
+
+              if msg.tag == tag
+                msg
+              else
+                # we got someone else's reply, so buffer
+                # it (for them to receive) and try again
+                @recv_buf[msg.tag] = msg
+                nil
+              end
+            end
+          end
+
+          if reply
+            @tag_pool.release tag
+
+            if reply.is_a? Rerror
+              raise Error, reply.ename
+            end
+
+            return reply
+          else
+            # give other threads a chance to receive
+            Thread.pass
+          end
         end
+      end
 
-        # receive the response
-        response = bay.shift
-        @tag_pool.release tag
+      ##
+      # Sends the given request (Rumai::IXP::Fcall) and returns its reply.
+      #
+      def talk request
+        tag = send(request)
 
-        if response.is_a? Rerror
-          raise Error, "#{response.ename.inspect} in response to #{request.inspect}"
-        else
-          return response
+        begin
+          recv tag
+        rescue Error => e
+          e.message << " -- in reply to #{request.inspect}"
+          raise
         end
       end
 
@@ -182,7 +224,7 @@ module Rumai
       ##
       # Encapsulates I/O access over a file handle (fid).
       #
-      # NOTE: this class is NOT thread-safe.
+      # NOTE: this class is NOT thread safe!
       #
       class FidStream
         attr_reader :fid, :stat
@@ -276,8 +318,8 @@ module Rumai
         # Writes the given content at the current position in this stream.
         #
         def write content
-          raise 'closed streams cannot be written to' if @closed
-          raise 'directories cannot be written to' if @stat.directory?
+          raise 'cannot write to a closed stream' if @closed
+          raise 'cannot write to a directory' if @stat.directory?
 
           data = content.to_s
           limit = data.length + @pos
@@ -310,7 +352,10 @@ module Rumai
       end
 
       ##
-      # Returns the names of all files inside the directory whose path is given.
+      # Returns the basenames of all files
+      # inside the directory at the given path.
+      #
+      # See Dir::entries in the Ruby documentation.
       #
       def entries path
         unless stat(path).directory?
@@ -321,7 +366,8 @@ module Rumai
       end
 
       ##
-      # Returns the content of the file/directory at the given path.
+      # Writes the given content to
+      # the file at the given path.
       #
       def write path, content
         open path, 'w' do |f|

data/lib/rumai/wm.rb

@@ -21,7 +21,9 @@ module Rumai
   CLIENT_GROUPING_TAG = '@'.freeze
   CLIENT_STICKY_TAG   = '/./'.freeze
 
+  #-----------------------------------------------------------------------------
   # abstraction of WM components
+  #-----------------------------------------------------------------------------
 
     ##
     # NOTE: Inheritors must override the 'chain' method.
@@ -124,7 +126,9 @@ module Rumai
           View.curr.clients
         end
 
+      #-------------------------------------------------------------------------
       # WM operations
+      #-------------------------------------------------------------------------
 
         ##
         # Focuses this client within the given view.
@@ -145,7 +149,6 @@ module Rumai
                 direction = src < dst ? :down : :up
 
                 distance.times { v.select direction }
-
                 break
               end
             end
@@ -288,7 +291,9 @@ module Rumai
 
         alias manage! float!
 
+      #-------------------------------------------------------------------------
       # WM hierarchy
+      #-------------------------------------------------------------------------
 
         ##
         # Returns the area that contains this client within the given view.
@@ -304,7 +309,9 @@ module Rumai
           tags.map! {|t| View.new t }
         end
 
+      #-------------------------------------------------------------------------
       # tag manipulations
+      #-------------------------------------------------------------------------
 
         TAG_DELIMITER = '+'.freeze
 
@@ -388,7 +395,9 @@ module Rumai
           end
         end
 
+      #-------------------------------------------------------------------------
       # multiple client grouping
+      #-------------------------------------------------------------------------
 
         ##
         # Checks if this client is included in the current grouping.
@@ -559,10 +568,17 @@ module Rumai
       # Sets the layout of clients in this column.
       #
       def layout= mode
+        case mode
+        when :stack then mode = 'stack-max'
+        when :max   then mode = 'stack+max'
+        end
+
         @view.ctl.write "colmode #{@id} #{mode}"
       end
 
+      #-------------------------------------------------------------------------
       # WM operations
+      #-------------------------------------------------------------------------
 
         ##
         # Puts focus on this area.
@@ -571,7 +587,9 @@ module Rumai
           @view.ctl.write "select #{@id}"
         end
 
+      #-------------------------------------------------------------------------
       # array abstraction: area is an array of clients
+      #-------------------------------------------------------------------------
 
         ##
         # Returns the number of clients in this area.
@@ -590,7 +608,7 @@ module Rumai
           insert clients
 
           # move inserted clients to bottom
-          clients.each_with_index do |c, i|
+          clients.reverse.each_with_index do |c, i|
             until c.id == self.client_ids[-i.succ]
               c.send :down
             end
@@ -743,7 +761,9 @@ module Rumai
         super view_id, '/tag'
       end
 
+      #-------------------------------------------------------------------------
       # WM operations
+      #-------------------------------------------------------------------------
 
         ##
         # Returns the manifest of all areas and clients in this view.
@@ -759,7 +779,9 @@ module Rumai
           ctl.write "select #{direction}"
         end
 
+      #-------------------------------------------------------------------------
       # WM hierarchy
+      #-------------------------------------------------------------------------
 
         ##
         # Returns the area which contains the given client in this view.
@@ -830,7 +852,9 @@ module Rumai
 
         alias each_managed_area each_column
 
+      #-------------------------------------------------------------------------
       # visual arrangement of clients
+      #-------------------------------------------------------------------------
 
         ##
         # Arranges the clients in this view, while maintaining
@@ -848,13 +872,7 @@ module Rumai
             main.layout = :default
 
             # collapse remaining areas into secondary column
-            extra = columns[1..-1]
-
-            if extra.length > 1
-              extra.reverse.each_cons(2) do |src, dst|
-                dst.concat src
-              end
-            end
+            extra = squeeze_columns(1..-1)
 
             if dock = extra.first
               dock.layout = :default
@@ -887,6 +905,31 @@ module Rumai
           end
         end
 
+        ##
+        # Arranges the clients in this view, while maintaining
+        # their relative order, in the given number of columns.
+        #
+        def arrange_in_stacks num_stacks
+          return if num_stacks < 1
+
+          # compute client distribution
+          num_clients = num_managed_clients
+          return unless num_clients > 0
+
+          stack_length = num_clients / num_stacks
+          return if stack_length < 1
+
+          # apply the distribution
+          maintain_focus do
+            each_column do |a|
+              a.length = stack_length
+              a.layout = :stack
+            end
+
+            squeeze_columns num_stacks-1..-1
+          end
+        end
+
         ##
         # Arranges the clients in this view, while
         # maintaining their relative order, in a (at
@@ -934,15 +977,30 @@ module Rumai
 
       private
 
+      ##
+      # Squeezes all columns in the given index range into a single one.
+      #
+      def squeeze_columns range
+        extra = columns[range]
+
+        if extra.length > 1
+          extra.reverse.each_cons(2) do |src, dst|
+            dst.concat src
+          end
+        end
+
+        extra
+      end
+
       ##
       # Executes the given block and restores
       # focus to the client that had focus
       # before the given block was executed.
       #
       def maintain_focus
-        c = Client.curr
+        c, v = Client.curr, View.curr
         yield
-        c.focus
+        c.focus v
       end
 
       ##
@@ -953,7 +1011,9 @@ module Rumai
       end
     end
 
+  #-----------------------------------------------------------------------------
   # access to global WM state
+  #-----------------------------------------------------------------------------
 
     ##
     # Returns the root of IXP file system hierarchy.
@@ -989,6 +1049,22 @@ module Rumai
         ary
       end
 
+    ##
+    # Returns a list of all grouped clients in
+    # the currently focused view. If there are
+    # no grouped clients, then the currently
+    # focused client is returned in the list.
+    #
+    def grouping
+      list = curr_view.clients.select {|c| c.group? }
+      list << curr_client if list.empty? and curr_client.exist?
+      list
+    end
+
+  #-----------------------------------------------------------------------------
+  # shortcuts for interactive WM manipulation (via IRB)
+  #-----------------------------------------------------------------------------
+
     def curr_client ; Client.curr       ; end
     def next_client ; curr_client.next  ; end
     def prev_client ; curr_client.prev  ; end
@@ -1005,20 +1081,6 @@ module Rumai
     def next_tag    ; next_view.id      ; end
     def prev_tag    ; prev_view.id      ; end
 
-    ##
-    # Returns a list of all grouped clients in
-    # the currently focused view. If there are
-    # no grouped clients, then the currently
-    # focused client is returned in the list.
-    #
-    def grouping
-      list = curr_view.clients.select {|c| c.group? }
-      list << curr_client if list.empty? and curr_client.exist?
-      list
-    end
-
-  # shortcuts for interactive WM manipulation (via IRB)
-
     # provide easy access to container state information
     [Client, Area, View].each {|c| c.extend ExportInstanceMethods }