inference-engine/include/ie_iinfer_request.hpp

   1 // Copyright (C) 2018-2019 Intel Corporation
   2 // SPDX-License-Identifier: Apache-2.0
   3 //
   4
   5 /**
   6  * @brief a header file for IInferRequest interface
   7  * @file ie_iinfer_request.hpp
   8  */
   9
  10 #pragma once
  11
  12 #include "ie_common.h"
  13 #include <ie_blob.h>
  14 #include <memory>
  15 #include <string>
  16 #include <map>
  17 #include <details/ie_irelease.hpp>
  18
  19 namespace InferenceEngine {
  20
  21 /**
  22  * @brief This is an interface of asynchronous infer request
  23  */
  24 class IInferRequest : public details::IRelease {
  25 public:
  26     /**
  27      * @enum WaitMode
  28      * @brief Enumeration to hold wait mode for IInferRequest
  29      */
  30     enum WaitMode : int64_t {
  31         /** Wait until inference result becomes available */
  32         RESULT_READY = -1,
  33         /** IInferRequest doesn't block or interrupt current thread and immediately returns inference status */
  34         STATUS_ONLY = 0,
  35     };
  36
  37     using Ptr = std::shared_ptr<IInferRequest>;
  38     using WeakPtr = std::weak_ptr<IInferRequest>;
  39
  40     /**
  41      * @brief Sets input/output data to infer
  42      * @note: Memory allocation does not happen
  43      * @param name Name of input or output blob.
  44      * @param data Reference to input or output blob. The type of a blob must match the network input precision and size.
  45      * @param resp Optional: pointer to an already allocated object to contain information in case of failure
  46      * @return Status code of the operation: OK (0) for success
  47      */
  48     virtual StatusCode SetBlob(const char *name, const Blob::Ptr &data, ResponseDesc *resp) noexcept = 0;
  49
  50     /**
  51      * @brief Gets input/output data for inference
  52      * @note: Memory allocation does not happen
  53      * @param name Name of input or output blob.
  54      * @param data Reference to input or output blob. The type of Blob must match the network input precision and size.
  55      * @param resp Optional: pointer to an already allocated object to contain information in case of failure
  56      * @return Status code of the operation: OK (0) for success
  57      */
  58     virtual StatusCode GetBlob(const char *name, Blob::Ptr &data, ResponseDesc *resp) noexcept = 0;
  59
  60     /**
  61      * @brief Infers specified input(s) in synchronous mode
  62      * @note blocks all methods of IInferRequest while request is ongoing (running or waiting in queue)
  63      * @param resp Optional: pointer to an already allocated object to contain information in case of failure
  64      * @return Status code of the operation: OK (0) for success
  65      */
  66     virtual StatusCode Infer(ResponseDesc *resp) noexcept = 0;
  67
  68     /**
  69      * @brief Queries performance measures per layer to get feedback of what is the most time consuming layer
  70      * @note: not all plugins provide meaningful data
  71      * @param perfMap Map of layer names to profiling information for that layer
  72      * @param resp Optional: pointer to an already allocated object to contain information in case of failure
  73      * @return Status code of the operation: OK (0) for success
  74      */
  75     virtual StatusCode GetPerformanceCounts(std::map<std::string, InferenceEngineProfileInfo> &perfMap,
  76                                             ResponseDesc *resp) const noexcept = 0;
  77
  78     /**
  79      * @brief Waits for the result to become available. Blocks until specified millis_timeout has elapsed or the result becomes available, whichever comes first.
  80      * @param millis_timeout Maximum duration in milliseconds to block for
  81      * @note There are special cases when millis_timeout is equal some value of the WaitMode enum:
  82      * * STATUS_ONLY - immediately returns inference status (IInferRequest::RequestStatus). It does not block or interrupt current thread
  83      * * RESULT_READY - waits until inference result becomes available
  84      * @param resp Optional: a pointer to an already allocated object to contain extra information of a failure (if occurred)
  85      * @return Enumeration of the resulted action: OK (0) for success
  86      */
  87     virtual InferenceEngine::StatusCode Wait(int64_t millis_timeout, ResponseDesc *resp) noexcept = 0;
  88
  89     /**
  90      * @brief Starts inference of specified input(s) in asynchronous mode
  91      * @note: It returns immediately. Inference starts also immediately
  92      * @param resp Optional: a pointer to an already allocated object to contain extra information of a failure (if occurred)
  93      * @return Enumeration of the resulted action: OK (0) for success
  94      */
  95     virtual StatusCode StartAsync(ResponseDesc *resp) noexcept = 0;
  96
  97     /**
  98      * @brief Completion callback definition as pointer to a function
  99      * @param context Pointer to request for providing context inside callback
 100      * @param code Completion result status: OK (0) for success
 101      */
 102     typedef void (*CompletionCallback)(InferenceEngine::IInferRequest::Ptr context,
 103                                        InferenceEngine::StatusCode code);
 104
 105     /**
 106      * @brief Sets a callback function that will be called on success or failure of asynchronous request
 107      * @param callback A function to be called
 108      * @return Enumeration of the resulted action: OK (0) for success
 109      */
 110     virtual StatusCode SetCompletionCallback(CompletionCallback callback) noexcept = 0;
 111
 112     /**
 113      * @brief Gets arbitrary data for the request and stores a pointer to a pointer to the obtained data
 114      * @param data Pointer to a pointer to the gotten arbitrary data
 115      * @param resp Optional: a pointer to an already allocated object to contain extra information of a failure (if occurred)
 116      * @return Enumeration of the resulted action: OK (0) for success
 117      */
 118     virtual StatusCode GetUserData(void **data, ResponseDesc *resp) noexcept = 0;
 119
 120     /**
 121      * @brief Sets arbitrary data for the request
 122      * @param data Pointer to a pointer to arbitrary data to set
 123      * @param resp Optional: a pointer to an already allocated object to contain extra information of a failure (if occurred)
 124      * @return Enumeration of the resulted action: OK (0) for success
 125      */
 126     virtual StatusCode SetUserData(void *data, ResponseDesc *resp) noexcept = 0;
 127
 128     /**
 129     * @brief Sets new batch size when dynamic batching is enabled in executable network that created this request.
 130     * @param batch_size new batch size to be used by all the following inference calls for this request.
 131     * @param resp Optional: a pointer to an already allocated object to contain extra information of a failure (if occurred)
 132     * @return Enumeration of the resulted action: OK (0) for success
 133     */
 134     virtual InferenceEngine::StatusCode SetBatch(int batch_size, ResponseDesc *resp) noexcept = 0;
 135 };
 136
 137 }  // namespace InferenceEngine