frePPLev2.0
open source Production PLanning
  • Home
  • Documentation
    • Getting started
    • Modeling guide
    • User guide
    • Installation guide
    • Developer guide
    • FAQ
  • C++ API

Code structure

This chapter provides a high level description of the code structure.
It provides brief notes that helps a developer find his/her way in the detailed C++ API reference (provided in the documentation) and Class diagram .

Three layers can be distinguished:

  • Utility classes which provide infrastructure-like services as a foundation for the next layers.
    • Object as an abstract base class for all frePPLe objects.
    • Metadata about objects.
    • Date, DateRange and TimePeriod for dealing with dates and times.
    • Timer for measuring execution time.
    • XML serialization for reading and writing XML data.
    • Python binding for interfacing with Python.
    • Command for executing state changes.
    • Exception classes for reporting error conditions.
    • Mutex provides support for concurrent access to memory objects in a multi-threaded environment.
    • HasName and Tree for representing entities with a name and storing them in a binary tree container.
    • HasHierarchy allows objects be structured in a hierarchical tree, ie to refer to a parent and have children.
    • Leveled for representing entities that are connected in a network graph.
  • Model classes which represent the core modeling objects.
    See the chapter Modeling for the details.
    They are structured as a base class (or Category) with one or more concrete implementations (or Classes).
  • Extension classes which inherit from the core model classes and implement specific new models or solver techniques.
    See this section for more details.

Object

Object is an abstract base class.
It handles to following capabilities:

  • Metadata: All subclasses publish metadata about their structure and the memory they consume.
  • 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.
  • Callbacks: When objects are created, changing or deleted, interested classes or objects can get a callback notification.
  • Serialization: Objects need to be persisted and later restored.
    Subclasses that don’t need to be persisted can skip the implementation of the writeElement method.

MetaData

FrePPLe uses a two level structure to group metadata:

  • A MetaCategory 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.
    E.g. “Buffer”
  • A MetaClass represents a concrete class. It belongs to a certain MetaCategory, and contains a factory method to generate objects.
    E.g. “BufferDefault”, “BufferMinMax”, “BufferInfinite”…
  • MetaData is the abstract base class for the concrete class MetaClass and MetaCategory.

After creating an MetaClass or MetaData object it needs to be registered, typically in the initialization of the library.

Date – DateRange – TimePeriod

These classes allow easy and intuitive manipulation of dates, durations and date ranges.
The classes are implemented as a thin wrapper around the standard ansi C time functions and provides time accuracy of 1 second.

Durations are formatted according to ISO8601.

An example:

   Date start = Date::now();
   TimePeriod duration("P1D");
   Date end = d + t;
   DateRange dr(start, end);
   cout << d << "  " << t << "  " << dr << endl;

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.
This means that “midnight on day 1″ + “24 hours” will not always give you “midnight on day 2″!

Timer

This is a class to measure the excution time of the application with (at least) millisecond precision.
An example:

   Timer t;
   do_something();
   cout << "something took " << t << " seconds" << endl;
   t.restart();
   do_something_else();
   cout << "something else took " << t << " seconds" << endl;

Exception

FrePPLe uses 3 exception classes to report errors. Each of the classes inherits from std::exception.

  • A DataException is thrown when data errors are found.
    The expected handling of this error is to catch the exception and allow the execution of the program to continue.
  • A RuntimeException is thrown when the library runs into problems that are specific at runtime.
    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.
  • A LogicException is thrown when the code runs into an unhandled and unexpected situation.
    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.

XML Serialization

The Object base class provides the following methods that need to be implemented by serializable clasess:

  • The beginElement is called by the parser when reading the start of a tag.
  • The endElement event is called by the parser when reading the end of a tag or attribute.
  • The writeElement is called when serializing the object.

FrePPLe uses the SAX parser from Xerces-C to parse and validate input XML data.
The class XMLInput is a wrapper around the parser. It receives the SAX events and makes the appropriate calls to the frePPLe objects.
Subclasses are available to parse a file or a string.

Writing XML output is done with the XMLOutput class which provides methods to write a header, elements and attributes. Subclasses are available to write to a file or a string.

Python binding

All frePPLe C++ objects are inheriting the Python C-API, and can thus be manipulated efficiently and elegantly from Python code. A couple of utility classes are available to simplify the use of the Python C-API in the frePPLe C++ code.

  • The PythonObject class handles two-way translation between the data types between C++ and Python.
  • The template class PythonExtension is used to define Python extensions.
  • The PythonType class is a wrapper around the type information in Python.
  • The PythonInterpreter class maintains the Python interpreter.

Command

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.

The CommandList class works as a wrapper for a collection of other commands, following the classic composite design pattern.
This allows command hierarchies to be constructed, which can be executed in sequence or in parallel.

Mutex

Working with frePPLe in a multithreaded environment requires special control over concurrent access to the objects in memory.

  • Mutex allows exclusive access to a object.
    Depending on your platform it is implement as a thin wrapper around a Windows critical_section or as pthread pthread_mutex_t.
  • ScopeMutexLock is a convenience class that makes it easy (and exception-safe) to lock a mutex in a scope.
  • The CommandList (described above) has the capability to execute commands in parallel by spawning seperate threads.

HasName and Tree

The classes represent classes which use a std::string / name as a unique identifier.
The Tree class is implemented as a red-black binary tree, using HasName objects as the nodes (i.e. intrusive container).

HasHierarchy

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.

Leveled

The model classes Operation, Buffer, Resource, Load and Flow are the key objects that are used to represent the network.
The first three represent the actual entities, while Load and Flow represent associations/links between the entities.
See the section Cluster and level algorithm for the details.

    • Getting started
    • Modeling guide
      • Simplified domain model
      • Detailed domain model
      • Environment variables
      • Python interpreter
      • Global parameters
      • Buffer
      • Calendar
      • Customer
      • Demand
      • Flow
      • Item
      • Load
      • Location
      • Operation
      • Suboperation
      • Operationplan
      • Problem
      • Resource
      • SetupMatrix
      • Skill
      • Resource skill
      • Solver
      • Extension modules
        • Forecast module
        • REST web service module
        • Linear programming solver module
        • OpenERP connector module
    • User guide
      • Main features
      • Supported browsers
      • Getting around
        • Logging in
        • Logging out
        • Changing password
        • Navigation
          • Menu bar
          • Jump search
          • Context menus
          • Browser bookmarks
        • Filtering data
        • Sorting data
        • Selecting time buckets
        • Exporting data
        • Importing data
        • User preferences
        • User permissions and roles
      • Screens
        • Data input
        • Supply Path / Where Used
        • Comments
        • History – Audit trail
        • Plan analysis
          • Problem report
          • Constraint report
          • Inventory report
          • Inventory detail report
          • Resource report
          • Resource Gantt report
          • Resource detail report
          • Operation report
          • Operation detail report
          • Demand report
          • Demand detail report
          • Demand Gantt report
          • Forecast report
          • Performance indicator report
        • Execute
      • Batch commands
        • manage.py (manage.exe on Windows)
        • frepple (frepple.exe on Windows)
        • freppleservice.exe (Windows only)
    • Installation guide
      • Windows installer
      • Compiling on Windows
      • Linux binary packages
      • Compiling on Linux
      • Compiling on debian-based linux
      • Compiling on Red Hat based Linux
      • Compiling from the subversion source code repository
      • Running the VMWare virtual machine
      • Other platforms
      • Configuring the user interface
      • Configuring multiple models in the user interface
      • Configuring as a Python extension module
    • FAQ
    • Developer guide
      • Code structure
      • Class diagram
      • Solver
        • Solver features
        • Planning algorithm
          • Top level loop
          • Demand solver
          • Buffer solver
          • Flow solver
          • Load solver
          • Operation solver
          • Resource solver
        • Cluster and level algorithm
      • Extension modules
      • Version control
      • Style guide
      • Portability
      • Security
      • Internationalization
      • Translating the user interface
      • Adding or customizing a report
      • Unit tests
        • buffer_procure_1
        • calendar
        • callback
        • cluster
        • constraints_combined_1
        • constraints_combined_2
        • constraints_leadtime_1
        • constraints_material_1
        • constraints_material_2
        • constraints_material_3
        • constraints_material_4
        • constraints_resource_1
        • constraints_resource_2
        • constraints_resource_3
        • constraints_resource_4
        • constraints_resource_5
        • datetime
        • deletion
        • demand_policy
        • flow_alternate_1
        • flow_alternate_2
        • flow_effective
        • forecast_1
        • forecast_2
        • forecast_3
        • forecast_4
        • forecast_5
        • forecast_6
        • jobshop
        • load_alternate
        • load_effective
        • lpsolver_1
        • multithreading
        • name
        • operation_alternate
        • operation_available
        • operation_effective
        • operation_pre_post
        • operation_routing
        • pegging
        • problems
        • python_1
        • python_2
        • python_3
        • safety_stock
        • sample_module
        • scalability_1
        • scalability_2
        • scalability_3
        • setup_1
        • setup_2
        • skill
        • xml
        • xml_remote
    • License
      • GNU Affero General Public License
      • GNU Free Documentation License
    • Third party add-ons
  • Copyright © 2010-2013 frePPLe bvba