data.h

/*
 *  Data module documentation
 *
 *  This file is part of OTAWA
 *  Copyright (c) 2016, IRIT UPS.
 *
 *  OTAWA is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  OTAWA 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 General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with OTAWA; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 */
#ifndef ELM_DATA_H_
#define ELM_DATA_H_
 
#include <elm/data/util.h>
 
namespace elm {
 
/*
 * @par custom_data Customizing the data structures
 *
 * The proposed data structure requires memory allocator, comparator or hash
 * key computation to work. As a default, they use the default implementation
 * of this features: @ref DefaultAllocator @ref Comparator or @ref HashKey.
 * Yet, ELM provides a way to customize the data structures using the
 * concept of data manager.
 *
 * A data manager groups together all facilities required to implement a data
 * structure and let the data structure user to customize its implementation.
 * There are basically three manager:
 *  * @ref EquivManager for data structures equality operations on their items,
 *  * @ref CompareManager for data structures requiring an absolute order on
 *    their items,
 *  * @ref HashManager for data structure requiring equality operations and
 *    hash value computation on their items.
 *
 *  In addition, all managers provide allocation facilities. Basically, the
 *  data structures takes a manager as template parameter. To customize a
 *  data structure, one has to pass a different manager in this template
 *  parameter. In the example below, the @ref EquivManager of the
 *  @ref Vector class is changed to use a special memory allocator:
 *  ```
 *  class MyAllocator {
 *      ...
 *  };
 *
 *  typedef EquivManager<int, Equiv<int>, MyAllocator> MyManager;
 *  Vector<int, MyManager> my_vector;
 *  ```
 *
 *  Sometimes, static nature of a manager is not enough and you need to
 *  instantiate a customized manager with a specific object:
 *  ```
 *  class MyAllocator {
 *      ...
 *  };
 *  typedef EquivManager<int, Equiv<int>, MyAllocator> MyManager;
 *
 *  MyAllocator my_allocator;
 *  MyManager my_manager(single<Equiv<int>>(), my_allocator);
 *
 *  Vector<int, MyManager> my_vector(my_manager);
 *  ```
 *
 *  @ref elm::single<T>() is used here to get a singleton instance of the given
 *  type: this prevents to clutter the memory with to many instance of a class
 *  that is actually a singleton.
 *
 *  To ensure memory minimal footprint, a manager that does not contain any data
 *  (no instance) does not take place in the data structure. To achieve this,
 *  the data structure inherits from the manager. As a consequence, when the
 *  manager contains an instance, its constructor is called each time the data
 *  structure is built passing an instance reference as constructor parameter.
 *
 *  In the example above, if we do not want to duplicate the allocators, it
 *  is required to have an implementation like below:
 *  ```
 *  class MyAllocator {
 *      ...
 *  };
 *  class MyManagerAllocator {
 *  public:
 *      MyManagerAllocator(MyAllocator& alloc): _alloc(alloc) { }
 *      MyManagerAllocator(MyManagerAllocator& a): _alloc(a._alloc) { }
 *      ...
 *  private:
 *      MyAllocator _alloc;
 *  };
 *  typedef EquivManager<int, Equiv<int>, MyManagerAllocator> MyManager;
 *
 *  MyAllocator my_allocator;
 *  MyManager my_manager(single<Equiv<int>>(), MyManagerallocator(my_allocator));
 *
 *  Vector<int, MyManager> my_vector(my_manager);
 *  ```
 */
 
namespace concept {
 
template <class T>
struct Predicate {
    bool operator()(const T& v);
};
 
template <class T, class A>
struct PredicateWithArg {
    bool operator()(const T& v, const A& a);
};
 
template <class X, class Y>
struct Function {
    typedef X x_t;
    typedef Y y_t;
    Y operator()(const X& x);
};
 
template <class X, class Y, class A>
struct FunctionWithArg {
    typedef X x_t;
    typedef Y y_t;
    Y operator()(const X& x, const A& a);
};
 
}   // concept
 
 
}   // elm
 
#endif /* ELM_DATA_H_ */