Cyber: notes from poco and bugfix for SharedLibrary d'ctor

cyber/class_loader/shared_library/exceptions.h

@@ -17,21 +17,22 @@
 #ifndef CYBER_CLASS_LOADER_SHARED_LIBRARY_EXCEPTIONS_H_
 #define CYBER_CLASS_LOADER_SHARED_LIBRARY_EXCEPTIONS_H_
 
-#include <string>
 #include <stdexcept>
+#include <string>
 
 namespace apollo {
 namespace cyber {
 namespace class_loader {
 
-#define DECLARE_SHARED_LIBRARY_EXCEPTION(CLS, BASE) \
-class CLS : public BASE {                           \
- public:                                            \
-  explicit CLS(const std::string& err_msg) : BASE(err_msg) {} \
-  ~CLS() throw() {}                                       \
-};
+#define DECLARE_SHARED_LIBRARY_EXCEPTION(CLS, BASE)             \
+  class CLS : public BASE {                                     \
+   public:                                                      \
+    explicit CLS(const std::string& err_msg) : BASE(err_msg) {} \
+    ~CLS() throw() {}                                           \
+  };
 
-DECLARE_SHARED_LIBRARY_EXCEPTION(LibraryAlreadyLoadedException, std::runtime_error);
+DECLARE_SHARED_LIBRARY_EXCEPTION(LibraryAlreadyLoadedException,
+                                 std::runtime_error);
 DECLARE_SHARED_LIBRARY_EXCEPTION(LibraryLoadException, std::runtime_error);
 DECLARE_SHARED_LIBRARY_EXCEPTION(SymbolNotFoundException, std::runtime_error);
 

cyber/class_loader/shared_library/shared_library.cc

@@ -13,7 +13,14 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  *****************************************************************************/
-
+//
+// Adapted from poco/Foundation/src/SharedLibrary_UNIX.cpp
+//
+// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
+// and Contributors.
+//
+// SPDX-License-Identifier:	BSL-1.0
+//
 #include "cyber/class_loader/shared_library/shared_library.h"
 
 #include <dlfcn.h>
@@ -22,19 +29,13 @@ namespace apollo {
 namespace cyber {
 namespace class_loader {
 
-SharedLibrary::SharedLibrary() : handle_(nullptr) {}
-
-SharedLibrary::SharedLibrary(const std::string& path) {
-  Load(path, 0);
-}
+SharedLibrary::SharedLibrary(const std::string& path) { Load(path, 0); }
 
 SharedLibrary::SharedLibrary(const std::string& path, int flags) {
   Load(path, flags);
 }
 
-void SharedLibrary::Load(const std::string& path) {
-  Load(path, 0);
-}
+void SharedLibrary::Load(const std::string& path) { Load(path, 0); }
 
 void SharedLibrary::Load(const std::string& path, int flags) {
   std::lock_guard<std::mutex> lock(mutex_);
@@ -84,11 +85,8 @@ void* SharedLibrary::GetSymbol(const std::string& name) {
   return result;
 }
 
-SharedLibrary::~SharedLibrary() {
-  Unload();
-}
-
+SharedLibrary::~SharedLibrary() {}
 
-}  // namespace shared_library
+}  // namespace class_loader
 }  // namespace cyber
 }  // namespace apollo

cyber/class_loader/shared_library/shared_library.h

@@ -13,12 +13,22 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  *****************************************************************************/
+//
+// Adapted from poco/Foundation/include/Poco/SharedLibrary.h
+//
+// Definition of the SharedLibrary class.
+//
+// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
+// and Contributors.
+//
+// SPDX-License-Identifier:     BSL-1.0
+//
+
+#ifndef CYBER_CLASS_LOADER_SHARED_LIBRARY_SHARED_LIBRARY_H_
+#define CYBER_CLASS_LOADER_SHARED_LIBRARY_SHARED_LIBRARY_H_
 
-#ifndef CYBER_CLASS_LOADER_SHARED_LIBRARY_H_
-#define CYBER_CLASS_LOADER_SHARED_LIBRARY_H_
-
-#include <string>
 #include <mutex>
+#include <string>
 
 #include "cyber/class_loader/shared_library/exceptions.h"
 
@@ -26,42 +36,84 @@ namespace apollo {
 namespace cyber {
 namespace class_loader {
 
+// The SharedLibrary class dynamically loads shared libraries at run-time.
 class SharedLibrary {
  public:
   enum Flags {
+    // On platforms that use dlopen(), use RTLD_GLOBAL. This is the default
+    // if no flags are given.
     SHLIB_GLOBAL = 1,
+
+    // On platforms that use dlopen(), use RTLD_LOCAL instead of RTLD_GLOBAL.
+    //
+    // Note that if this flag is specified, RTTI (including dynamic_cast and
+    // throw) will not work for types defined in the shared library with GCC
+    // and possibly other compilers as well. See
+    // http://gcc.gnu.org/faq.html#dso for more information.
     SHLIB_LOCAL = 2,
   };
 
-  SharedLibrary();
+  // Creates a SharedLibrary object.
+  SharedLibrary() = default;
+
+  // Destroys the SharedLibrary. The actual library
+  // remains loaded.
+  virtual ~SharedLibrary();
 
+  // Creates a SharedLibrary object and loads a library
+  // from the given path.
   explicit SharedLibrary(const std::string& path);
 
+  // Creates a SharedLibrary object and loads a library
+  // from the given path, using the given flags.
+  // See the Flags enumeration for valid values.
   SharedLibrary(const std::string& path, int flags);
 
-  virtual ~SharedLibrary();
-
+ public:
+  // Loads a shared library from the given path.
+  // Throws a LibraryAlreadyLoadedException if
+  // a library has already been loaded.
+  // Throws a LibraryLoadException if the library
+  // cannot be loaded.
   void Load(const std::string& path);
 
+  // Loads a shared library from the given path,
+  // using the given flags. See the Flags enumeration
+  // for valid values.
+  // Throws a LibraryAlreadyLoadedException if
+  // a library has already been loaded.
+  // Throws a LibraryLoadException if the library
+  // cannot be loaded.
   void Load(const std::string& path, int flags);
 
+  // Unloads a shared library.
   void Unload();
 
+  // Returns true iff a library has been loaded.
   bool IsLoaded();
 
+  // Returns true iff the loaded library contains
+  // a symbol with the given name.
   bool HasSymbol(const std::string& name);
 
+  // Returns the address of the symbol with
+  // the given name. For functions, this
+  // is the entry point of the function.
+  // Throws a SymbolNotFoundException if the
+  // symbol does not exist.
   void* GetSymbol(const std::string& name);
 
+  // Returns the path of the library, as specified in a call
+  // to load() or the constructor.
   inline const std::string& GetPath() const { return path_; }
 
+ public:
   SharedLibrary(const SharedLibrary&) = delete;
   SharedLibrary& operator=(const SharedLibrary&) = delete;
 
  private:
   void* handle_ = nullptr;
   std::string path_;
-
   std::mutex mutex_;
 };
 
@@ -69,4 +121,4 @@ class SharedLibrary {
 }  // namespace cyber
 }  // namespace apollo
 
-#endif  // CYBER_CLASS_LOADER_SHARED_LIBRARY_H_
+#endif  // CYBER_CLASS_LOADER_SHARED_LIBRARY_SHARED_LIBRARY_H_