Treelite
c_api_runtime.cc
Go to the documentation of this file.
1 
8 #include <treelite/predictor.h>
10 #include <dmlc/thread_local.h>
11 #include <string>
12 #include <cstring>
13 #include "./c_api_error.h"
14 
15 using namespace treelite;
16 
17 namespace {
18 
20 struct TreeliteRuntimeAPIThreadLocalEntry {
22  std::string ret_str;
23 };
24 
25 // thread-local store for returning strings
26 using TreeliteRuntimeAPIThreadLocalStore
27  = dmlc::ThreadLocalStore<TreeliteRuntimeAPIThreadLocalEntry>;
28 
29 } // anonymous namespace
30 
31 int TreeliteAssembleSparseBatch(const float* data,
32  const uint32_t* col_ind,
33  const size_t* row_ptr,
34  size_t num_row, size_t num_col,
35  CSRBatchHandle* out) {
36  API_BEGIN();
37  CSRBatch* batch = new CSRBatch();
38  batch->data = data;
39  batch->col_ind = col_ind;
40  batch->row_ptr = row_ptr;
41  batch->num_row = num_row;
42  batch->num_col = num_col;
43  *out = static_cast<CSRBatchHandle>(batch);
44  API_END();
45 }
46 
48  API_BEGIN();
49  delete static_cast<CSRBatch*>(handle);
50  API_END();
51 }
52 
53 int TreeliteAssembleDenseBatch(const float* data, float missing_value,
54  size_t num_row, size_t num_col,
55  DenseBatchHandle* out) {
56  API_BEGIN();
57  DenseBatch* batch = new DenseBatch();
58  batch->data = data;
59  batch->missing_value = missing_value;
60  batch->num_row = num_row;
61  batch->num_col = num_col;
62  *out = static_cast<DenseBatchHandle>(batch);
63  API_END();
64 }
65 
67  API_BEGIN();
68  delete static_cast<DenseBatch*>(handle);
69  API_END();
70 }
71 
72 int TreeliteBatchGetDimension(void* handle,
73  int batch_sparse,
74  size_t* out_num_row,
75  size_t* out_num_col) {
76  API_BEGIN();
77  if (batch_sparse) {
78  const CSRBatch* batch_ = static_cast<CSRBatch*>(handle);
79  *out_num_row = batch_->num_row;
80  *out_num_col = batch_->num_col;
81  } else {
82  const DenseBatch* batch_ = static_cast<DenseBatch*>(handle);
83  *out_num_row = batch_->num_row;
84  *out_num_col = batch_->num_col;
85  }
86  API_END();
87 }
88 
89 int TreelitePredictorLoad(const char* library_path,
90  int num_worker_thread,
91  PredictorHandle* out) {
92  API_BEGIN();
93  Predictor* predictor = new Predictor(num_worker_thread);
94  predictor->Load(library_path);
95  *out = static_cast<PredictorHandle>(predictor);
96  API_END();
97 }
98 
100  void* batch,
101  int batch_sparse,
102  int verbose,
103  int pred_margin,
104  float* out_result,
105  size_t* out_result_size) {
106  API_BEGIN();
107  Predictor* predictor_ = static_cast<Predictor*>(handle);
108  const size_t num_feature = predictor_->QueryNumFeature();
109  const std::string err_msg
110  = std::string("Too many columns (features) in the given batch. "
111  "Number of features must not exceed ")
112  + std::to_string(num_feature);
113  if (batch_sparse) {
114  const CSRBatch* batch_ = static_cast<CSRBatch*>(batch);
115  CHECK_LE(batch_->num_col, num_feature) << err_msg;
116  *out_result_size = predictor_->PredictBatch(batch_, verbose,
117  (pred_margin != 0), out_result);
118  } else {
119  const DenseBatch* batch_ = static_cast<DenseBatch*>(batch);
120  CHECK_LE(batch_->num_col, num_feature) << err_msg;
121  *out_result_size = predictor_->PredictBatch(batch_, verbose,
122  (pred_margin != 0), out_result);
123  }
124  API_END();
125 }
126 
128  union TreelitePredictorEntry* inst,
129  int pred_margin,
130  float* out_result, size_t* out_result_size) {
131  API_BEGIN();
132  Predictor* predictor_ = static_cast<Predictor*>(handle);
133  *out_result_size
134  = predictor_->PredictInst(inst, (pred_margin != 0), out_result);
135  API_END();
136 }
137 
139  void* batch,
140  int batch_sparse,
141  size_t* out) {
142  API_BEGIN();
143  const Predictor* predictor_ = static_cast<Predictor*>(handle);
144  if (batch_sparse) {
145  const CSRBatch* batch_ = static_cast<CSRBatch*>(batch);
146  *out = predictor_->QueryResultSize(batch_);
147  } else {
148  const DenseBatch* batch_ = static_cast<DenseBatch*>(batch);
149  *out = predictor_->QueryResultSize(batch_);
150  }
151  API_END();
152 }
153 
155  size_t* out) {
156  API_BEGIN();
157  const Predictor* predictor_ = static_cast<Predictor*>(handle);
158  *out = predictor_->QueryResultSizeSingleInst();
159  API_END();
160 }
161 
163  API_BEGIN();
164  const Predictor* predictor_ = static_cast<Predictor*>(handle);
165  *out = predictor_->QueryNumOutputGroup();
166  API_END();
167 }
168 
170  API_BEGIN();
171  const Predictor* predictor_ = static_cast<Predictor*>(handle);
172  *out = predictor_->QueryNumFeature();
173  API_END();
174 }
175 
177  API_BEGIN()
178  const Predictor* predictor_ = static_cast<Predictor*>(handle);
179  auto pred_transform = predictor_->QueryPredTransform();
180  std::string& ret_str = TreeliteRuntimeAPIThreadLocalStore::Get()->ret_str;
181  ret_str = pred_transform;
182  *out = ret_str.c_str();
183  API_END();
184 }
185 
187  API_BEGIN()
188  const Predictor* predictor_ = static_cast<Predictor*>(handle);
189  *out = predictor_->QuerySigmoidAlpha();
190  API_END();
191 }
192 
194  API_BEGIN()
195  const Predictor* predictor_ = static_cast<Predictor*>(handle);
196  *out = predictor_->QueryGlobalBias();
197  API_END();
198 }
199 
201  API_BEGIN();
202  delete static_cast<Predictor*>(handle);
203  API_END();
204 }
Load prediction function exported as a shared library.
void * DenseBatchHandle
handle to batch of dense data rows
Definition: c_api_runtime.h:28
size_t QueryNumFeature() const
Get the width (number of features) of each instance used to train the loaded model.
Definition: predictor.h:171
void * CSRBatchHandle
handle to batch of sparse data rows
Definition: c_api_runtime.h:26
const uint32_t * col_ind
feature indices
Definition: predictor.h:22
#define API_BEGIN()
macro to guard beginning and end section of all functions
Definition: c_api_error.h:15
size_t QueryResultSizeSingleInst() const
Query the necessary size of array to hold the prediction for a single data row.
Definition: predictor.h:151
C API of Treelite, used for interfacing with other languages This header is used exclusively by the r...
int TreelitePredictorQueryResultSize(PredictorHandle handle, void *batch, int batch_sparse, size_t *out)
Given a batch of data rows, query the necessary size of array to hold predictions for all data points...
int TreelitePredictorQueryResultSizeSingleInst(PredictorHandle handle, size_t *out)
Query the necessary size of array to hold the prediction for a single data row.
int TreelitePredictorQueryPredTransform(PredictorHandle handle, const char **out)
Get name of post prediction transformation used to train the loaded model.
int TreelitePredictorPredictBatch(PredictorHandle handle, void *batch, int batch_sparse, int verbose, int pred_margin, float *out_result, size_t *out_result_size)
Make predictions on a batch of data rows (synchronously). This function internally divides the worklo...
size_t PredictInst(TreelitePredictorEntry *inst, bool pred_margin, float *out_result)
Make predictions on a single data row (synchronously). The work will be scheduled to the calling thre...
Definition: predictor.cc:459
int TreelitePredictorQueryNumFeature(PredictorHandle handle, size_t *out)
Get the width (number of features) of each instance used to train the loaded model.
int TreeliteBatchGetDimension(void *handle, int batch_sparse, size_t *out_num_row, size_t *out_num_col)
get dimensions of a batch
sparse batch in Compressed Sparse Row (CSR) format
Definition: predictor.h:18
const size_t * row_ptr
pointer to row headers; length of [num_row] + 1
Definition: predictor.h:24
void Load(const char *name)
load the prediction function from dynamic shared library.
Definition: predictor.cc:228
dense batch
Definition: predictor.h:32
float QueryGlobalBias() const
Get global bias which adjusting predicted margin scores.
Definition: predictor.h:195
const float * data
feature values
Definition: predictor.h:34
Error handling for C API.
int TreelitePredictorLoad(const char *library_path, int num_worker_thread, PredictorHandle *out)
load prediction code into memory. This function assumes that the prediction code has been already com...
int TreeliteAssembleSparseBatch(const float *data, const uint32_t *col_ind, const size_t *row_ptr, size_t num_row, size_t num_col, CSRBatchHandle *out)
assemble a sparse batch
size_t PredictBatch(const CSRBatch *batch, int verbose, bool pred_margin, float *out_result)
Make predictions on a batch of data rows (synchronously). This function internally divides the worklo...
Definition: predictor.cc:447
float missing_value
value representing the missing value (usually nan)
Definition: predictor.h:36
size_t QueryResultSize(const CSRBatch *batch) const
Given a batch of data rows, query the necessary size of array to hold predictions for all data points...
Definition: predictor.h:100
int TreeliteDeleteDenseBatch(DenseBatchHandle handle)
delete a dense batch from memory
int TreeliteDeleteSparseBatch(CSRBatchHandle handle)
delete a sparse batch from memory
int TreeliteAssembleDenseBatch(const float *data, float missing_value, size_t num_row, size_t num_col, DenseBatchHandle *out)
assemble a dense batch
data layout. The value -1 signifies the missing value. When the "missing" field is set to -1...
Definition: entry.h:14
void * PredictorHandle
handle to predictor class
Definition: c_api_runtime.h:24
const float * data
feature values
Definition: predictor.h:20
std::string QueryPredTransform() const
Get name of post prediction transformation used to train the loaded model.
Definition: predictor.h:179
float QuerySigmoidAlpha() const
Get alpha value in sigmoid transformation used to train the loaded model.
Definition: predictor.h:187
size_t num_row
number of rows
Definition: predictor.h:38
size_t QueryNumOutputGroup() const
Get the number of output groups in the loaded model The number is 1 for most tasks; it is greater tha...
Definition: predictor.h:162
int TreelitePredictorQueryNumOutputGroup(PredictorHandle handle, size_t *out)
Get the number of output groups in the loaded model The number is 1 for most tasks; it is greater tha...
predictor class: wrapper for optimized prediction code
Definition: predictor.h:44
int TreelitePredictorFree(PredictorHandle handle)
delete predictor from memory
size_t num_row
number of rows
Definition: predictor.h:26
int TreelitePredictorPredictInst(PredictorHandle handle, union TreelitePredictorEntry *inst, int pred_margin, float *out_result, size_t *out_result_size)
Make predictions on a single data row (synchronously). The work will be scheduled to the calling thre...
size_t num_col
number of columns (i.e. # of features used)
Definition: predictor.h:28
int TreelitePredictorQuerySigmoidAlpha(PredictorHandle handle, float *out)
Get alpha value of sigmoid transformation used to train the loaded model.
#define API_END()
every function starts with API_BEGIN(); and finishes with API_END() or API_END_HANDLE_ERROR ...
Definition: c_api_error.h:18
int TreelitePredictorQueryGlobalBias(PredictorHandle handle, float *out)
Get global bias which adjusting predicted margin scores.
size_t num_col
number of columns (i.e. # of features used)
Definition: predictor.h:40