c_api.h

Go to the documentation of this file.

 
#ifndef XGBOOST_C_API_H_
#define XGBOOST_C_API_H_
 
#ifdef __cplusplus
#define XGB_EXTERN_C extern "C"
#include <cstddef>
#include <cstdint>
#include <cstdio>
#else
#define XGB_EXTERN_C
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
#endif  // __cplusplus
 
#if defined(_MSC_VER) || defined(_WIN32)
#define XGB_DLL XGB_EXTERN_C __declspec(dllexport)
#else
#define XGB_DLL XGB_EXTERN_C __attribute__((visibility("default")))
#endif  // defined(_MSC_VER) || defined(_WIN32)
 
// manually define unsigned long
typedef uint64_t bst_ulong;  // NOLINT(*)
 
typedef void *DMatrixHandle;  // NOLINT(*)
typedef void *BoosterHandle;  // NOLINT(*)
typedef void *CategoriesHandle;  // NOLINT(*)
 
XGB_DLL void XGBoostVersion(int *major, int *minor, int *patch);
 
XGB_DLL int XGBuildInfo(char const **out);
 
XGB_DLL const char *XGBGetLastError();
 
XGB_DLL int XGBRegisterLogCallback(void (*callback)(const char *));
 
XGB_DLL int XGBSetGlobalConfig(char const *config);
 
XGB_DLL int XGBGetGlobalConfig(char const **out_config);
 
XGB_DLL int XGDMatrixCreateFromFile(const char *fname, int silent, DMatrixHandle *out);
 
XGB_DLL int XGDMatrixCreateFromURI(char const *config, DMatrixHandle *out);
 
XGB_DLL int XGDMatrixCreateFromColumnar(char const *data, char const *config, DMatrixHandle *out);
 
XGB_DLL int XGDMatrixCreateFromCSR(char const *indptr, char const *indices, char const *data,
                                   bst_ulong ncol, char const *config, DMatrixHandle *out);
 
XGB_DLL int XGDMatrixCreateFromDense(char const *data, char const *config, DMatrixHandle *out);
 
XGB_DLL int XGDMatrixCreateFromCSC(char const *indptr, char const *indices, char const *data,
                                   bst_ulong nrow, char const *config, DMatrixHandle *out);
 
XGB_DLL int XGDMatrixCreateFromMat(const float *data, bst_ulong nrow, bst_ulong ncol, float missing,
                                   DMatrixHandle *out);
XGB_DLL int XGDMatrixCreateFromMat_omp(const float *data,  // NOLINT
                                       bst_ulong nrow, bst_ulong ncol, float missing,
                                       DMatrixHandle *out, int nthread);
 
XGB_DLL int XGDMatrixCreateFromCudaColumnar(char const *data, char const *config,
                                            DMatrixHandle *out);
 
XGB_DLL int XGDMatrixCreateFromCudaArrayInterface(char const *data, char const *config,
                                                  DMatrixHandle *out);
 
/*  ==== First set of callback functions, used exclusively by JVM packages. ==== */
 
typedef void *DataIterHandle;  // NOLINT(*)
typedef void *DataHolderHandle;  // NOLINT(*)
 
typedef struct {  // NOLINT(*)
  size_t size;
  size_t columns;
#ifdef __APPLE__
  /* Necessary as Java on MacOS defines jlong as long int
   * and gcc defines int64_t as long long int. */
  long *offset;  // NOLINT(*)
#else
  int64_t *offset;  // NOLINT(*)
#endif  // __APPLE__
  float *label;
  float *weight;
  int *index;
  float *value;
} XGBoostBatchCSR;
 
XGB_EXTERN_C typedef int XGBCallbackSetData(  // NOLINT(*)
    DataHolderHandle handle, XGBoostBatchCSR batch);
 
XGB_EXTERN_C typedef int XGBCallbackDataIterNext(  // NOLINT(*)
    DataIterHandle data_handle, XGBCallbackSetData *set_function,
    DataHolderHandle set_function_handle);
 
XGB_DLL int XGDMatrixCreateFromDataIter(DataIterHandle data_handle,
                                        XGBCallbackDataIterNext *callback, const char *cache_info,
                                        float missing, DMatrixHandle *out);
 
XGB_DLL int XGProxyDMatrixCreate(DMatrixHandle *out);
 
XGB_EXTERN_C typedef int XGDMatrixCallbackNext(DataIterHandle iter);  // NOLINT(*)
 
XGB_EXTERN_C typedef void DataIterResetCallback(DataIterHandle handle);  // NOLINT(*)
 
XGB_DLL int XGDMatrixCreateFromCallback(DataIterHandle iter, DMatrixHandle proxy,
                                        DataIterResetCallback *reset, XGDMatrixCallbackNext *next,
                                        char const *config, DMatrixHandle *out);
XGB_DLL int XGQuantileDMatrixCreateFromCallback(DataIterHandle iter, DMatrixHandle proxy,
                                                DataIterHandle ref, DataIterResetCallback *reset,
                                                XGDMatrixCallbackNext *next, char const *config,
                                                DMatrixHandle *out);
 
XGB_DLL int XGExtMemQuantileDMatrixCreateFromCallback(DataIterHandle iter, DMatrixHandle proxy,
                                                      DataIterHandle ref,
                                                      DataIterResetCallback *reset,
                                                      XGDMatrixCallbackNext *next,
                                                      char const *config, DMatrixHandle *out);
 
XGB_DLL int XGProxyDMatrixSetDataCudaArrayInterface(DMatrixHandle handle, const char *data);
 
XGB_DLL int XGProxyDMatrixSetDataColumnar(DMatrixHandle handle, char const *data);
 
XGB_DLL int XGProxyDMatrixSetDataCudaColumnar(DMatrixHandle handle, const char *data);
 
XGB_DLL int XGProxyDMatrixSetDataDense(DMatrixHandle handle, char const *data);
 
XGB_DLL int XGProxyDMatrixSetDataCSR(DMatrixHandle handle, char const *indptr, char const *indices,
                                     char const *data, bst_ulong ncol);
  // End of Streaming
 
XGB_DLL int XGDMatrixSliceDMatrix(DMatrixHandle handle, const int *idxset, bst_ulong len,
                                  DMatrixHandle *out);
XGB_DLL int XGDMatrixSliceDMatrixEx(DMatrixHandle handle, const int *idxset, bst_ulong len,
                                    DMatrixHandle *out, int allow_groups);
XGB_DLL int XGDMatrixFree(DMatrixHandle handle);
XGB_DLL int XGDMatrixSaveBinary(DMatrixHandle handle, const char *fname, int silent);
 
XGB_DLL int XGDMatrixSetInfoFromInterface(DMatrixHandle handle, char const *field,
                                          char const *data);
 
XGB_DLL int XGDMatrixSetFloatInfo(DMatrixHandle handle, const char *field, const float *array,
                                  bst_ulong len);
XGB_DLL int XGDMatrixSetUIntInfo(DMatrixHandle handle, const char *field, const unsigned *array,
                                 bst_ulong len);
 
XGB_DLL int XGDMatrixSetStrFeatureInfo(DMatrixHandle handle, const char *field,
                                       const char **features, const bst_ulong size);
 
XGB_DLL int XGDMatrixGetStrFeatureInfo(DMatrixHandle handle, const char *field, bst_ulong *size,
                                       const char ***out_features);
 
XGB_DLL int XGDMatrixGetCategories(DMatrixHandle handle, char const *config, CategoriesHandle *out);
 
XGB_DLL int XGDMatrixGetCategoriesExportToArrow(DMatrixHandle handle, char const *config,
                                                CategoriesHandle *out, char const **export_out);
 
XGB_DLL int XGBCategoriesFree(CategoriesHandle handle);
 
XGB_DLL int XGDMatrixSetDenseInfo(DMatrixHandle handle, const char *field, void const *data,
                                  bst_ulong size, int type);
 
XGB_DLL int XGDMatrixGetInfoRef(DMatrixHandle handle, char const *field, char const **out_array);
 
XGB_DLL int XGDMatrixGetFloatInfo(const DMatrixHandle handle, const char *field, bst_ulong *out_len,
                                  const float **out_dptr);
XGB_DLL int XGDMatrixGetUIntInfo(const DMatrixHandle handle, const char *field, bst_ulong *out_len,
                                 const unsigned **out_dptr);
XGB_DLL int XGDMatrixNumRow(DMatrixHandle handle, bst_ulong *out);
XGB_DLL int XGDMatrixNumCol(DMatrixHandle handle, bst_ulong *out);
 
XGB_DLL int XGDMatrixNumNonMissing(DMatrixHandle handle, bst_ulong *out);
 
XGB_DLL int XGDMatrixDataSplitMode(DMatrixHandle handle, bst_ulong *out);
 
XGB_DLL int XGDMatrixGetDataAsCSR(DMatrixHandle const handle, char const *config,
                                  bst_ulong *out_indptr, unsigned *out_indices, float *out_data);
 
XGB_DLL int XGDMatrixGetQuantileCut(DMatrixHandle const handle, char const *config,
                                    char const **out_indptr, char const **out_data);
  // End of DMatrix
 
XGB_DLL int XGBoosterCreate(const DMatrixHandle dmats[], bst_ulong len, BoosterHandle *out);
XGB_DLL int XGBoosterFree(BoosterHandle handle);
XGB_DLL int XGBoosterReset(BoosterHandle handle);
 
XGB_DLL int XGBoosterSlice(BoosterHandle handle, int begin_layer, int end_layer, int step,
                           BoosterHandle *out);
 
XGB_DLL int XGBoosterBoostedRounds(BoosterHandle handle, int *out);
 
XGB_DLL int XGBoosterSetParam(BoosterHandle handle, const char *name, const char *value);
XGB_DLL int XGBoosterGetNumFeature(BoosterHandle handle, bst_ulong *out);
XGB_DLL int XGBoosterUpdateOneIter(BoosterHandle handle, int iter, DMatrixHandle dtrain);
XGB_DLL int XGBoosterBoostOneIter(BoosterHandle handle, DMatrixHandle dtrain, float *grad,
                                  float *hess, bst_ulong len);
 
XGB_DLL int XGBoosterTrainOneIter(BoosterHandle handle, DMatrixHandle dtrain, int iter,
                                  char const *grad, char const *hess);
 
XGB_DLL int XGBoosterEvalOneIter(BoosterHandle handle, int iter, DMatrixHandle dmats[],
                                 const char *evnames[], bst_ulong len, const char **out_result);
XGB_DLL int XGBoosterPredict(BoosterHandle handle, DMatrixHandle dmat, int option_mask,
                             unsigned ntree_limit, int training, bst_ulong *out_len,
                             const float **out_result);
 
XGB_DLL int XGBoosterPredictFromDMatrix(BoosterHandle handle, DMatrixHandle dmat,
                                        char const *config, bst_ulong const **out_shape,
                                        bst_ulong *out_dim, float const **out_result);
XGB_DLL int XGBoosterPredictFromDense(BoosterHandle handle, char const *values, char const *config,
                                      DMatrixHandle m, bst_ulong const **out_shape,
                                      bst_ulong *out_dim, const float **out_result);
XGB_DLL int XGBoosterPredictFromColumnar(BoosterHandle handle, char const *values,
                                         char const *config, DMatrixHandle m,
                                         bst_ulong const **out_shape, bst_ulong *out_dim,
                                         const float **out_result);
 
XGB_DLL int XGBoosterPredictFromCSR(BoosterHandle handle, char const *indptr, char const *indices,
                                    char const *values, bst_ulong ncol, char const *config,
                                    DMatrixHandle m, bst_ulong const **out_shape,
                                    bst_ulong *out_dim, const float **out_result);
 
XGB_DLL int XGBoosterPredictFromCudaArray(BoosterHandle handle, char const *values,
                                          char const *config, DMatrixHandle proxy,
                                          bst_ulong const **out_shape, bst_ulong *out_dim,
                                          const float **out_result);
 
XGB_DLL int XGBoosterPredictFromCudaColumnar(BoosterHandle handle, char const *data,
                                             char const *config, DMatrixHandle proxy,
                                             bst_ulong const **out_shape, bst_ulong *out_dim,
                                             const float **out_result);
  // End of Prediction
 
XGB_DLL int XGBoosterLoadModel(BoosterHandle handle, const char *fname);
XGB_DLL int XGBoosterSaveModel(BoosterHandle handle, const char *fname);
XGB_DLL int XGBoosterLoadModelFromBuffer(BoosterHandle handle, const void *buf, bst_ulong len);
 
XGB_DLL int XGBoosterSaveModelToBuffer(BoosterHandle handle, char const *config, bst_ulong *out_len,
                                       char const **out_dptr);
 
XGB_DLL int XGBoosterSerializeToBuffer(BoosterHandle handle, bst_ulong *out_len,
                                       const char **out_dptr);
XGB_DLL int XGBoosterUnserializeFromBuffer(BoosterHandle handle, const void *buf, bst_ulong len);
 
XGB_DLL int XGBoosterSaveJsonConfig(BoosterHandle handle, bst_ulong *out_len, char const **out_str);
XGB_DLL int XGBoosterLoadJsonConfig(BoosterHandle handle, char const *config);  // End of Serialization
 
XGB_DLL int XGBoosterDumpModel(BoosterHandle handle, const char *fmap, int with_stats,
                               bst_ulong *out_len, const char ***out_dump_array);
 
XGB_DLL int XGBoosterDumpModelEx(BoosterHandle handle, const char *fmap, int with_stats,
                                 const char *format, bst_ulong *out_len,
                                 const char ***out_dump_array);
 
XGB_DLL int XGBoosterDumpModelWithFeatures(BoosterHandle handle, int fnum, const char **fname,
                                           const char **ftype, int with_stats, bst_ulong *out_len,
                                           const char ***out_models);
 
XGB_DLL int XGBoosterDumpModelExWithFeatures(BoosterHandle handle, int fnum, const char **fname,
                                             const char **ftype, int with_stats, const char *format,
                                             bst_ulong *out_len, const char ***out_models);
 
XGB_DLL int XGBoosterGetCategories(BoosterHandle handle, char const *config, CategoriesHandle *out);
 
XGB_DLL int XGBoosterGetCategoriesExportToArrow(BoosterHandle handle, char const *config,
                                                CategoriesHandle *out, char const **export_out);
 
XGB_DLL int XGBoosterGetAttr(BoosterHandle handle, const char *key, const char **out, int *success);
XGB_DLL int XGBoosterSetAttr(BoosterHandle handle, const char *key, const char *value);
XGB_DLL int XGBoosterGetAttrNames(BoosterHandle handle, bst_ulong *out_len, const char ***out);
 
XGB_DLL int XGBoosterSetStrFeatureInfo(BoosterHandle handle, const char *field,
                                       const char **features, const bst_ulong size);
 
XGB_DLL int XGBoosterGetStrFeatureInfo(BoosterHandle handle, const char *field, bst_ulong *len,
                                       const char ***out_features);
 
XGB_DLL int XGBoosterFeatureScore(BoosterHandle handle, const char *config,
                                  bst_ulong *out_n_features, char const ***out_features,
                                  bst_ulong *out_dim, bst_ulong const **out_shape,
                                  float const **out_scores);  // End of Booster
 
typedef void *TrackerHandle; /* NOLINT */
 
XGB_DLL int XGTrackerCreate(char const *config, TrackerHandle *handle);
 
XGB_DLL int XGTrackerWorkerArgs(TrackerHandle handle, char const **args);
 
XGB_DLL int XGTrackerRun(TrackerHandle handle, char const *config);
 
XGB_DLL int XGTrackerWaitFor(TrackerHandle handle, char const *config);
 
XGB_DLL int XGTrackerFree(TrackerHandle handle);
 
XGB_DLL int XGCommunicatorInit(char const *config);
 
XGB_DLL int XGCommunicatorFinalize(void);
 
XGB_DLL int XGCommunicatorGetRank(void);
 
XGB_DLL int XGCommunicatorGetWorldSize(void);
 
XGB_DLL int XGCommunicatorIsDistributed(void);
 
XGB_DLL int XGCommunicatorPrint(char const *message);
 
XGB_DLL int XGCommunicatorGetProcessorName(const char **name_str);
 
XGB_DLL int XGCommunicatorBroadcast(void *send_receive_buffer, size_t size, int root);
 
XGB_DLL int XGCommunicatorAllreduce(void *send_receive_buffer, size_t count, int data_type, int op);
  // End of Collective
#endif   // XGBOOST_C_API_H_