inference-engine/include/ie_remote_context.hpp

   1 // Copyright (C) 2018-2020 Intel Corporation
   2 // SPDX-License-Identifier: Apache-2.0
   3 //
   4
   5 /**
   6  * @brief This is a header file for the IE RemoteContext and RemoteBlob classes
   7  *
   8  * @file ie_remote_context.hpp
   9  */
  10 #pragma once
  11
  12 #include <map>
  13 #include <memory>
  14 #include <string>
  15
  16 #include "ie_blob.h"
  17 #include "ie_parameter.hpp"
  18
  19 namespace InferenceEngine {
  20 class RemoteContext;
  21
  22 /**
  23  * @brief An std::map object containing low-level object parameters
  24  * of classes that are derived from RemoteBlob or RemoteContext
  25  */
  26 using ParamMap = std::map<std::string, Parameter>;
  27 /**
  28  * @brief This class represents an Inference Engine abstraction to the memory allocated
  29  * on the remote (non-CPU) accelerator device
  30  */
  31 class RemoteBlob : public MemoryBlob {
  32 public:
  33     /**
  34      * @brief A smart pointer to the RemoteBlob object
  35      */
  36     using Ptr = std::shared_ptr<RemoteBlob>;
  37
  38     /**
  39      * @brief A smart pointer to the const RemoteBlob object
  40      */
  41     using CPtr = std::shared_ptr<const RemoteBlob>;
  42
  43     /**
  44      * @brief RemoteBlob virtual destructor
  45      */
  46     virtual ~RemoteBlob() = default;
  47
  48     /**
  49      * @brief Constructor. Creates an empty RemoteBlob object with the specified precision.
  50      * @param tensorDesc Defines the layout and dims of the blob
  51      */
  52     explicit RemoteBlob(const TensorDesc& tensorDesc): MemoryBlob(tensorDesc) {}
  53
  54     /**
  55     * @brief Returns the number of bytes per element.
  56     */
  57     size_t element_size() const noexcept override {
  58         return tensorDesc.getPrecision().size();
  59     }
  60
  61     /**
  62      * @brief Returns a map of device-specific parameters required for low-level
  63      * operations with underlying object.
  64      * Parameters include device/context/surface/buffer handles, access flags,
  65      * etc. Contents of the map returned depend on remote execution context that is
  66      * currently set on the device (working scenario).
  67      * Abstract method.
  68      * @return A map of name/parameter elements.
  69      */
  70     virtual ParamMap getParams() const = 0;
  71
  72     /**
  73      * @brief Returns name of the device on which underlying object is allocated.
  74      * Abstract method.
  75      * @return A device name string in the same format as that in plugin metric.
  76      */
  77     virtual std::string getDeviceName() const noexcept = 0;
  78
  79     /**
  80      * @brief Returns device context which underlying object belongs to.
  81      * Abstract method.
  82      * @return Pointer to plugin-specific context class object, which is derived from RemoteContext.
  83      * Dynamic casting should be used if it is necessary to retrieve a pointer to original class.
  84      */
  85     virtual std::shared_ptr<RemoteContext> getContext() const noexcept = 0;
  86 };
  87
  88 /**
  89  * @brief This class represents an Inference Engine abstraction
  90  * for remote (non-CPU) accelerator device-specific execution context.
  91  * Such context represents a scope on the device within which executable
  92  * networks and remote memory blobs can exist, function and exchange data.
  93  */
  94 class RemoteContext {
  95 public:
  96     /**
  97      * @brief A smart pointer to the RemoteContext object
  98      */
  99     using Ptr = std::shared_ptr<RemoteContext>;
 100
 101     /**
 102      * @brief A smart pointer to the const RemoteContext object
 103      */
 104     using CPtr = std::shared_ptr<const RemoteContext>;
 105
 106     /**
 107      * @brief RemoteContext virtual destructor
 108      */
 109     virtual ~RemoteContext() = default;
 110
 111     /**
 112      * @brief Checks if the RemoteContext object can be cast to the type T*
 113      *
 114      * @tparam T Type to be checked. Must represent a class derived from the RemoteContext
 115      * @return true if this object can be dynamically cast to the type T*. Otherwise, false
 116      */
 117     template <typename T,
 118         typename std::enable_if<!std::is_pointer<T>::value && !std::is_reference<T>::value, int>::type = 0,
 119         typename std::enable_if<std::is_base_of<RemoteContext, T>::value, int>::type = 0>
 120         bool is() noexcept {
 121         return dynamic_cast<T*>(this) != nullptr;
 122     }
 123
 124     /**
 125      * @brief Checks if the RemoteContext object can be cast to the type const T*
 126      *
 127      * @tparam T Type to be checked. Must represent a class derived from the RemoteContext
 128      * @return true if this object can be dynamically cast to the type const T*. Otherwise, false
 129      */
 130     template <typename T,
 131         typename std::enable_if<!std::is_pointer<T>::value && !std::is_reference<T>::value, int>::type = 0,
 132         typename std::enable_if<std::is_base_of<RemoteContext, T>::value, int>::type = 0>
 133         bool is() const noexcept {
 134         return dynamic_cast<const T*>(this) != nullptr;
 135     }
 136
 137     /**
 138      * @brief Casts this RemoteContext object to the type T*.
 139      *
 140      * @tparam T Type to cast to. Must represent a class derived from the RemoteContext
 141      * @return Raw pointer to the object of the type T or nullptr on error
 142      */
 143     template <typename T,
 144         typename std::enable_if<!std::is_pointer<T>::value && !std::is_reference<T>::value, int>::type = 0,
 145         typename std::enable_if<std::is_base_of<RemoteContext, T>::value, int>::type = 0>
 146         T * as() noexcept {
 147         return dynamic_cast<T*>(this);
 148     }
 149
 150     /**
 151      * @brief Casts this RemoteContext object to the type const T*.
 152      *
 153      * @tparam T Type to cast to. Must represent a class derived from the RemoteContext
 154      * @return Raw pointer to the object of the type const T or nullptr on error
 155      */
 156     template <typename T,
 157         typename std::enable_if<!std::is_pointer<T>::value && !std::is_reference<T>::value, int>::type = 0,
 158         typename std::enable_if<std::is_base_of<RemoteContext, T>::value, int>::type = 0>
 159         const T * as() const noexcept {
 160         return dynamic_cast<const T*>(this);
 161     }
 162
 163     /**
 164      * @brief Returns name of the device on which underlying object is allocated.
 165      * Abstract method.
 166      * @return A device name string in the same format as that in plugin metric.
 167      */
 168     virtual std::string getDeviceName() const noexcept = 0;
 169
 170     /**
 171      * @brief Allocates memory blob in device memory or wraps user-supplied memory handle
 172      * using the specified tensor description and low-level device-specific parameters.
 173      * Returns a pointer to the object which implements RemoteBlob interface.
 174      * @param tensorDesc Defines the layout and dims of the blob
 175      * @param params Map of the low-level blob object parameters.
 176      * Abstract method.
 177      * @return A pointer to plugin object that implements RemoteBlob interface.
 178      */
 179     virtual RemoteBlob::Ptr CreateBlob(const TensorDesc& tensorDesc, const ParamMap& params = {}) = 0;
 180
 181     /**
 182      * @brief Returns a map of device-specific parameters required for low-level
 183      * operations with underlying object.
 184      * Parameters include device/context handles, access flags,
 185      * etc. Contents of the map returned depend on remote execution context that is
 186      * currently set on the device (working scenario).
 187      * Abstract method.
 188      * @return A map of name/parameter elements.
 189      */
 190     virtual ParamMap getParams() const = 0;
 191 };
 192
 193 /**
 194  * @brief A wrapper of CreateBlob method of RemoteContext to keep consistency with
 195  * plugin-specific wrappers.
 196  * @param desc Defines the layout and dims of the blob
 197  * @param ctx Poniter to the plugin object derived from RemoteContext.
 198  * @return A pointer to plugin object that implements RemoteBlob interface.
 199  */
 200 inline RemoteBlob::Ptr make_shared_blob(const TensorDesc& desc, RemoteContext::Ptr ctx) {
 201     return ctx->CreateBlob(desc);
 202 }
 203
 204 }  // namespace InferenceEngine