ie_core.hpp
Go to the documentation of this file.
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 Inference Engine Core class C++ API
7  *
8  * @file ie_core.hpp
9  */
10 #pragma once
11 
12 #include <map>
13 #include <memory>
14 #include <string>
15 #include <vector>
16 
17 #include "cpp/ie_plugin_cpp.hpp"
19 #include "ie_extension.h"
20 #include "ie_remote_context.hpp"
21 
22 namespace InferenceEngine {
23 
24 /**
25  * @brief This class represents Inference Engine Core entity.
26  *
27  * It can throw exceptions safely for the application, where it is properly handled.
28  */
29 class INFERENCE_ENGINE_API_CLASS(Core) {
30  class Impl;
31  std::shared_ptr<Impl> _impl;
32 
33 public:
34  /** @brief Constructs Inference Engine Core instance using XML configuration file with
35  * plugins description.
36  *
37  * See RegisterPlugins for more details.
38  *
39  * @param xmlConfigFile A path to .xml file with plugins to load from. If XML configuration file is not specified,
40  * then default Inference Engine plugins are loaded from the default plugin.xml file.
41  */
42  explicit Core(const std::string& xmlConfigFile = std::string());
43 
44  /**
45  * @brief Returns plugins version information
46  *
47  * @param deviceName Device name to indentify plugin
48  * @return A vector of versions
49  */
50  std::map<std::string, Version> GetVersions(const std::string& deviceName) const;
51 
52  /**
53  * @brief Sets logging callback
54  *
55  * Logging is used to track what is going on inside the plugins, Inference Engine library
56  *
57  * @param listener Logging sink
58  */
59  void SetLogCallback(IErrorListener& listener) const;
60 
61 #ifdef ENABLE_UNICODE_PATH_SUPPORT
62  /**
63  * @brief Reads IR xml and bin files
64  * @param modelPath path to IR file
65  * @param binPath path to bin file, if path is empty, will try to read bin file with the same name as xml and
66  * if bin file with the same name was not found, will load IR without weights.
67  * @return CNNNetwork
68  */
69  CNNNetwork ReadNetwork(const std::wstring& modelPath, const std::wstring& binPath = std::wstring()) const {
70  return ReadNetwork(details::wStringtoMBCSstringChar(modelPath), details::wStringtoMBCSstringChar(binPath));
71  }
72 #endif
73 
74  /**
75  * @brief Reads IR xml and bin files
76  * @param modelPath path to IR file
77  * @param binPath path to bin file, if path is empty, will try to read bin file with the same name as xml and
78  * if bin file with the same name was not found, will load IR without weights.
79  * @return CNNNetwork
80  */
81  CNNNetwork ReadNetwork(const std::string& modelPath, const std::string& binPath = "") const;
82  /**
83  * @brief Reads IR xml and bin (with the same name) files
84  * @param model string with IR
85  * @param weights shared pointer to constant blob with weights
86  * @return CNNNetwork
87  */
88  CNNNetwork ReadNetwork(const std::string& model, const Blob::CPtr& weights) const;
89 
90  /**
91  * @brief Creates an executable network from a network object.
92  *
93  * Users can create as many networks as they need and use
94  * them simultaneously (up to the limitation of the hardware resources)
95  *
96  * @param network CNNNetwork object acquired from CNNNetReader
97  * @param deviceName Name of device to load network to
98  * @param config Optional map of pairs: (config parameter name, config parameter value) relevant only for this load
99  * operation
100  * @return An executable network reference
101  */
102  ExecutableNetwork LoadNetwork(
103  CNNNetwork network, const std::string& deviceName,
104  const std::map<std::string, std::string>& config = std::map<std::string, std::string>());
105 
106  /**
107  * @brief Registers extension
108  * @param extension Pointer to already loaded extension
109  */
110  void AddExtension(const IExtensionPtr& extension);
111 
112  /**
113  * @brief Creates an executable network from a network object within a specified remote context.
114  * @param network CNNNetwork object acquired from CNNNetReader
115  * @param context Pointer to RemoteContext object
116  * @param deviceName Name of device to load network to
117  * @param config Optional map of pairs: (config parameter name, config parameter value) relevant only for this load
118  * operation
119  * @return An executable network reference
120  */
121  ExecutableNetwork LoadNetwork(
122  CNNNetwork network, RemoteContext::Ptr context,
123  const std::map<std::string, std::string>& config = std::map<std::string, std::string>());
124 
125  /**
126  * @brief Registers extension for the specified plugin
127  *
128  * @param extension Pointer to already loaded extension
129  * @param deviceName Device name to identify plugin to add an executable extension
130  */
131  void AddExtension(IExtensionPtr extension, const std::string& deviceName);
132 
133  /**
134  * @brief Creates an executable network from a previously exported network
135  *
136  * @param deviceName Name of device load executable network on
137  * @param modelFileName Path to the location of the exported file
138  * @param config Optional map of pairs: (config parameter name, config parameter value) relevant only for this load
139  * operation*
140  * @return An executable network reference
141  */
142  ExecutableNetwork ImportNetwork(
143  const std::string& modelFileName, const std::string& deviceName,
144  const std::map<std::string, std::string>& config = std::map<std::string, std::string>());
145 
146  /**
147  * @brief Creates an executable network from a previously exported network
148  * @param deviceName Name of device load executable network on
149  * @param networkModel network model stream
150  * @param config Optional map of pairs: (config parameter name, config parameter value) relevant only for this load
151  * operation*
152  * @return An executable network reference
153  */
154  ExecutableNetwork ImportNetwork(std::istream& networkModel, const std::string& deviceName = {},
155  const std::map<std::string, std::string>& config = {});
156 
157  /**
158  * @brief Query device if it supports specified network with specified configuration
159  *
160  * @param deviceName A name of a device to query
161  * @param network Network object to query
162  * @param config Optional map of pairs: (config parameter name, config parameter value)
163  * @return Pointer to the response message that holds a description of an error if any occurred
164  */
165  QueryNetworkResult QueryNetwork(
166  const ICNNNetwork& network, const std::string& deviceName,
167  const std::map<std::string, std::string>& config = std::map<std::string, std::string>()) const;
168 
169  /**
170  * @brief Sets configuration for device, acceptable keys can be found in ie_plugin_config.hpp
171  *
172  * @param deviceName An optinal name of a device. If device name is not specified, the config is set for all the
173  * registered devices.
174  *
175  * @param config Map of pairs: (config parameter name, config parameter value)
176  */
177  void SetConfig(const std::map<std::string, std::string>& config, const std::string& deviceName = std::string());
178 
179  /**
180  * @brief Gets configuration dedicated to device behaviour.
181  *
182  * The method is targeted to extract information which can be set via SetConfig method.
183  *
184  * @param deviceName - A name of a device to get a configuration value.
185  * @param name - value of config corresponding to config key.
186  * @return Value of config corresponding to config key.
187  */
188  Parameter GetConfig(const std::string& deviceName, const std::string& name) const;
189 
190  /**
191  * @brief Gets general runtime metric for dedicated hardware.
192  *
193  * The method is needed to request common device properties
194  * which are executable network agnostic. It can be device name, temperature, other devices-specific values.
195  *
196  * @param deviceName - A name of a device to get a metric value.
197  * @param name - metric name to request.
198  * @return Metric value corresponding to metric key.
199  */
200  Parameter GetMetric(const std::string& deviceName, const std::string& name) const;
201 
202  /**
203  * @brief Returns devices available for neural networks inference
204  *
205  * @return A vector of devices. The devices are returned as { CPU, FPGA.0, FPGA.1, MYRIAD }
206  If there more than one device of specific type, they are enumerated with .# suffix.
207  */
208  std::vector<std::string> GetAvailableDevices() const;
209 
210  /**
211  * @brief Register new device and plugin which implement this device inside Inference Engine.
212  *
213  * @param pluginName A name of plugin. Depending on platform pluginName is wrapped with shared library suffix and
214  * prefix to identify library full name
215  *
216  * @param deviceName A device name to register plugin for. If device name is not specified, then it's taken from
217  * plugin using InferenceEnginePluginPtr::GetName function
218  */
219  void RegisterPlugin(const std::string& pluginName, const std::string& deviceName);
220 
221  /**
222  * @brief Unloads previously loaded plugin with a specified name from Inference Engine
223  * The method is needed to remove plugin instance and free its resources. If plugin for a
224  * specified device has not been created before, the method throws an exception.
225  *
226  * @param deviceName Device name identifying plugin to remove from Inference Engine
227  */
228  void UnregisterPlugin(const std::string& deviceName);
229 
230  /** @brief Registers plugin to Inference Engine Core instance using XML configuration file with
231  * plugins description.
232  *
233  * XML file has the following structure:
234  *
235  * ```xml
236  * <ie>
237  * <plugins>
238  * <plugin name="" location="">
239  * <extensions>
240  * <extension location=""/>
241  * </extensions>
242  * <properties>
243  * <property key="" value=""/>
244  * </properties>
245  * </plugin>
246  * </plugins>
247  * </ie>
248  * ```
249  *
250  * - `name` identifies name of device enabled by plugin
251  * - `location` specifies absolute path to dynamic library with plugin. A path can also be relative to inference
252  * engine shared library. It allows to have common config for different systems with different configurations.
253  * - Properties are set to plugin via the `SetConfig` method.
254  * - Extensions are set to plugin via the `AddExtension` method.
255  *
256  * @param xmlConfigFile A path to .xml file with plugins to register.
257  */
258  void RegisterPlugins(const std::string& xmlConfigFile);
259 
260  /**
261  * @brief Create a new shared context object on specified accelerator device
262  * using specified plugin-specific low level device API parameters (device handle, pointer, etc.)
263  * @param deviceName Name of a device to create new shared context on.
264  * @param params Map of device-specific shared context parameters.
265  */
266  RemoteContext::Ptr CreateContext(const std::string& deviceName, const ParamMap& params);
267 
268  /**
269  * @brief Get a pointer to default(plugin-supplied) shared context object for specified accelerator device.
270  * @param deviceName - A name of a device to get create shared context from.
271  */
272  RemoteContext::Ptr GetDefaultContext(const std::string& deviceName);
273 };
274 } // namespace InferenceEngine
This class represents Inference Engine Core entity.
Definition: ie_core.hpp:29
Inference Engine API.
Definition: ie_argmax_layer.hpp:15
This is a header file for the IE RemoteContext and RemoteBlob classes.
std::shared_ptr< const Blob > CPtr
A smart pointer to the const Blob object.
Definition: ie_blob.h:47
This is the main interface to describe the NN topology.
Definition: ie_icnn_network.hpp:42
wrapper over IExecutableNetwork
Definition: ie_executable_network.hpp:30
This class contains all the information about the Neural Network and the related binary information...
Definition: ie_cnn_network.h:38
std::map< std::string, Parameter > ParamMap
An std::map object containing low-level object parameters of classes that are derived from RemoteBlob...
Definition: ie_remote_context.hpp:26
This is a header file with functions related to filesystem operations.
This class represents an object to work with different parameters.
Definition: ie_parameter.hpp:38
This class represents a custom error listener.
Definition: ie_error.hpp:18
This is a header file for the Inference Engine plugin C++ API.
Responce structure encapsulating information about supported layer.
Definition: ie_plugin.hpp:53
std::shared_ptr< RemoteContext > Ptr
A smart pointer to the RemoteContext object.
Definition: ie_remote_context.hpp:99
A header file that defines a wrapper class for handling extension instantiation and releasing resourc...