hooke/engine.py

   1 # Copyright (C) 2010 W. Trevor King <wking@drexel.edu>
   2 #
   3 # This file is part of Hooke.
   4 #
   5 # Hooke is free software: you can redistribute it and/or modify it
   6 # under the terms of the GNU Lesser General Public License as
   7 # published by the Free Software Foundation, either version 3 of the
   8 # License, or (at your option) any later version.
   9 #
  10 # Hooke is distributed in the hope that it will be useful, but WITHOUT
  11 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  12 # or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General
  13 # Public License for more details.
  14 #
  15 # You should have received a copy of the GNU Lesser General Public
  16 # License along with Hooke.  If not, see
  17 # <http://www.gnu.org/licenses/>.
  18
  19 """The `engine` module provides :class:`CommandEngine` for executing
  20 :class:`hooke.command.Command`\s.
  21 """
  22
  23 import logging
  24 from Queue import Queue, Empty
  25
  26 from .command import NullQueue
  27
  28
  29 class QueueMessage (object):
  30     def __str__(self):
  31         return self.__class__.__name__
  32
  33
  34 class CloseEngine (QueueMessage):
  35     pass
  36
  37
  38 class CommandMessage (QueueMessage):
  39     """A message storing a command to run, `command` should be the
  40     name of a :class:`hooke.command.Command` instance, and `arguments`
  41     should be a :class:`dict` with `argname` keys and `value` values
  42     to be passed to the command.
  43     """
  44     def __init__(self, command, arguments=None):
  45         self.command = command
  46         if arguments == None:
  47             arguments = {}
  48         self.arguments = arguments
  49
  50
  51 class CommandEngine (object):
  52     def run(self, hooke, ui_to_command_queue, command_to_ui_queue):
  53         """Get a :class:`QueueMessage` from the incoming
  54         `ui_to_command_queue` and act accordingly.
  55
  56         If the message is a :class:`CommandMessage` instance, the
  57         command run may read subsequent input from
  58         `ui_to_command_queue` (if it is an interactive command).  The
  59         command may also put assorted data into `command_to_ui_queue`.
  60
  61         When the command completes, it will put a
  62         :class:`hooke.command.CommandExit` instance into
  63         `command_to_ui_queue`, at which point the `CommandEngine` will
  64         be ready to receive the next :class:`QueueMessage`.
  65         """
  66         log = logging.getLogger('hooke')
  67         while True:
  68             log.debug('engine waiting for command')
  69             msg = ui_to_command_queue.get()
  70             if isinstance(msg, CloseEngine):
  71                 command_to_ui_queue.put(hooke)
  72                 log.debug(
  73                     'engine closing, placed hooke instance in return queue')
  74                 break
  75             assert isinstance(msg, CommandMessage), type(msg)
  76             log.debug('engine running %s with %s'
  77                       % (msg.command, msg.arguments))
  78             cmd = hooke.command_by_name[msg.command]
  79             cmd.run(hooke, ui_to_command_queue, command_to_ui_queue,
  80                     **msg.arguments)
  81
  82     def run_command(self, hooke, command, arguments):
  83         """Internal command execution.
  84
  85         This allows commands to execute sub commands and enables
  86         :class:`~hooke.command_stack.CommandStack` execution.
  87
  88         Note that these commands *do not* have access to the usual UI
  89         communication queues, so make sure they will not need user
  90         interaction.
  91         """
  92         log = logging.getLogger('hooke')
  93         log.debug('engine running internal %s with %s'
  94                   % (command, arguments))
  95         cmd = hooke.command_by_name[command]
  96         outqueue = Queue()
  97         cmd.run(hooke, NullQueue(), outqueue, **arguments)
  98         while True:
  99             try:
 100                 msg = outqueue.get(block=False)
 101             except Empty:
 102                 break
 103             log.debug('engine message from %s (%s): %s' % (command, type(msg), msg))