Fawkes API  Fawkes Development Version
module.h
00001 
00002 /***************************************************************************
00003  *  module.h - representation of a module (i.e. shared object) using
00004  *             dl of glibc, applicable for Linux/FreeBSD/MacOS X systems
00005  *
00006  *  Created: Wed Aug 23 15:48:23 2006
00007  *  Copyright  2006-2011  Tim Niemueller [www.niemueller.de]
00008  *
00009  ****************************************************************************/
00010 
00011 /*  This program is free software; you can redistribute it and/or modify
00012  *  it under the terms of the GNU General Public License as published by
00013  *  the Free Software Foundation; either version 2 of the License, or
00014  *  (at your option) any later version. A runtime exception applies to
00015  *  this software (see LICENSE.GPL_WRE file mentioned below for details).
00016  *
00017  *  This program is distributed in the hope that it will be useful,
00018  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
00019  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00020  *  GNU Library General Public License for more details.
00021  *
00022  *  Read the full text in the LICENSE.GPL_WRE file in the doc directory.
00023  */
00024 
00025 #ifndef __UTILS_SYSTEM_DYNAMIC_MODULE_MODULE_H_
00026 #define __UTILS_SYSTEM_DYNAMIC_MODULE_MODULE_H_
00027 
00028 #include <core/exception.h>
00029 #include <string>
00030 
00031 namespace fawkes {
00032 
00033 
00034 class ModuleOpenException : public Exception
00035 {
00036  public:
00037   ModuleOpenException(const char *msg);
00038 };
00039 
00040 class Module {
00041  public:
00042 
00043   /** Flags for the loading process */
00044   typedef enum {
00045     MODULE_FLAGS_NONE   = 0,            /**< No flags */
00046     MODULE_FLAGS_DEFAULT= 0x000E,       /**< Default flags, these are
00047                                          *   MODULE_BIND_GLOBAL, MODULE_BIND_NOW and
00048                                          *   MODULE_BIND_DEEP. */
00049     MODULE_BIND_LAZY    = 0x0001,       /**< Perform lazy binding. Only resolve
00050                                          *   symbols as thecode that references
00051                                          *   them is executed. If the symbol
00052                                          *   is never referenced,then it is
00053                                          *   never resolved. (Lazy  binding is
00054                                          *   only performed for function
00055                                          *   references; references to variables
00056                                          *   are always immediately bound when
00057                                          *   the library is loaded.)
00058                                          */
00059     MODULE_BIND_NOW     = 0x0002,       /**< Resolve all symbols immediately when
00060                                          *   loading the library. It's the opposite
00061                                          *   of MODULE_BIND_LAZY. It shall be the
00062                                          *   the default (makes sense for the
00063                                          *   framework robotics).
00064                                          */
00065     MODULE_BIND_LOCAL   = 0x0000,       /**< Symbols defined in this library are
00066                                          *   not made available to resolve
00067                                          *   references in subsequently
00068                                          *   loaded libraries. It's the opposite
00069                                          *   of MODULE_BIND_GLOBAL. It shall be the
00070                                          *   default and MODULE_BIND_GLOBAL shall
00071                                          *   automatically override it.
00072                                          */
00073     MODULE_BIND_GLOBAL  = 0x0004,       /**< Symbols defined in this library are
00074                                          *   not made available to resolve
00075                                          *   references in subsequently
00076                                          *   loaded libraries.
00077                                          */
00078     MODULE_BIND_MASK    = 0x0003,       /**< Can be used to encode flags in a
00079                                          *   longer data field
00080                                          */
00081     MODULE_BIND_DEEP    = 0x0008,       /**< Place the lookup scope of the symbols
00082                                          *   in this library ahead of the global
00083                                          *   scope. This means that a self-contained
00084                                          *   library will use its own symbols in
00085                                          *   preference to global symbols with the
00086                                          *   same name contained in libraries that
00087                                          *   have already been loaded.
00088                                          */
00089     MODULE_NODELETE    = 0x1000         /**< Do not unload the library during
00090                                          * dlclose().  Consequently, the
00091                                          * library's static variables are not
00092                                          * reinitialized if the library is
00093                                          * reloaded with dlopen() at a later time.
00094                                          */
00095   } ModuleFlags;
00096 
00097   Module(std::string filename, ModuleFlags flags = MODULE_FLAGS_DEFAULT);
00098   virtual ~Module();
00099 
00100   virtual void          open();
00101   virtual bool          close();
00102   virtual void          ref();
00103   virtual void          unref();
00104   virtual bool          notref();
00105   virtual unsigned int  get_ref_count();
00106   virtual bool          has_symbol(const char *symbol_name);
00107   virtual void *        get_symbol(const char *symbol_name);
00108   virtual std::string   get_filename();
00109   virtual std::string   get_base_filename();
00110   virtual bool          operator==(const Module &cmod);
00111 
00112   static const char * get_file_extension();
00113 
00114  private:
00115   static const char *FILE_EXTENSION;
00116 
00117   void *       __handle;
00118   std::string  __filename;
00119   ModuleFlags  __flags;
00120   bool         __is_resident;
00121   unsigned int __ref_count;
00122 };
00123 
00124 
00125 /** Concatenation of flags.
00126  * @param flags_a flags to concatenate
00127  * @param flags_b other flags to concatenate
00128  * @return concatenated flags
00129  */
00130 inline Module::ModuleFlags operator|(const Module::ModuleFlags &flags_a,
00131                                      const Module::ModuleFlags &flags_b)
00132 {
00133   return (Module::ModuleFlags)((int)flags_a | (int)flags_b);
00134 }
00135 
00136 } // end namespace fawkes
00137 
00138 #endif