//------------------------------------------------------------------------------
// GxB_init: initialize GraphBLAS and declare malloc/calloc/realloc/free to use
//------------------------------------------------------------------------------

// SuiteSparse:GraphBLAS, Timothy A. Davis, (c) 2017-2025, All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0

//------------------------------------------------------------------------------

// GrB_init (or GxB_init) must called before any other GraphBLAS operation.
// GrB_finalize must be called as the last GraphBLAS operation.  GxB_init is
// identical to GrB_init, except that it allows the user application to define
// the malloc/calloc/realloc/free functions that SuiteSparse:GraphBLAS will
// use for arena 0 (the default arena).  The functions cannot be modified once
// GraphBLAS starts.

// The calloc and realloc function pointers are optional and can be NULL.  If
// calloc is currently not used, and malloc/memset are used instead.  If
// realloc is NULL, it is not used, and malloc/memcpy/free are used instead.

// The malloc/calloc/realloc/free functions passed to GxB_init are for
// arena 0 (GrB_DEFAULT), and cannot be modified once set by GxB_init.
// GraphBLAS uses this arena during initializations (for the JIT hash table).

// Examples:
//
// To use GraphBLAS with the C11 functions (or to another library
// linked in that replaces them): 
//
//      // either use:
//      GrB_init (mode) ;
//      // or use this (but not both):
//      GxB_init (mode, malloc, calloc, realloc, free) ;
//
// To use GraphBLAS from within a mexFunction:
//
//      #include "mex.h"
//      GxB_init (mode, mxMalloc, mxCalloc, mxRealloc, mxFree) ;
//
// To use the C interface to the Intel TBB scalable allocators:
//
//      #include "tbb/scalable_allocator.h"
//      GxB_init (mode, scalable_malloc, scalable_calloc, scalable_realloc,
//          scalable_free) ;
//
// To use CUDA and its RMM memory manager in arena 0:
//
//      GxB_init (mode, GB_rmm_malloc, NULL, NULL, GB_rmm_free) ;
//
//          where mode is GxB_BLOCKING_GPU or GxB_NONBLOCKING_GPU
//
// To use user-provided malloc and free functions, but not calloc/realloc:
//
//      GxB_init (mode, my_malloc, NULL, NULL, my_free) ;
//
// The calloc function is not called by GraphBLAS; malloc and a parallel memset
// are used instead.  The only place where the calloc function pointer is used
// is by GrB_get, which can return it to the user application.

#include "GB.h"
#include "init/GB_init.h"

GrB_Info GxB_init           // start up GraphBLAS and also define malloc, etc
(
    int mode,               // blocking or non-blocking mode

    // pointers to memory management functions
    void * (* user_malloc_function  ) (size_t),         // required
    void * (* user_calloc_function  ) (size_t, size_t), // not used
    void * (* user_realloc_function ) (void *, size_t), // optional, can be NULL
    void   (* user_free_function    ) (void *)          // required
)
{ 

    //--------------------------------------------------------------------------
    // check inputs
    //--------------------------------------------------------------------------

    GB_WERK ("GxB_init (mode, malloc, calloc, realloc, free)") ;

    //--------------------------------------------------------------------------
    // initialize GraphBLAS
    //--------------------------------------------------------------------------

#if defined ( GRAPHBLAS_HAS_CUDA )
    // fixme for CUDA arena: CUDA will have GB_rmm_malloc etc in another arena
    if (mode == GxB_BLOCKING_GPU || mode == GxB_NONBLOCKING_GPU)
    {
        return (GB_init (mode,              // blocking or non-blocking mode
            // thread-safe RMM C memory management functions:
            GB_rmm_malloc, NULL, NULL, GB_rmm_free, Werk)) ;
    }
#endif

    return (GB_init
        (mode,                          // blocking or non-blocking mode
        user_malloc_function,           // user-defined malloc, required
        user_calloc_function,           // user-defined calloc, not used
        user_realloc_function,          // user-defined realloc, may be NULL
        user_free_function,             // user-defined free, required
        Werk)) ;
}

