Fawkes API  Fawkes Development Version
module.h
1 
2 /***************************************************************************
3  * module.h - representation of a module (i.e. shared object) using
4  * dl of glibc, applicable for Linux/FreeBSD/MacOS X systems
5  *
6  * Created: Wed Aug 23 15:48:23 2006
7  * Copyright 2006-2011 Tim Niemueller [www.niemueller.de]
8  *
9  ****************************************************************************/
10 
11 /* This program is free software; you can redistribute it and/or modify
12  * it under the terms of the GNU General Public License as published by
13  * the Free Software Foundation; either version 2 of the License, or
14  * (at your option) any later version. A runtime exception applies to
15  * this software (see LICENSE.GPL_WRE file mentioned below for details).
16  *
17  * This program is distributed in the hope that it will be useful,
18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20  * GNU Library General Public License for more details.
21  *
22  * Read the full text in the LICENSE.GPL_WRE file in the doc directory.
23  */
24 
25 #ifndef _UTILS_SYSTEM_DYNAMIC_MODULE_MODULE_H_
26 #define _UTILS_SYSTEM_DYNAMIC_MODULE_MODULE_H_
27 
28 #include <core/exception.h>
29 
30 #include <string>
31 
32 namespace fawkes {
33 
35 {
36 public:
37  ModuleOpenException(const char *msg);
38 };
39 
40 class Module
41 {
42 public:
43  /** Flags for the loading process */
44  typedef enum {
45  MODULE_FLAGS_NONE = 0, /**< No flags */
46  MODULE_FLAGS_DEFAULT = 0x000E, /**< Default flags, these are
47  * MODULE_BIND_GLOBAL, MODULE_BIND_NOW and
48  * MODULE_BIND_DEEP. */
49  MODULE_BIND_LAZY = 0x0001, /**< Perform lazy binding. Only resolve
50  * symbols as thecode that references
51  * them is executed. If the symbol
52  * is never referenced,then it is
53  * never resolved. (Lazy binding is
54  * only performed for function
55  * references; references to variables
56  * are always immediately bound when
57  * the library is loaded.)
58  */
59  MODULE_BIND_NOW = 0x0002, /**< Resolve all symbols immediately when
60  * loading the library. It's the opposite
61  * of MODULE_BIND_LAZY. It shall be the
62  * the default (makes sense for the
63  * framework robotics).
64  */
65  MODULE_BIND_LOCAL = 0x0000, /**< Symbols defined in this library are
66  * not made available to resolve
67  * references in subsequently
68  * loaded libraries. It's the opposite
69  * of MODULE_BIND_GLOBAL. It shall be the
70  * default and MODULE_BIND_GLOBAL shall
71  * automatically override it.
72  */
73  MODULE_BIND_GLOBAL = 0x0004, /**< Symbols defined in this library are
74  * not made available to resolve
75  * references in subsequently
76  * loaded libraries.
77  */
78  MODULE_BIND_MASK = 0x0003, /**< Can be used to encode flags in a
79  * longer data field
80  */
81  MODULE_BIND_DEEP = 0x0008, /**< Place the lookup scope of the symbols
82  * in this library ahead of the global
83  * scope. This means that a self-contained
84  * library will use its own symbols in
85  * preference to global symbols with the
86  * same name contained in libraries that
87  * have already been loaded.
88  */
89  MODULE_NODELETE = 0x1000 /**< Do not unload the library during
90  * dlclose(). Consequently, the
91  * library's static variables are not
92  * reinitialized if the library is
93  * reloaded with dlopen() at a later time.
94  */
96 
97  Module(std::string filename, ModuleFlags flags = MODULE_FLAGS_DEFAULT);
98  virtual ~Module();
99 
100  virtual void open();
101  virtual bool close();
102  virtual void ref();
103  virtual void unref();
104  virtual bool notref();
105  virtual unsigned int get_ref_count();
106  virtual bool has_symbol(const char *symbol_name);
107  virtual void * get_symbol(const char *symbol_name);
108  virtual std::string get_filename();
109  virtual std::string get_base_filename();
110  virtual bool operator==(const Module &cmod);
111 
112  static const char *get_file_extension();
113 
114 private:
115  static const char *FILE_EXTENSION;
116 
117  void * handle_;
118  std::string filename_;
119  ModuleFlags flags_;
120  bool is_resident_;
121  unsigned int ref_count_;
122 };
123 
124 /** Concatenation of flags.
125  * @param flags_a flags to concatenate
126  * @param flags_b other flags to concatenate
127  * @return concatenated flags
128  */
129 inline Module::ModuleFlags
130 operator|(const Module::ModuleFlags &flags_a, const Module::ModuleFlags &flags_b)
131 {
132  return (Module::ModuleFlags)((int)flags_a | (int)flags_b);
133 }
134 
135 } // end namespace fawkes
136 
137 #endif
Base class for exceptions in Fawkes.
Definition: exception.h:36
Opening a module failed.
Definition: module.h:35
ModuleOpenException(const char *msg)
Constructor.
Definition: module.cpp:40
Dynamic module loader for Linux, FreeBSD, and MacOS X.
Definition: module.h:41
virtual std::string get_filename()
Get the full file name of the module.
Definition: module.cpp:269
virtual std::string get_base_filename()
Get the base file name of the module.
Definition: module.cpp:279
ModuleFlags
Flags for the loading process.
Definition: module.h:44
@ MODULE_BIND_NOW
Resolve all symbols immediately when loading the library.
Definition: module.h:59
@ MODULE_BIND_LAZY
Perform lazy binding.
Definition: module.h:49
@ MODULE_NODELETE
Do not unload the library during dlclose().
Definition: module.h:89
@ MODULE_BIND_LOCAL
Symbols defined in this library are not made available to resolve references in subsequently loaded l...
Definition: module.h:65
@ MODULE_BIND_MASK
Can be used to encode flags in a longer data field.
Definition: module.h:78
@ MODULE_BIND_DEEP
Place the lookup scope of the symbols in this library ahead of the global scope.
Definition: module.h:81
@ MODULE_BIND_GLOBAL
Symbols defined in this library are not made available to resolve references in subsequently loaded l...
Definition: module.h:73
@ MODULE_FLAGS_NONE
No flags.
Definition: module.h:45
@ MODULE_FLAGS_DEFAULT
Default flags, these are MODULE_BIND_GLOBAL, MODULE_BIND_NOW and MODULE_BIND_DEEP.
Definition: module.h:46
virtual void * get_symbol(const char *symbol_name)
Get a symbol from the module.
Definition: module.cpp:244
virtual void unref()
Decrease the reference count of this module.
Definition: module.cpp:175
virtual ~Module()
Destructor.
Definition: module.cpp:76
virtual unsigned int get_ref_count()
Get the reference count of this module.
Definition: module.cpp:196
virtual void ref()
Increment the reference count of this module.
Definition: module.cpp:168
virtual bool operator==(const Module &cmod)
Compare to another Module instance.
Definition: module.cpp:207
virtual void open()
Open the module.
Definition: module.cpp:86
virtual bool has_symbol(const char *symbol_name)
Check if the module has the given symbol.
Definition: module.cpp:222
virtual bool close()
Close the module.
Definition: module.cpp:147
static const char * get_file_extension()
Get file extension for dl modules.
Definition: module.cpp:260
virtual bool notref()
Check if there are no reference to this module.
Definition: module.cpp:187
Module(std::string filename, ModuleFlags flags=MODULE_FLAGS_DEFAULT)
Constructor.
Definition: module.cpp:63
Fawkes library namespace.
BlackBoard::ListenerRegisterFlag operator|(const BlackBoard::ListenerRegisterFlag &a, const BlackBoard::ListenerRegisterFlag &b)
Concatenation of register flags.
Definition: blackboard.h:251