Module SimPy.Simulation

Simulation 1.6.1
__version__ = '$Revision: 1.1.1.17 $ $Date: 2005/11/12 08:18:36 $ kgm'
LICENSE:
Copyright (C) 2002,2005  Klaus G. Muller, Tony Vignaux
mailto: kgmuller@xs4all.nl and Tony.Vignaux@vuw.ac.nz

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2.1 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public
    License along with this library; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
END OF LICENSE

Implements SimPy Processes, resources, and the backbone simulation scheduling
by coroutine calls.
Based on generators (Python 2.2 and later)

**Change history:**

    Started out as SiPy 0.9
    
    5/9/2002: SiPy 0.9.1
    
        - Addition of '_cancel' method in class Process and supporting '_unpost' method in 
          class __Evlist.
        
        - Removal of redundant 'Action' method in class Process.
        
    12/9/2002:
    
        - Addition of resource class
        
        - Addition of "_request" and "_release" coroutine calls
        
    15/9/2002: moved into SimPy package
    
    16/9/2002:
        - Resource attributes fully implemented (resources can now have more
          than 1 shareable resource units)
        
    17/9/2002:
    
        - corrected removal from waitQ (Vignaux)
        
    17/9/2002:
    
        - added test for queue discipline in "test_demo()". Must be FIFO
        
    26/9/02: Version 0.2.0
    
        - cleaned up code; more consistent naming
        
        - prefixed all Simulation-private variable names with "_".
        
        - prefixed all class-private variable names with "__".
        
        - made normal exit quiet (but return message from scheduler()
        
    28/9/02:
    
        - included stopSimulation()
        
    15/10/02: Simulation version 0.3
    
        - Version printout now only if __TESTING
        
        - "_stop" initialized to True by module load, and set to False in 
      initialize()
        
        - Introduced 'simulate(until=0)' instead of 'scheduler(till=0)'. 
      Left 'scheduler()' in for backward compatibility, but marked
      as deprecated.
        
        - Added attribute "name" to class Process; default=="a_process"
        
        - Changed Resource constructor to 
      'def __init__(self,capacity=1,name="a_resource",unitName="units"'.
        
    13/11/02: Simulation version 0.6
    
        - Major changes to class Resource:
        
            - Added two queue types for resources, FIFO (default) and PriorityQ
            
            - Changed constructor to allow selection of queue type.
            
            - Introduced preemption of resources (to be used with PriorityQ
              queue type)
            
            - Changed constructor of class Resource to allow selection of preemption
            
            - Changes to class Process to support preemption of service
            
            - Cleaned up 'simulate' by replacing series of if-statements by dispatch table.

    19/11/02: Simulation version 0.6.1
        - Changed priority schemes so that higher values of Process 
          attribute "priority" represent higher priority.

    20/11/02: Simulation version 0.7
        - Major change of priority approach:

            - Priority set by "yield request,self,res,priority"

            - Priority of a Process instance associated with a specific 
              resource

    25/11/02: Simulation version 0.7.1

        - Code cleanup and optimization

        - Made process attributes remainService and preempted private 
         (_remainService and _preempted)

    11/12/2002: First process interrupt implementation

        - Addition of user methods 'interrupt' and 'resume'

        - Significant code cleanup to maintain process state

    20/12/2002: Changes to "interrupt"; addition of boolean methods to show
                     process states

    16/3/2003: Changed hold (allowing posting events past _endtime)
    
    18/3/2003: Changed _nextev to prevent _t going past _endtime

    23/3/2003: Introduced new interrupt construct; deleted 'resume' method
    
    25/3/2003: Expanded interrupt construct:
    
        - Made 'interrupt' a method  of Process

        - Added 'interruptCause' as an attribute of an interrupted process

        - Changed definition of 'active' to 
         'self._nextTime <> None and not self._inInterrupt'

        - Cleaned up test_interrupt function

    30/3/2003: Modification of 'simulate':

        - error message if 'initialize' not called (fatal)

        - error message if no process scheduled (warning)

        - Ensured that upon exit from 'simulate', now() == _endtime is 
          always valid

    2/04/2003:

        - Modification of 'simulate': leave _endtime alone (undid change
          of 30 Mar 03)

        - faster '_unpost'

    3/04/2003: Made 'priority' private ('_priority')

    4/04/2003: Catch activation of non-generator error

    5/04/2003: Added 'interruptReset()' function to Process.

    7/04/2003: Changed '_unpost' to ensure that process has
                   _nextTime == None (is passive) afterwards.

    8/04/2003: Changed _hold to allow for 'yield hold,self' 
                   (equiv to 'yield hold,self,0')

    10/04/2003: Changed 'cancel' syntax to 'Process().cancel(victim)'

    12/5/2003: Changed eventlist handling from dictionary to bisect
    
    9/6/2003: - Changed eventlist handling from pure dictionary to bisect-
                sorted "timestamps" list of keys, resulting in greatly 
                improved performance for models with large
                numbers of event notices with differing event times.
                =========================================================
                This great change was suggested by Prof. Simon Frost. 
                Thank you, Simon! This version 1.3 is dedicated to you!
                =========================================================
              - Added import of Lister which supports well-structured 
                printing of all attributes of Process and Resource instances.

    Oct 2003: Added monitored Resource instances (Monitors for activeQ and waitQ)

    13 Dec 2003: Merged in Monitor and Histogram

    27 Feb 2004: Repaired bug in activeQ monitor of class Resource. Now actMon
                 correctly records departures from activeQ.
                 
    19 May 2004: Added erroneously omitted Histogram class.

    5 Sep 2004: Added SimEvents synchronization constructs
    
    17 Sep 2004: Added waituntil synchronization construct
    
    01 Dec 2004: SimPy version 1.5
                 Changes in this module: Repaired SimEvents bug re proc.eventsFired
                 
    12 Jan 2005: SimPy version 1.5.1
                 Changes in this module: Monitor objects now have a default name
                                         'a_Monitor'
                                         
    29 Mar 2005: Start SimPy 1.6: compound "yield request" statements
    
    05 Jun 2005: Fixed bug in _request method -- waitMon did not work properly in
                 preemption case
                 
    09 Jun 2005: Added test in 'activate' to see whether 'initialize()' was called first.
    
    23 Aug 2005: - Added Tally data collection class
                 - Adjusted Resource to work with Tally
                 - Redid function allEventNotices() (returns prettyprinted string with event
                   times and names of process instances
                 - Added function allEventTimes (returns event times of all scheduled events)