Heterogeneous Concurrent Modeling and Design in Java (Volume 2: Ptolemy II Software Architecture) Christopher Brooks Edward A. Lee Xiaojun Liu Stephen Neuendorffer Yang Zhao Haiyang Zheng Electrical Engineering and Computer Sciences University of California at Berkeley Technical Report No. UCB/EECS-2007-8 http://www.eecs.berkeley.edu/Pubs/TechRpts/2007/EECS-2007-8.html January 11, 2007 Copyright © 2007, by the author(s). All rights reserved. Permission to make digital or hard copies of all or part of this work for personal or classroom use is granted without fee provided that copies are not made or distributed for profit or commercial advantage and that copies bear this notice and the full citation on the first page. To copy otherwise, to republish, to post on servers or to redistribute to lists, requires prior specific permission. Acknowledgement This work was supported in part by the Center for Hybrid and Embedded Software Systems (CHESS) at UC Berkeley, which receives support from the National Science Foundation (NSF award #CCR-0225610), the State of California Micro Program, Rome AFRL, and the following companies: Agilent, DGIST, General Motors, Hewlett Packard, Infineon, Microsoft, National Instruments, and Toyota. PTOLEMY II HETEROGENEOUS CONCURRENT MODELING AND DESIGN IN JAVA Edited by: Christopher Brooks, Edward A. Lee, Xiaojun Liu, Steve Neuendorffer, Yang Zhao, Haiyang Zheng VOLUME 2: PTOLEMY II SOFTWARE ARCHITECTURE Authors: Shuvra S. Bhattacharyya Department of Electrical Engineering and Computer Sciences University of California at Berkeley Christopher Brooks I T Y • O F S • C R A http://ptolemy.eecs.berkeley.edu E A L V Elaine Cheong I I F N O U R • L John Davis, II N E E L T IG H T T I H H A E T R E BE • Mudit Goel Document Version 6.0 • •1 8 6 8• Bart Kienhuis for use with Ptolemy II 6.0 Edward A. Lee January 11, 2007 Man-Kit Leung Jie Liu Earlier versions: Xiaojun Liu • UCB/ERL M05/22, UCB/ERL M04/16, UCB/ERL M03/28, Lukito Muliadi UCB/ERL M02/23 UCB/ERL M99/40, UCB/ERL M01/12 Steve Neuendorffer John Reekie This work was supported in part by the Center for Hybrid and Embed- Neil Smyth ded Software Systems (CHESS) at UC Berkeley, which receives support Jeff Tsay from the National Science Foundation (NSF award #CCR-0225610), the Brian Vogel State of California Micro Program, Rome AFRL, and the following com- Winthrop Williams panies: Agilent, DGIST, General Motors, Hewlett Packard, Infineon, Yuhong Xiong Microsoft, National Instruments, and Toyota. Yang Zhao Haiyang Zheng Gang Zhou Copyright © 1998-2007 The Regents of the University of California. All rights reserved. “Java” is a registered trademark of Sun Microsystems. VOLUME 2 PTOLEMY II SOFTWARE ARCHITECTURE This volume describes the software architecture of Ptolemy II. The first chapter covers the kernel package, which provides a set of Java classes supporting clustered graph topologies for models. Clus- ter graphs provide a very general abstract syntax for component-based modeling, without assuming or imposing any semantics on the models. The actor package begins to add semantics by providing basic infrastructure for data transport between components. The data package provides classes to encapsu- late the data that is transported. It also provides an extensible type system and an interpreted expres- sion language. The graph package provides graph-theoretic algorithms that are used in the type system and by schedulers in the individual domains. The plot package provides a visual data plotting utility that is used in many of the applets and applications. The codegen package is a templated based code generator similar to the Ptolemy Classic code generators. The copernicus package is a code generator that performs static analysis on Java class files to produce smaller, faster executable models. Volume 1 gives an introduction to Ptolemy II, including tutorials on the use of the software, and vol- ume 3 describes the domains, each of which implements a model of computation. This page intentionally left mostly blank. Contents Volume 2 Ptolemy II Software Architecture 3 Contents 5 1. The Kernel 1 1.1. Abstract Syntax 1 1.2. Non-Hierarchical Topologies 2 1.2.1. Links 2 1.2.2. Consistency 2 1.3. Support Classes 4 1.3.1. Containers 4 1.3.2. Name and Full Name 4 1.3.3. Workspace 6 1.3.4. Attributes 6 1.3.5. List Classes 8 1.4. Clustered Graphs and Hierarchy 9 1.4.1. Abstraction 9 1.4.2. Relation Groups 12 1.4.3. Level-Crossing Connections 12 1.4.4. Tunneling Entities 13 1.4.5. Cloning 14 1.4.6. An Elaborate Example 14 1.5. Opaque Composite Entities 14 1.6. Concurrency 15 1.6.1. Limitations of Monitors 18 1.6.2. Read and Write Access Permissions for Workspace 20 1.7. Mutations 21 1.7.1. Change Requests 21 1.7.2. NamedObj and Listeners 23 1.8. Actor-Oriented Classes 24 1.9. Exceptions 25 1.9.1. Base Class 25 1.9.2. Less Severe Exceptions 25 1.9.3. More Severe Exceptions 27 2. Actor Package 29 2.1. Concurrent Computation 29 2.2. Message Passing 30 2.2.1. Data Transport 30 2.2.2. Example 33 2.2.3. Transparent Ports 34 2.2.4. Data Transfer in Various Models of Computation 36 2.2.5. Discussion of the Data Transfer Mechanism 39 2.3. Execution 40 2.3.1. Director 42 2.3.2. Manager 46 2.3.3. ExecutionListener 46 2.3.4. Opaque Composite Actors 47 2.4. Scheduler and Process Support 48 2.4.1. Function Dependency 48 2.4.2. Statically Scheduled Domains 49 2.4.3. Process Domains 51 3. Data Package 55 3.1. Introduction 55 3.2. Data Encapsulation 55 3.2.1. Matrix data types 57 3.2.2. Array and Record data types 57 3.2.3. Fixed Point Data Type 57 3.2.4. Function Closures 59 3.2.5. Nil Tokens 59 3.3. Immutability 59 3.4. Polymorphism 60 3.4.1. Polymorphic Arithmetic Operators 60 3.4.2. Automatic Type Conversion 61 3.5. Variables and Parameters 64 3.5.1. Values 64 3.5.2. Types 64 3.5.3. Dependencies 68 3.6. Expressions 68 3.7. Unit System 70 3.8. The Static Unit System 71 3.8.1. Unit Systems 72 3.8.2. Units of Measurement Algebra 73 3.8.3. Descriptive Form Language 75 3.8.4. Implementing the Static Unit System in Ptolemy 76 3.8.5. The Unit Library 78 3.8.6. Generating Descriptive Forms 78 3.8.7. UnitsConstraint Solver 79 3.8.8. Minimal Span Solutions 82 3.8.9. Implementing the Units Constraint Solver 85 Appendix: Expression Evaluation 86 Generating the parse tree 86 Traversing the parse tree 87 Node types 88 Extensibility 90 4. Graph Package 91 4.1. Introduction 91 4.2. Classes and Interfaces in the Graph Package 92 4.2.1. Element and ElementList 92 4.2.2. Labeled Lists 92 4.2.3. Node 92 4.2.4. Edge 93 4.2.5. Graph 93 4.2.6. Directed Graphs 93 4.2.7. Graph Mappings 97 4.2.8. Graph Analysis 97 4.2.9. Graph Analyzers 101 4.2.10. Strategies 102 4.2.11. Cached Strategies vs. Non-Cached Strategies 105 4.2.12. Graph Schedules 106 4.2.13. Graph Exceptions 107 4.2.14. Directed Acyclic Graphs and CPO 109 4.2.15. Inequality Terms, Inequalities, and the Inequality Solver 110 4.3. Example Use 111 4.3.1. Generating A Schedule for a Composite Actor 111 4.3.2. Forming and Solving Constraints over a CPO 111 5. Type System 115 5.1. Introduction 115 5.2. Formulation 119 5.2.1. Type Constraints 119 5.2.2. Run-time Type Checking and Lossless Type Conversion 120 5.3. Structured Types 121 5.3.1. Setting Up Type Constraints 122 5.4. Implementation 125 5.4.1. Implementation Classes 125 5.4.2. Type Checking and Type Resolution 126 5.4.3. Some Implementation Details 128 5.5. Examples 129 5.5.1. Polymorphic DownSample 129 5.5.2. Fork Connection 129 5.6. Actors Constructing Tokens with Structured Types 130 Appendix: The Type Resolution Algorithm 131 6. Plot Package 133 6.1. Overview 133 6.2. Using Plots 134 6.2.1. Zooming and filling 135 6.2.2. Printing and exporting 135 6.2.3. Editing the data 137 6.2.4. Modifying the format 138 6.3. Class Structure 139 6.3.1. Toolkit classes 140 6.3.2. Applets and applications 140 6.3.3. Writing applets 143 6.4. PlotML File Format 145 6.4.1. Data organization 146 6.4.2. Configuring the axes 147 6.4.3. Configuring data 150 6.4.4. Specifying data 151 6.4.5. Bar graphs 152 6.4.6. Histograms 152 6.5. Old Textual File Format 152 6.5.1. Commands Configuring the Axes 153 6.5.2. Commands for Plotting Data 154 6.6. Compatibility 155 6.7. Limitations 156 7. Code Generation 157 7.1. Motivation 157 7.2. A Helper-based Mechanism 158 7.2.1. What is in a C Code Template File? 159 7.2.2. What is in a Helper Java Class File? 160 7.2.3. The Macro Language 160 7.2.4. The CountTrues Example 162 7.3. Overview of The Software Architecture 163 7.4. Domains 167 7.4.1. SDF 167 7.4.2.