c_api.h

查看此文件文档。

#ifndef XGBOOST_C_API_H_
#define XGBOOST_C_API_H_

#ifdef __cplusplus
#define XGB_EXTERN_C extern "C"
#include <cstddef>
#include <cstdio>
#include <cstdint>
#else
#define XGB_EXTERN_C
#include <stddef.h>
#include <stdio.h>
#include <stdint.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)

// 手动定义 unsigned long
typedef uint64_t bst_ulong; // NOLINT(*)

typedef void *DMatrixHandle; // NOLINT(*)
typedef void *BoosterHandle; // 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 XGDMatrixCreateFromCSREx(const size_t *indptr, const unsigned *indices,
 const float *data, size_t nindptr, size_t nelem,
 size_t num_col, 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 XGDMatrixCreateFromCSCEx(const size_t *col_ptr, const unsigned *indices,
 const float *data, size_t nindptr, size_t nelem,
 size_t num_row, 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);

/* ==== 用于 JVM 包的第一组回调函数。 ==== */

typedef void *DataIterHandle; // NOLINT(*)
typedef void *DataHolderHandle; // NOLINT(*)


typedef struct { // NOLINT(*)
/* \brief 迷你批次中的行数。 */ size_t size;
 /* \brief 迷你批次中的列数。 */
 size_t columns;
#ifdef __APPLE__
 /* 在 MacOS 上，Java 将 jlong 定义为 long int，
 * 而 gcc 将 int64_t 定义为 long long int。因此有必要。 */
 long* offset; // NOLINT(*)
#else
 int64_t* offset; // NOLINT(*)
#endif // __APPLE__
/* \brief 迷你批次的标签 */ float* label;
 /* \brief 迷你批次的权重 */ float* weight;
 /* \brief 特征索引 */ int* index;
 /* \brief 特征值 */ 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);
 // Stream 结束

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 XGDMatrixSetDenseInfo(DMatrixHandle handle, const char *field, void const *data,
 bst_ulong size, int type);

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);
 // 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);
 // 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); // 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 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); // 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);
 // Collective 结束
#endif // XGBOOST_C_API_H_