BaseFactory.hh

/* This file is part of the BIAS library (Basic ImageAlgorithmS).

   Copyright (C) 2003-2009    (see file CONTACT for details)
   Multimediale Systeme der Informationsverarbeitung
   Institut fuer Informatik
   Christian-Albrechts-Universitaet Kiel
   
   
   BIAS is free software; you can redistribute it and/or modify
   it under the terms of the GNU Lesser General Public License as published by
   the Free Software Foundation; either version 2.1 of the License, or
   (at your option) any later version.
   
   BIAS 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 Lesser General Public License for more details.
   
   You should have received a copy of the GNU Lesser General Public License
   along with BIAS; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
#ifndef __BaseFactory_hh__
#define __BaseFactory_hh__

#include <bias_config.h>

#include <Base/Common/FileHandling.hh>
#include <Base/Common/Singleton.hh>
#include <Base/Debug/Debug.hh>
#include <Base/Debug/LogFacility.hh>

#include <cstring>
#include <vector>
#include <map>
#include <algorithm>
#ifndef WIN32
#  include <stdio.h>
#  include <sys/types.h>
#  include <dirent.h>
#  include <dlfcn.h>
#endif

// #ifdef WIN32
// #include <Shlwapi.h> // for PathAppend()
// #endif

namespace BIAS {

  template<class BaseClassType, class TagType> class BaseFactory;

  template<class BaseClassType, class TagType> 
  std::ostream &operator<<(std::ostream& os, 
                           const BaseFactory<BaseClassType, TagType>& bf);



  /** @class BaseFactory
      @brief simple factory class designed for usage as a singleton
      
      The factory differenciates between being used in a context 
      with dynamic libraries (*.so / *.dll) and being used in a static
      library context (*.a / *.a).
      
      In a dynamic library context, the factory looks for possible candidates 
      for creation by itself by searching certain directories. These 
      directories are set using the Add2Directories() function. Each library 
      with name lib${PREFIX}*.so / ${PREFIX}*.dll is investigated. If it 
      contains a C-style function with signature 
        Base *create();
      The associated class can be created with the factory. The create function
      is very simple and typically created by adding
      /code
      #ifdef BIAS_BUILD_SHARED_LIBS
      extern "C" TFModuleBase *create() { return new TFMSpecialModule();}
      extern "C" void destroy(TFModuleBase *p) { delete p; }
      #endif
      /endcode
      to the TFMSpecialModule.cpp file.
      
      In a static library context, the factory must be manually made aware of
      the different classes which it manages. This is typically done by 
      calling the AddType() function of the directory.

      
      Instantiate this class with the desired base class as template argument.
      The base class must provide the functions 
        - TagType BaseClassType::GetTag() const
      The instantiation will fail otherwise. Exemplary usage:

      /code 

      typedef tag_type std::string

      class Base 
      {
      public:
        Base(const tag_type& name)
          : Name_(name) {}
        void Who() { cout << "I am "<<Name_<<endl; }
        inline tag_type GetTag() const { return Name_; }
        tag_type Name_;
      };

      class A : public Base
      {
      public:
        A() : Base("a") {};
        static Base *Allocator() { return dynamic_cast<Base *>(new A); }
      };


      class B : public Base
      {
      public:
        B() : Base("b") {};
        static Base *Allocator() { return dynamic_cast<Base *>(new B); }
      };

      BaseFactory<Base, tag_type> *factory =
          FactorySingleton<Base, tag_type>::Factory.GetInstance();

      #ifdef BIAS_BUILD_SHARED_LIBS
      // Make sure class A compiles in a library libMyPrefixA.so
      // and that this library contains a C-style function similar to
      // Base *create() { return new A; }
      // The corresponding must be ensured for class B and each class
      // managed by the factory
      factory->SetPrefix("MyPrefix");
      factory->Add2Directories("directory where libMyPrefixA.so resides");
      factory->Add2Directories("directory where libMyPrefixB.so resides");
      #else
      // populate the factory (only necessary with static factories)
      factory->AddType(&A::Allocator);
      factory->AddType(&B::Allocator);
      #endif

      Base *p = factory->Generate("a");

      /endcode 

      @author woelk 10/2007 */
  template<class BaseClassType, class TagType = std::string>
  class BaseFactory
    : public Singleton<BaseFactory<BaseClassType, TagType> >,BIAS::Debug
  {
  public:
    /// typedef for function pointer to class allocator function
    typedef BaseClassType* (*AllocatorFunctionPointer)();


    static char GetSeperator() {
#ifdef WIN32
    return';';
#else
    return ':';
#endif
    }
    /// This function only makes sense when shared libraries are used:
    /// Initialize the factory with ':' (linux) or ';' (windows) separated list of directories and a 
    /// lib_prefix. All shared libraries in the given directories
    /// with names lib${lib_prefix}*.so (linux) resp.
    /// ${lib_prefix}*.dll (windows)
    /// are opened. An object can only be created when the library contains 
    /// a c-style function with the signature
    ///         BaseClass *create() 
    /// and hence all libraries not containing this symbol are neglected.
    void Add2Directories(const std::string &directories);

    /// This function only makes sense when shared libraries are used:
    /// Set the prefix used i
    void SetPrefix(const std::string &prefix);

    /** @brief function for generic class generation from
        @returns pointer to class on success, NULL on error */
    BaseClassType *Generate(const TagType& tag);

    void GetNearTag(const TagType& tag, TagType& t1, TagType& t2) const;

    /** Searches for all available modules and gives all their tag.
    @returns number of tags on success, negative value on error */
    int GetKnownTags(std::vector<TagType>& tags) const;


    /**  Get all tags and associated filenames of all modules which
     have been loaded already.
     */
    int GetLoadedFiles(std::vector<TagType>& tags,
               std::vector<std::string>& files) const;

    /** This function is only meaningfull, when static libraries are used
        @brief add a new class entry to map
        @returns 0 on success, negative value on error */
    void AddType(AllocatorFunctionPointer allocFunc);

    /** @brief empties the map, and unloads all shared libraries */
    void Clear();

    friend std::ostream &
    operator<<<>(std::ostream& os, 
                 const BaseFactory<BaseClassType, TagType>& bf);

    /// the singleton must be able to use the base factory
    friend class Singleton<BaseFactory<BaseClassType, TagType> >;
  protected:
    /// struct for storing class details in member map Map_
    struct MapEntry {
#ifdef BIAS_BUILD_SHARED_LIBS
#  ifdef WIN32
      HMODULE DllHandle;
#  else
      void *DllHandle;
#  endif
#endif
      /// pointer to the static allocator function of this class
      AllocatorFunctionPointer AllocatorFunction_;
    };

    /// tag - class allocator correspondences are stored in this map
    std::map<TagType, MapEntry> Map_;

    // also remember used files, may be usefull for somebody
    std::map<TagType, std::string> TagToFileMap_;


    /// These members are onyl meaningfull when shared libraries are used
    std::vector<std::string> Directories_;
    std::string Prefix_;
  
    /// private constructor, the factory is designed as a singleton
    BaseFactory();
    BaseFactory(const BaseFactory& b);
    BaseFactory& operator=(const BaseFactory& b); 
    /// destructor
    ~BaseFactory();

    /// @brief checks if tag is already in map
    inline bool IsInMap_(const TagType& tag) const
    { return (Map_.find(tag) != Map_.end()); }
  
    /// This function is onyl meaningfull when shared libraries are used:
    /// Search for all libraries with names lib${lib_prefix}*.so (linux) resp.
    /// ${lib_prefix}*.dll (windows)
    /// are opened. An object can only be created when the library contains 
    /// a c-style function with the signature
    ///         BaseClass *create() 
    /// and hence all libraries not containing this symbol are neglected.
    void GetKnownTags_(std::vector<TagType> &tags,
                       const std::string& directory) const;

    /// This function is onyl meaningfull when shared libraries are used:
    /// open file and store handle in DllMap
    int OpenDll_(const std::string& tag);


  }; // class BaseFactory

  /////////////////////////////////////////////////////////////////////////
  // implementation
  /////////////////////////////////////////////////////////////////////////

  template <class BaseClassType, class TagType>
  BaseFactory<BaseClassType, TagType>::
  BaseFactory()
    : Map_(), Directories_(), Prefix_()
  {}


  template <class BaseClassType, class TagType>
  BaseFactory<BaseClassType, TagType>::
  BaseFactory(const BaseFactory<BaseClassType, TagType>& t)
    : Map_(), Directories_(), Prefix_()
  { BIASABORT; }

  
  template <class BaseClassType, class TagType>
  BaseFactory<BaseClassType, TagType>::
  ~BaseFactory()
  { Clear();
  }


  template <class BaseClassType, class TagType>
  BaseFactory<BaseClassType, TagType>& BaseFactory<BaseClassType, TagType>::
  operator=(const BaseFactory<BaseClassType, TagType>& t)
  { BIASABORT; return *this; }


  template <class BaseClassType, class TagType>
  void BaseFactory<BaseClassType, TagType>::
  Add2Directories(const std::string &directories)
  {
#ifdef BIAS_BUILD_SHARED_LIBS
    char seperator;
#ifdef WIN32
    seperator = ';';
#else
    seperator = ':';
#endif
    std::string::size_type pos = 0;
    std::string::size_type offset = 0;
    std::string directory;
    while ( (pos = directories.find(seperator, offset)) != std::string::npos){
      directory = directories.substr(offset, pos-offset);
      Directories_.push_back(directory);
      offset = pos+1;
    }
    directory = directories.substr(offset, directories.length()-offset);
    Directories_.push_back(directory);
#endif
  }
  

  template <class BaseClassType, class TagType>
  void BaseFactory<BaseClassType, TagType>::
  SetPrefix(const std::string &prefix)
  {
#ifdef BIAS_BUILD_SHARED_LIBS
    Prefix_ = prefix;
#endif
  }


  template <class BaseClassType, class TagType>
  BaseClassType *BaseFactory<BaseClassType, TagType>::
  Generate(const TagType& tag)
  {
    BaseClassType *(*CreateFunc)() = NULL;
    typename std::map<TagType, MapEntry>::const_iterator it;
    it = Map_.find(tag);
#ifdef BIAS_BUILD_SHARED_LIBS
    if (it == Map_.end()) {
      if (OpenDll_(tag) < 0) {
        return NULL;
      }
    }
    CreateFunc = Map_[tag].AllocatorFunction_;
#else
    if (it != Map_.end()){
      CreateFunc = it->second.AllocatorFunction_;
    } else {
      BLF("failed to load static library for tag \""<<tag<<"\"");
      return NULL;
    }
#endif
    BIASASSERT(CreateFunc != NULL);
    
    return CreateFunc();
  }


  template <class BaseClassType, class TagType>
  void BaseFactory<BaseClassType, TagType>::
  GetNearTag(const TagType& tag, TagType& tagupper, TagType& taglower) const
  {
//#ifdef BIAS_BUILD_SHARED_LIBS
    std::vector<TagType> tags;
    GetKnownTags(tags);
    // insert searched tag and sort again
    tags.push_back(tag);
    std::sort(tags.begin(),tags.end());
    unsigned int i=0;
    while (tags[i] != tag && i<tags.size()) i++;
    if (i>0 && i<tags.size()) tagupper = tags[i-1];
    if (i<tags.size()) taglower = tags[i+1];
// #else
//     tagupper = taglower = tag;
//     // safety check if there is anything in the map
//     if (Map_.empty()) return;
//     typename std::map<TagType, MapEntry>::const_iterator el = Map_.find(tag);
//     if (el != Map_.end()){
//       // exact match !
//       tagupper = taglower = tag;
//     } else {
//       // init with first
//       tagupper =  Map_.begin()->first;
//       taglower =  Map_.rbegin()->first;
//       // generate element
//       Map_[tag];
//       // find neighbors
//       typename std::map<TagType, MapEntry>::const_iterator it = Map_.find(tag);
//       it++;
//       if (it != Map_.end()) taglower = it->first;
//       it--;
//       if (it != Map_.begin()) {
//         it--;
//         tagupper = it->first;
//         it++;
//       }
//       // cleanup synthetic element
//       Map_.erase(it);
//     } 
//#endif
  }


  template <class BaseClassType, class TagType>
  int BaseFactory<BaseClassType, TagType>::
  GetKnownTags(std::vector<TagType>& tags) const
  {
    tags.clear();
#ifdef BIAS_BUILD_SHARED_LIBS
    std::vector<std::string> tmp;
    typename std::vector<std::string>::const_iterator it;
    for (it = Directories_.begin(); it!=Directories_.end(); it++){
      GetKnownTags_(tmp, *it);
      tags.insert(tags.begin(), tmp.begin(), tmp.end());
    }
#else
    typename std::map<TagType, MapEntry>::const_iterator it;
    for (it=Map_.begin(); it!=Map_.end(); it++){
      tags.push_back(it->first);
    }
#endif
    std::sort(tags.begin(),tags.end());
    return (int)tags.size();
  }


  template <class BaseClassType, class TagType>
  void BaseFactory<BaseClassType, TagType>::
  AddType(AllocatorFunctionPointer allocFunc)
  {
#ifndef BIAS_BUILD_SHARED_LIBS
    BaseClassType *cl = (*allocFunc)();
    if (!cl){
      BEXCEPTION("allocator function is not working!");
    }
//  if (cl->GetTag() == FACTORY_INVALID_TAG) {
//    BEXCEPTION("can not add tag FACTORY_INVALID_TAG to factory!");
//  }
    if (IsInMap_(cl->GetTag())) {
      BEXCEPTION("tag \""<<cl->GetTag()<<"\" already exists in factory instance!");
    }
    struct MapEntry me = { allocFunc };
    Map_.insert(make_pair(cl->GetTag(), me));
    
    delete cl;
#endif
  }


  template <class BaseClassType, class TagType>
  void BaseFactory<BaseClassType, TagType>::
  Clear()
  {
#ifdef BIAS_BUILD_SHARED_LIBS
    typename std::map<TagType, MapEntry >::iterator it;
    for (it = Map_.begin(); it!= Map_.end(); it++){
#  ifdef WIN32
      if (FreeLibrary(it->second.DllHandle)!=0) {
        BLF("error unloading library \""<<it->first<<"\"!");
      }
#  else
      if (dlclose(it->second.DllHandle)!=0) {
        BLF("error unloading library \""<<it->first<<"\"!");
        BLF("-> "<<dlerror());
      }
#  endif
      BLD("unloaded library \""<<it->first<<"\"");
    }
#endif
    Map_.clear(); 
  }


  template <class BaseClassType, class TagType>
  int BaseFactory<BaseClassType, TagType>::
  OpenDll_(const std::string& tag)
  {
#ifdef BIAS_BUILD_SHARED_LIBS
    typename std::vector<std::string>::const_iterator it;
    std::string filename;
    MapEntry NewModule;
    NewModule.DllHandle = NULL;
    std::string postfix;
#  ifdef WIN32
#    ifdef COMPILE_NDEBUG
    postfix = ".dll";
#    else //COMPILE_NDEBUG
    postfix = "D.dll";
#    endif //COMPILE_NDEBUG
#  else
#    ifdef __APPLE__
#      ifdef COMPILE_NDEBUG
    postfix = ".dylib";
#      else //COMPILE_NDEBUG
    postfix = "D.dylib";
#      endif //COMPILE_NDEBUG
#    else // __APPLE__
#      ifdef COMPILE_NDEBUG
      postfix = ".so";
#      else //COMPILE_NDEBUG
    postfix = "D.so";
  #    endif //COMPILE_NDEBUG
#    endif // __APPLE__
#  endif
    for (it = Directories_.begin(); it!=Directories_.end(); it++) {
        filename = *it + "/" + Prefix_ + tag + postfix;
#  ifdef WIN32
      NewModule.DllHandle = LoadLibrary(filename.c_str());
#  else  
      NewModule.DllHandle = dlopen(filename.c_str(),RTLD_NOW);
#  endif
      if (NewModule.DllHandle != NULL) {
        //BLD("loaded library \""<<filename<<"\"");
        break;
      } else {
        BLF("failed to load library \""<<filename<<"\"!");
#  ifndef WIN32
        BLF("-> "<<dlerror());
#  endif
      }
    }
    if (!NewModule.DllHandle){
      BLD("failed to load library \""<<Prefix_+tag+postfix<<"\" from :");
      for (unsigned i=0; i<Directories_.size(); i++)
        BLD("  "<< Directories_[i]);
      return -1;
    }

    std::string CreateSym;
#  ifdef WIN32
    // C++-function name are exported decorated in dll, so use C-style create only
    CreateSym = "create";
    NewModule.AllocatorFunction_ = 
      (AllocatorFunctionPointer)GetProcAddress(NewModule.DllHandle, CreateSym.c_str());
#  else
    CreateSym = "create";
    // evil, evil, evil,...
    void *damnedvoidpointer = dlsym(NewModule.DllHandle,CreateSym.c_str());
    memcpy(&(NewModule.AllocatorFunction_), &damnedvoidpointer,sizeof(damnedvoidpointer));

    //  NewModule.AllocatorFunction_ = (create_t*)damnedvoidpointer;
    //  NewModule.AllocatorFunction_ = (create_t*)dlsym(NewModule.DllHandle,
    //                                            CreateSym.c_str());
#  endif
    if (NewModule.AllocatorFunction_ == NULL) {
      BLF("can not find symbol \""<<CreateSym<<"\" in file \""<<filename<<"\"");
      return -2;
    } else {
      BLD("loaded library \""<<filename<<"\"");
      TagToFileMap_[tag] = filename;
    }

    // store pointer to dll and to Create() in map
    Map_[tag] = NewModule;
#endif
    return 0;
  }

  template <class BaseClassType, class TagType>
  void BaseFactory<BaseClassType, TagType>::
  GetKnownTags_(std::vector<TagType> &tags, const std::string& directory) const
  {
#ifdef BIAS_BUILD_SHARED_LIBS
    tags.clear();
    std::string filename;
    
#  ifdef WIN32
    std::string postfix;
#  ifdef COMPILE_NDEBUG
    postfix = ".dll";
#  else //COMPILE_NDEBUG
    postfix = "D.dll";
#  endif //COMPILE_NDEBUG

    std::string tmp = directory + "/"+Prefix_+"*"+postfix;

    TCHAR searchPath[MAX_PATH];
    // a wildcard needs to be added to the end of the path, e.g. "C:\*"
    lstrcpy(searchPath, tmp.c_str());
    // defined in shell lightweight API (v4.71)
    //   PathAppend(searchPath, "*"); 

    WIN32_FIND_DATA ffd; // file information struct
    HANDLE sh = FindFirstFile(searchPath, &ffd);
    if(INVALID_HANDLE_VALUE == sh) return; // not a proper path i guess
    

    const int prefix_len = (int)Prefix_.length();
    const int postfix_len = (int)postfix.length();
    // enumerate all items; NOTE: FindFirstFile has already got info for 
    // an item
    do {
      //std::cout << "Name = " << ffd.cFileName << std::endl;
      //std::cout << "Type = " 
      //          << ( (ffd.dwFileAttributes & FILE_ATTRIBUTE_DIRECTORY)
      //                            ? "dir\n" : "file\n" );
      //std::cout << "Size = " << ffd.nFileSizeLow << std::endl;
      filename = ffd.cFileName;
      int l = (int)filename.length();
      if (filename.substr(0,prefix_len) == Prefix_ 
          && filename.substr(l-postfix_len) == postfix) {
        filename = filename.substr(prefix_len,l-postfix_len-prefix_len);
        tags.push_back(filename);
      }
    } while (FindNextFile(sh, &ffd));
    
    FindClose(sh);
#  else
    std::string postfix;
#  ifdef COMPILE_NDEBUG
    postfix = ".so";
#  else //COMPILE_NDEBUG
    postfix = "D.so";
#  endif //COMPILE_NDEBUG

    DIR *dp;
    struct dirent *ep;
    dp = opendir (directory.c_str());
    if (dp == NULL) {
      perror (directory.c_str());
      return ;
    }
    while ( (ep = readdir (dp)) != NULL) {
      filename = ep->d_name;
      int l = filename.length();
      const int prefix_lenth = Prefix_.length();
      const int postfix_len = postfix.length();
      if (filename.substr(0,prefix_lenth) == Prefix_ 
          && filename.substr(l-postfix_len) ==postfix) {
        filename = filename.substr(prefix_lenth,l-prefix_lenth-postfix_len);
        tags.push_back(filename);
      }
    }
    (void) closedir (dp);
#  endif
    std::sort(tags.begin(),tags.end());
#endif
  }




  template <class BaseClassType, class TagType>
  int BaseFactory<BaseClassType, TagType>::
  GetLoadedFiles(std::vector<TagType>& tags, std::vector<std::string>& files) const
  {
    files.clear();
    tags.clear();
    typename std::map<TagType,std::string>::const_iterator it;
    it = TagToFileMap_.begin();
    while(it !=TagToFileMap_.end()) {
      tags.push_back(it->first);
      files.push_back(it->second);
      it++;
    }
    return (int)files.size();
  }





  ///////////////////////////////////////////////////////////////
  // iostream
  ///////////////////////////////////////////////////////////////

  template <class BaseClassType, class TagType>
  std::ostream &
  operator<<(std::ostream& os, 
             const BaseFactory<BaseClassType, TagType>& bf)
  {
    typename std::map<TagType, 
      typename BaseFactory<BaseClassType, TagType>::MapEntry>::
      const_iterator it;
    for (it=bf.Map_.begin(); it!=bf.Map_.end(); it++){
      os <<"tag :"<<(it->first)<<std::endl;
    }
    return os;
  }
} // namespace

#endif // __BaseFactory_hh__