<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> <title>Frepple / Code structure </title> <link rel='stylesheet' href='../styles.css' type='text/css' /> <!--PageHeaderFmt--> </head> <body> <div id="container"> <div id="menubar"> <div id="logo" align="center"> <br/><img src='../frepple.bmp' alt="frepple" /><br/> <a href='http://www.frepple.com/'> <strong>a Free<br/>Production Planning<br/>Library</strong> </a></div> <div id="menu"> <br/> <h3><a href='../Main/HomePage.html'>Main</a></h3> <h3><a href='../UI/Main.html'>User Manual</a></h3> <h3><a href='../Tutorial/Main.html'>Tutorial</a></h3> <h3><a href='Main.html'>Reference Manual</a></h3> <h3><a href='../Main/FAQ.html'>FAQ</a></h3> <h3><a href='../reference/index.html'>C++ API</a></h3> <br/><div> </div> </div> </div> <div id="content"> <br/> <!--PageText--> <div id='wikitext'> <p><a class='wikilink' href='../Main/HomePage.html'>Main</a> > <span class='wikitrail'><a class='wikilink' href='Main.html'>Reference Manual</a> > <a class='wikilink' href='Developer.html'>Information for developers</a> > <a class='selflink' href='DeveloperCodestructure.html'>Code structure</a></span> </p> <p class='vspace'>This chapter provides a high level description of the code structure. <br />It provides brief notes that helps a developer find his/her way in the detailed <a class='urllink' href='http://www.frepple.com/reference/index.html' rel='nofollow'>C++ API reference</a> and <a class='wikilink' href='DeveloperClassdiagram.html'>Class diagram</a> . </p> <p class='vspace'>Three layers can be distinguished: </p> <div class='vspace'></div><ul><li><strong>Utility classes</strong> which provide infrastructure-like services as a foundation for the next layers. <ul><li><a href='DeveloperCodestructure.html#object'>Object</a> as an abstract base class for all frePPLe objects. </li><li><a href='DeveloperCodestructure.html#metadata'>Metadata</a> about objects. </li><li><a href='DeveloperCodestructure.html#date'>Date, DateRange and TimePeriod</a> for dealing with dates and times. </li><li><a href='DeveloperCodestructure.html#timer'>Timer</a> for measuring execution time. </li><li><a href='DeveloperCodestructure.html#xml'>XML serialization</a> for reading and writing XML data. </li><li><a href='DeveloperCodestructure.html#python'>Python binding</a> for interfacing with Python. </li><li><a href='DeveloperCodestructure.html#command'>Command</a> for executing state changes. </li><li><a href='DeveloperCodestructure.html#exception'>Exception classes</a> for reporting error conditions. </li><li><a href='DeveloperCodestructure.html#mutex'>Mutex</a> provides support for concurrent access to memory objects in a multithreaded environment. </li><li><a href='DeveloperCodestructure.html#name'>HasName and Tree</a> for representing entities with a name and storing them in a binary tree container. </li><li><a href='DeveloperCodestructure.html#hierarchy'>HasHierarchy</a> allows objects be structured in a hierarchical tree, ie to refer to a parent and have children. </li><li><a href='DeveloperCodestructure.html#leveled'>Leveled</a> for representing entities that are connected in a network graph. </li></ul></li><li><strong>Model classes</strong> which represent the core modeling objects.<br /> See the chapter <a class='wikilink' href='Modeling.html'>Modeling</a> for the details.<br /> They are structured as a base class (or Category) with one or more concrete implementations (or Classes). </li><li><strong>Extension classes</strong> which inherit from the core model classes and implement specific new models or solver techniques.<br /> See the section <a class='wikilink' href='DeveloperExtend.html'>Extension modules</a> for more details. </li></ul><div class='vspace'></div><h3><a name='object' id='object'></a>Object</h3> <p>Object is an abstract base class. <br />It handles to following capabilities: </p> <div class='vspace'></div><ul><li>Metadata: All subclasses publish metadata about their structure and the memory they consume. </li><li>Concurrency: Locking of objects is required in multithreaded environments. The implementation of the locking mechanism is delegated to the LockManager class, and this class provides only a pointer to a lock object and convenience guard classes. </li><li>Callbacks: When objects are created, changing or deleted, interested classes or objects can get a callback notification. </li><li>Serialization: Objects need to be persisted and later restored. <br />Subclasses that don't need to be persisted can skip the implementation of the writeElement method. </li></ul><div class='vspace'></div><h3><a name='metadata' id='metadata'></a>MetaData</h3> <p>FrePPLe uses a two level structure to group metadata: </p> <div class='vspace'></div><ul><li>A <strong>MetaCategory</strong> represents an entity type. The metacategory will implement a container for all instances of this type, and also a handler method to control persistence of the objects. <br />E.g. "Buffer" </li><li>A <strong>MetaClass</strong> represents a concrete class. It belongs to a certain MetaCategory, and contains a factory method to generate objects. <br />E.g. "BufferDefault", "BufferMinMax", "BufferInfinite"... </li><li><strong>MetaData</strong> is the abstract base class for the concrete class MetaClass and MetaCategory. </li></ul><p class='vspace'>After creating an MetaClass or MetaData object it needs to be registered, typically in the initialization of the library. </p> <div class='vspace'></div><h3><a name='date' id='date'></a>Date - DateRange - TimePeriod</h3> <p>These classes allow easy and intuitive manipulation of dates, durations and date ranges. <br />The classes are implemented as a thin wrapper around the standard ansi C time functions and provides time accuracy of 1 second. </p> <p class='vspace'>Durations are formatted according to ISO8601. </p> <p class='vspace'>An example: </p> <div class='vspace'></div><pre> Date start = Date::now(); TimePeriod duration("P1D"); Date end = d + t; DateRange dr(start, end); cout << d << " " << t << " " << dr << endl; </pre><p class='vspace'>The C library is respecting daylight saving time (DST). Depending on the timezone configured on your computer, you will have two days a year which last 23 or 25 hours instead of the regular 24 hours.<br />This means that "midnight on day 1" + "24 hours" will not always give you "midnight on day 2"! </p> <div class='vspace'></div><h3><a name='timer' id='timer'></a>Timer</h3> <p>This is a class to measure the excution time of the application with (at least) millisecond precision. <br />An example: </p> <div class='vspace'></div><pre> Timer t; do_something(); cout << "something took " << t << " seconds" << endl; t.restart(); do_something_else(); cout << "something else took " << t << " seconds" << endl; </pre><div class='vspace'></div><h3><a name='exception' id='exception'></a>Exception</h3> <p>FrePPLe uses 3 exception classes to report errors. Each of the classes inherits from std::exception. </p> <div class='vspace'></div><ul><li>A <strong>DataException</strong> is thrown when data errors are found. <br />The expected handling of this error is to catch the exception and allow the execution of the program to continue. </li><li>A <strong>RuntimeException</strong> is thrown when the library runs into problems that are specific at runtime. <br /> These could either be memory problems, threading problems, file system problems, etc... Errors of this type can be caught by the client applications and the application can continue in most cases. </li><li>A <strong>LogicException</strong> is thrown when the code runs into an unhandled and unexpected situation. <br /> The normal handling of this error is to exit the program, and report the problem. This exception always indicates a bug in the program code. </li></ul><div class='vspace'></div><h3><a name='xml' id='xml'></a>XML Serialization</h3> <p>The Object base class provides the following methods that need to be implemented by serializable clasess: </p><ul><li>The <strong>beginElement</strong> is called by the parser when reading the start of a tag. </li><li>The <strong>endElement</strong> event is called by the parser when reading the end of a tag or attribute. </li><li>The <strong>writeElement</strong> is called when serializing the object. </li></ul><p class='vspace'>FrePPLe uses the SAX parser from Xerces-C to parse and validate input XML data.<br />The class <strong>XMLInput</strong> is a wrapper around the parser. It receives the SAX events and makes the appropriate calls to the frePPLe objects.<br />Subclasses are available to parse a file or a string. </p> <p class='vspace'>Writing XML output is done with the <strong>XMLOutput</strong> class which provides methods to write a header, elements and attributes. Subclasses are available to write to a file or a string. </p> <div class='vspace'></div><h3><a name='python' id='python'></a>Python binding</h3> <p>A couple of utility classes are available to simplify the use of the Python C-api in the frePPLe C++ code. </p> <div class='vspace'></div><ul><li>The <strong>PythonObject</strong> class handles two-way translation between the data types between C++ and Python. </li><li>The template class <strong>PythonExtension</strong> is used to define Python extensions. </li><li>The <strong>PythonType</strong> class is a wrapper around the type information in Python. </li><li>The <strong>PythonInterpreter</strong> class maintains the Python interpreter. </li></ul><div class='vspace'></div><h3><a name='command' id='command'></a>Command</h3> <p>This class implements the design pattern with the same name. All state changes in the application are expected to be encapsulated in objects of this class. </p> <p class='vspace'>The CommandList class works as a wrapper for a collection of other commands, following the classic composite design pattern. <br />This allows command hierarchies to be constructed, which can be executed in sequence or in parallel. </p> <div class='vspace'></div><h3><a name='mutex' id='mutex'></a>Mutex</h3> <p>Working with frePPLe in a multithreaded environment requires special control over concurrent access to the objects in memory. </p> <div class='vspace'></div><ul><li><strong>Mutex</strong> allows exclusive access to a object. <br />Depending on your platform it is implement as a thin wrapper around a Windows critical_section or as pthread pthread_mutex_t. </li><li><strong>ScopeMutexLock</strong> is a convenience class that makes it easy (and exception-safe) to lock a mutex in a scope. </li><li>The <strong>CommandList</strong> (described above) has the capability to execute commands in parallel by spawning seperate threads. </li></ul><div class='vspace'></div><h3><a name='name' id='name'></a>HasName and Tree</h3> <p>The classes represent classes which use a std::string / name as a unique identifier. <br />The Tree class is implemented as a red-black binary tree, using HasName objects as the nodes (i.e. intrusive container). </p> <div class='vspace'></div><h3><a name='hierarchy' id='hierarchy'></a>HasHierarchy</h3> <p>The class allows allows objects be structured in a hierarchical tree. A HasName object can point to a single parent and it maintains a linked list of children. </p> <div class='vspace'></div><h3><a name='leveled' id='leveled'></a>Leveled</h3> <p>The model classes Operation, Buffer, Resource, Load and Flow are the key objects that are used to represent the network.<br />The first three represent the actual entities, while Load and Flow represent associations/links between the entities.<br />See the section <a class='wikilink' href='Solvercluster.html'>Cluster and level algorithm</a> for the details. </p> </div> <!--PageFooterFmt--> <!--HTMLFooter--> </div></div> </body> </html>
