frePPLeOpen source Production Planning
  • Home
  • Documentation
  • C++ API

Code structure

This chapter provides a high level description of the C++ 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 execution 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
      • 1 – Introduction
      • 2 – Installation
      • 3 – Entering data
      • 4 – Modelling concepts
      • 5 – Your first model
      • 6 – Your first plan
    • 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
    • User guide
      • Supported browsers
      • Getting around
        • Logging in
        • Logging out
        • Changing password
        • Navigation
          • Menu bar
          • Jump search
          • Context menus
        • Filtering data
        • Sorting data
        • Selecting time buckets
        • Exporting data
        • Importing data
        • Customizing a screen
        • User preferences
        • User permissions and roles
        • Comments
        • History – Audit trail
      • Data maintenance screens
      • Supply Path / Where Used
      • Plan analysis screens
        • 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
      • Execution screen
      • Batch commands
        • frepplectl
        • frepple
        • freppleservice.exe (Windows only)
    • Installation guide
      • Windows installer
      • Compiling on Windows
      • Linux binary packages
      • Compiling on Linux
      • Compiling from the source code repository
      • Running the VMWare virtual machine
      • Other platforms
      • Configuring multiple models in the user interface
      • Configuring as a Python extension module
    • Extension modules
      • Forecast module
      • Order quoting module
      • REST web service module
      • OpenERP connector module
      • Linear programming solver module
    • Technical guide
      • Architecture
      • Source code repository
      • User interface
        • Creating an extension app
        • Translating the user interface
        • Adding or customizing a report
        • Style guide
      • Solver engine
        • Code structure
        • Class diagram
        • Planning algorithm
          • Top level loop
          • Demand solver
          • Buffer solver
          • Flow solver
          • Load solver
          • Operation solver
          • Resource solver
        • Cluster and level algorithm
        • Extension modules
        • Style guide
        • Portability
      • Security
      • 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
    • FAQ
    • License
      • GNU Affero General Public License
      • GNU Free Documentation License
    • Third party add-ons
  • Copyright © 2010-2013 frePPLe bvba