git.sesse.net Git - casparcg/blob - dependencies/tbb/include/tbb/runtime_loader.h

   1 /*
   2     Copyright 2005-2011 Intel Corporation.  All Rights Reserved.
   3
   4     This file is part of Threading Building Blocks.
   5
   6     Threading Building Blocks is free software; you can redistribute it
   7     and/or modify it under the terms of the GNU General Public License
   8     version 2 as published by the Free Software Foundation.
   9
  10     Threading Building Blocks is distributed in the hope that it will be
  11     useful, but WITHOUT ANY WARRANTY; without even the implied warranty
  12     of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13     GNU General Public License for more details.
  14
  15     You should have received a copy of the GNU General Public License
  16     along with Threading Building Blocks; if not, write to the Free Software
  17     Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  18
  19     As a special exception, you may use this file as part of a free software
  20     library without restriction.  Specifically, if other files instantiate
  21     templates or use macros or inline functions from this file, or you compile
  22     this file and link it with other files to produce an executable, this
  23     file does not by itself cause the resulting executable to be covered by
  24     the GNU General Public License.  This exception does not however
  25     invalidate any other reasons why the executable file might be covered by
  26     the GNU General Public License.
  27 */
  28
  29 #ifndef __TBB_runtime_loader_H
  30 #define __TBB_runtime_loader_H
  31
  32 #if ! TBB_PREVIEW_RUNTIME_LOADER
  33     #error Set TBB_PREVIEW_RUNTIME_LOADER to include runtime_loader.h
  34 #endif
  35
  36 #include "tbb/tbb_stddef.h"
  37 #include <climits>
  38
  39 #if _MSC_VER
  40     #if ! __TBB_NO_IMPLICIT_LINKAGE
  41         #ifdef _DEBUG
  42             #pragma comment( linker, "/nodefaultlib:tbb_debug.lib" )
  43             #pragma comment( linker, "/defaultlib:tbbproxy_debug.lib" )
  44         #else
  45             #pragma comment( linker, "/nodefaultlib:tbb.lib" )
  46             #pragma comment( linker, "/defaultlib:tbbproxy.lib" )
  47         #endif
  48     #endif
  49 #endif
  50
  51 namespace tbb {
  52
  53 namespace interface6 {
  54
  55 //! Load TBB at runtime.
  56 /*!
  57
  58 \b Usage:
  59
  60 In source code:
  61
  62 \code
  63 #include "tbb/runtime_loader.h"
  64
  65 char const * path[] = { "<install dir>/lib/ia32", NULL };
  66 tbb::runtime_loader loader( path );
  67
  68 // Now use TBB.
  69 \endcode
  70
  71 Link with \c tbbproxy.lib (or \c libtbbproxy.a) instead of \c tbb.lib (\c libtbb.dylib,
  72 \c libtbb.so).
  73
  74 TBB library will be loaded at runtime from \c <install dir>/lib/ia32 directory.
  75
  76 \b Attention:
  77
  78 All \c runtime_loader objects (in the same module, i.e. exe or dll) share some global state.
  79 The most noticeable piece of global state is loaded TBB library.
  80 There are some implications:
  81
  82     -   Only one TBB library can be loaded per module.
  83
  84     -   If one object has already loaded TBB library, another object will not load TBB.
  85         If the loaded TBB library is suitable for the second object, both will use TBB
  86         cooperatively, otherwise the second object will report an error.
  87
  88     -   \c runtime_loader objects will not work (correctly) in parallel due to absence of
  89         syncronization.
  90
  91 */
  92
  93 class runtime_loader : tbb::internal::no_copy {
  94
  95     public:
  96
  97         //! Error mode constants.
  98         enum error_mode {
  99             em_status,     //!< Save status of operation and continue.
 100             em_throw,      //!< Throw an exception of tbb::runtime_loader::error_code type.
 101             em_abort       //!< Print message to \c stderr and call \c abort().
 102         }; // error_mode
 103
 104         //! Error codes.
 105         enum error_code {
 106             ec_ok,         //!< No errors.
 107             ec_bad_call,   //!< Invalid function call (e. g. load() called when TBB is already loaded).
 108             ec_bad_arg,    //!< Invalid argument passed.
 109             ec_bad_lib,    //!< Invalid library found (e. g. \c TBB_runtime_version symbol not found).
 110             ec_bad_ver,    //!< TBB found but version is not suitable.
 111             ec_no_lib      //!< No suitable TBB library found.
 112         }; // error_code
 113
 114         //! Initialize object but do not load TBB.
 115         runtime_loader( error_mode mode = em_abort );
 116
 117         //! Initialize object and load TBB.
 118         /*!
 119             See load() for details.
 120
 121             If error mode is \c em_status, call status() to check whether TBB was loaded or not.
 122         */
 123         runtime_loader(
 124             char const * path[],                           //!< List of directories to search TBB in.
 125             int          min_ver = TBB_INTERFACE_VERSION,  //!< Minimal suitable version of TBB.
 126             int          max_ver = INT_MAX,                //!< Maximal suitable version of TBB.
 127             error_mode   mode    = em_abort                //!< Error mode for this object.
 128         );
 129
 130         //! Destroy object.
 131         ~runtime_loader();
 132
 133         //! Load TBB.
 134         /*!
 135             The method searches the directories specified in \c path[] array for the TBB library.
 136             When the library is found, it is loaded and its version is checked. If the version is
 137             not suitable, the library is unloaded, and the search continues.
 138
 139             \b Note:
 140
 141             For security reasons, avoid using relative directory names. For example, never load
 142             TBB from current (\c "."), parent (\c "..") or any other relative directory (like
 143             \c "lib" ). Use only absolute directory names (e. g. "/usr/local/lib").
 144
 145             For the same security reasons, avoid using system default directories (\c "") on
 146             Windows. (See http://www.microsoft.com/technet/security/advisory/2269637.mspx for
 147             details.)
 148
 149             Neglecting these rules may cause your program to execute 3-rd party malicious code.
 150
 151             \b Errors:
 152                 -   \c ec_bad_call - TBB already loaded by this object.
 153                 -   \c ec_bad_arg - \p min_ver and/or \p max_ver negative or zero,
 154                     or \p min_ver > \p max_ver.
 155                 -   \c ec_bad_ver - TBB of unsuitable version already loaded by another object.
 156                 -   \c ec_no_lib - No suitable library found.
 157         */
 158         error_code
 159         load(
 160             char const * path[],                           //!< List of directories to search TBB in.
 161             int          min_ver = TBB_INTERFACE_VERSION,  //!< Minimal suitable version of TBB.
 162             int          max_ver = INT_MAX                 //!< Maximal suitable version of TBB.
 163
 164         );
 165
 166
 167         //! Report status.
 168         /*!
 169             If error mode is \c em_status, the function returns status of the last operation.
 170         */
 171         error_code status();
 172
 173     private:
 174
 175         error_mode const my_mode;
 176         error_code       my_status;
 177         bool             my_loaded;
 178
 179 }; // class runtime_loader
 180
 181 } // namespace interface6
 182
 183 using interface6::runtime_loader;
 184
 185 } // namespace tbb
 186
 187 #endif /* __TBB_runtime_loader_H */
 188