include/tbb/runtime_loader.h

   1 /*
   2     Copyright (c) 2005-2019 Intel Corporation
   3
   4     Licensed under the Apache License, Version 2.0 (the "License");
   5     you may not use this file except in compliance with the License.
   6     You may obtain a copy of the License at
   7
   8         http://www.apache.org/licenses/LICENSE-2.0
   9
  10     Unless required by applicable law or agreed to in writing, software
  11     distributed under the License is distributed on an "AS IS" BASIS,
  12     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13     See the License for the specific language governing permissions and
  14     limitations under the License.
  15 */
  16
  17 #ifndef __TBB_runtime_loader_H
  18 #define __TBB_runtime_loader_H
  19
  20 #if ! TBB_PREVIEW_RUNTIME_LOADER
  21     #error Set TBB_PREVIEW_RUNTIME_LOADER to include runtime_loader.h
  22 #endif
  23
  24 #include "tbb_stddef.h"
  25 #include <climits>
  26
  27 #if _MSC_VER
  28     #if ! __TBB_NO_IMPLICIT_LINKAGE
  29         #ifdef _DEBUG
  30             #pragma comment( linker, "/nodefaultlib:tbb_debug.lib" )
  31             #pragma comment( linker, "/defaultlib:tbbproxy_debug.lib" )
  32         #else
  33             #pragma comment( linker, "/nodefaultlib:tbb.lib" )
  34             #pragma comment( linker, "/defaultlib:tbbproxy.lib" )
  35         #endif
  36     #endif
  37 #endif
  38
  39 namespace tbb {
  40
  41 namespace interface6 {
  42
  43 //! Load TBB at runtime.
  44 /*!
  45
  46 \b Usage:
  47
  48 In source code:
  49
  50 \code
  51 #include "tbb/runtime_loader.h"
  52
  53 char const * path[] = { "<install dir>/lib/ia32", NULL };
  54 tbb::runtime_loader loader( path );
  55
  56 // Now use TBB.
  57 \endcode
  58
  59 Link with \c tbbproxy.lib (or \c libtbbproxy.a) instead of \c tbb.lib (\c libtbb.dylib,
  60 \c libtbb.so).
  61
  62 TBB library will be loaded at runtime from \c <install dir>/lib/ia32 directory.
  63
  64 \b Attention:
  65
  66 All \c runtime_loader objects (in the same module, i.e. exe or dll) share some global state.
  67 The most noticeable piece of global state is loaded TBB library.
  68 There are some implications:
  69
  70     -   Only one TBB library can be loaded per module.
  71
  72     -   If one object has already loaded TBB library, another object will not load TBB.
  73         If the loaded TBB library is suitable for the second object, both will use TBB
  74         cooperatively, otherwise the second object will report an error.
  75
  76     -   \c runtime_loader objects will not work (correctly) in parallel due to absence of
  77         synchronization.
  78
  79 */
  80
  81 class runtime_loader : tbb::internal::no_copy {
  82
  83     public:
  84
  85         //! Error mode constants.
  86         enum error_mode {
  87             em_status,     //!< Save status of operation and continue.
  88             em_throw,      //!< Throw an exception of tbb::runtime_loader::error_code type.
  89             em_abort       //!< Print message to \c stderr and call \c abort().
  90         }; // error_mode
  91
  92         //! Error codes.
  93         enum error_code {
  94             ec_ok,         //!< No errors.
  95             ec_bad_call,   //!< Invalid function call (e. g. load() called when TBB is already loaded).
  96             ec_bad_arg,    //!< Invalid argument passed.
  97             ec_bad_lib,    //!< Invalid library found (e. g. \c TBB_runtime_version symbol not found).
  98             ec_bad_ver,    //!< TBB found but version is not suitable.
  99             ec_no_lib      //!< No suitable TBB library found.
 100         }; // error_code
 101
 102         //! Initialize object but do not load TBB.
 103         runtime_loader( error_mode mode = em_abort );
 104
 105         //! Initialize object and load TBB.
 106         /*!
 107             See load() for details.
 108
 109             If error mode is \c em_status, call status() to check whether TBB was loaded or not.
 110         */
 111         runtime_loader(
 112             char const * path[],                           //!< List of directories to search TBB in.
 113             int          min_ver = TBB_INTERFACE_VERSION,  //!< Minimal suitable version of TBB.
 114             int          max_ver = INT_MAX,                //!< Maximal suitable version of TBB.
 115             error_mode   mode    = em_abort                //!< Error mode for this object.
 116         );
 117
 118         //! Destroy object.
 119         ~runtime_loader();
 120
 121         //! Load TBB.
 122         /*!
 123             The method searches the directories specified in \c path[] array for the TBB library.
 124             When the library is found, it is loaded and its version is checked. If the version is
 125             not suitable, the library is unloaded, and the search continues.
 126
 127             \b Note:
 128
 129             For security reasons, avoid using relative directory names. For example, never load
 130             TBB from current (\c "."), parent (\c "..") or any other relative directory (like
 131             \c "lib" ). Use only absolute directory names (e. g. "/usr/local/lib").
 132
 133             For the same security reasons, avoid using system default directories (\c "") on
 134             Windows. (See http://www.microsoft.com/technet/security/advisory/2269637.mspx for
 135             details.)
 136
 137             Neglecting these rules may cause your program to execute 3-rd party malicious code.
 138
 139             \b Errors:
 140                 -   \c ec_bad_call - TBB already loaded by this object.
 141                 -   \c ec_bad_arg - \p min_ver and/or \p max_ver negative or zero,
 142                     or \p min_ver > \p max_ver.
 143                 -   \c ec_bad_ver - TBB of unsuitable version already loaded by another object.
 144                 -   \c ec_no_lib - No suitable library found.
 145         */
 146         error_code
 147         load(
 148             char const * path[],                           //!< List of directories to search TBB in.
 149             int          min_ver = TBB_INTERFACE_VERSION,  //!< Minimal suitable version of TBB.
 150             int          max_ver = INT_MAX                 //!< Maximal suitable version of TBB.
 151
 152         );
 153
 154
 155         //! Report status.
 156         /*!
 157             If error mode is \c em_status, the function returns status of the last operation.
 158         */
 159         error_code status();
 160
 161     private:
 162
 163         error_mode const my_mode;
 164         error_code       my_status;
 165         bool             my_loaded;
 166
 167 }; // class runtime_loader
 168
 169 } // namespace interface6
 170
 171 using interface6::runtime_loader;
 172
 173 } // namespace tbb
 174
 175 #endif /* __TBB_runtime_loader_H */
 176