/**
* Copyright 2015~2023 by XGBoost Contributors
* \file c_api.h
* \author Tianqi Chen
* \brief C API of XGBoost, used for interfacing to other languages.
*/
#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)
// manually define unsigned long
typedef uint64_t bst_ulong; // NOLINT(*)
/**
* @mainpage
*
* \brief XGBoost C API reference.
*
* For the official document page see:
* <a href="https://xgboost.readthedocs.io/en/stable/c.html">XGBoost C Package</a>.
*/
/**
* @defgroup Library
*
* These functions are used to obtain general information about XGBoost including version,
* build info and current global configuration.
*
* @{
*/
/*! \brief handle to DMatrix */
typedef void *DMatrixHandle; // NOLINT(*)
/*! \brief handle to Booster */
typedef void *BoosterHandle; // NOLINT(*)
/*!
* \brief Return the version of the XGBoost library being currently used.
*
* The output variable is only written if it's not NULL.
*
* \param major Store the major version number
* \param minor Store the minor version number
* \param patch Store the patch (revision) number
*/
XGB_DLL void XGBoostVersion(int* major, int* minor, int* patch);
/*!
* \brief Get compile information of shared library.
*
* \param out string encoded JSON object containing build flags and dependency version.
*
* \return 0 for success, -1 for failure
*/
XGB_DLL int XGBuildInfo(char const **out);
/*!
* \brief get string message of the last error
*
* all function in this file will return 0 when success
* and -1 when an error occurred,
* XGBGetLastError can be called to retrieve the error
*
* this function is thread safe and can be called by different thread
* \return const char* error information
*/
XGB_DLL const char *XGBGetLastError();
/*!
* \brief register callback function for LOG(INFO) messages -- helpful messages
* that are not errors.
* Note: this function can be called by multiple threads. The callback function
* will run on the thread that registered it
* \return 0 for success, -1 for failure
*/
XGB_DLL int XGBRegisterLogCallback(void (*callback)(const char*));
/*!
* \brief Set global configuration (collection of parameters that apply globally). This function
* accepts the list of key-value pairs representing the global-scope parameters to be
* configured. The list of key-value pairs are passed in as a JSON string.
* \param config a JSON string representing the list of key-value pairs. The JSON object shall
* be flat: no value can be a JSON object or an array.
* \return 0 for success, -1 for failure
*/
XGB_DLL int XGBSetGlobalConfig(char const *config);
/*!
* \brief Get current global configuration (collection of parameters that apply globally).
* \param out_config pointer to received returned global configuration, represented as a JSON string.
* \return 0 for success, -1 for failure
*/
XGB_DLL int XGBGetGlobalConfig(char const **out_config);
/**@}*/
/**
* @defgroup DMatrix
*
* @brief DMatrix is the baisc data storage for XGBoost used by all XGBoost algorithms
* including both training, prediction and explanation. There are a few variants of
* `DMatrix` including normal `DMatrix`, which is a CSR matrix, `QuantileDMatrix`,
* which is used by histogram-based tree methods for saving memory, and lastly the
* experimental external-memory-based DMatrix, which reads data in batches during
* training. For the last two variants, see the @ref Streaming group.
*
* @{
*/
/*!
* \brief load a data matrix
* \deprecated since 2.0.0
* \see XGDMatrixCreateFromURI()
* \param fname the name of the file
* \param silent whether print messages during loading
* \param out a loaded data matrix
* \return 0 when success, -1 when failure happens
*/
XGB_DLL int XGDMatrixCreateFromFile(const char *fname, int silent, DMatrixHandle *out);
/*!
* \brief load a data matrix
* \param config JSON encoded parameters for DMatrix construction. Accepted fields are:
* - uri: The URI of the input file.
* - silent (optional): Whether to print message during loading. Default to true.
* - data_split_mode (optional): Whether to split by row or column. In distributed mode, the
* file is split accordingly; otherwise this is only an indicator on how the file was split
* beforehand. Default to row.
* \param out a loaded data matrix
* \return 0 when success, -1 when failure happens
*/
XGB_DLL int XGDMatrixCreateFromURI(char const *config, DMatrixHandle *out);
/*!
* \brief create a matrix content from CSR format
* \deprecated since 2.0.0
* \see XGDMatrixCreateFromCSR()
*/
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);
/**
* @example c-api-demo.c
*/
/*!
* \brief Create a matrix from CSR matrix.
* \param indptr JSON encoded __array_interface__ to row pointers in CSR.
* \param indices JSON encoded __array_interface__ to column indices in CSR.
* \param data JSON encoded __array_interface__ to values in CSR.
* \param ncol Number of columns.
* \param config JSON encoded configuration. Required values are:
* - missing: Which value to represent missing value.
* - nthread (optional): Number of threads used for initializing DMatrix.
* \param out created dmatrix
* \return 0 when success, -1 when failure happens
*/
XGB_DLL int XGDMatrixCreateFromCSR(char const *indptr, char const *indices, char const *data,
bst_ulong ncol, char const *config, DMatrixHandle *out);
/*!
* \brief Create a matrix from dense array.
* \param data JSON encoded __array_interface__ to array values.
* \param config JSON encoded configuration. Required values are:
* - missing: Which value to represent missing value.
* - nthread (optional): Number of threads used for initializing DMatrix.
* \param out created dmatrix
* \return 0 when success, -1 when failure happens
*/
XGB_DLL int XGDMatrixCreateFromDense(char const *data, char const *config, DMatrixHandle *out);
/*!
* \brief Create a matrix from a CSC matrix.
* \param indptr JSON encoded __array_interface__ to column pointers in CSC.
* \param indices JSON encoded __array_interface__ to row indices in CSC.
* \param data JSON encoded __array_interface__ to values in CSC.
* \param nrow number of rows in the matrix.
* \param config JSON encoded configuration. Supported values are:
* - missing: Which value to represent missing value.
* - nthread (optional): Number of threads used for initializing DMatrix.
* \param out created dmatrix
* \return 0 when success, -1 when failure happens
*/
XGB_DLL int XGDMatrixCreateFromCSC(char const *indptr, char const *indices, char const *data,
bst_ulong nrow, char const *c_json_config, DMatrixHandle *out);
/*!
* \brief create a matrix content from CSC format
* \deprecated since 2.0.0
* \see XGDMatrixCreateFromCSC()
*/
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);
/*!
* \brief create matrix content from dense matrix
* \param data pointer to the data space
* \param nrow number of rows
* \param ncol number columns
* \param missing which value to repr