fmpi_core.h

// SPDX-License-Identifier: 0BSD
/*!
 * @file
 * @license{
 * BSD Zero Clause License
 *
 * Copyright (c) 2022 by Raphael Bach
 *
 * Permission to use, copy, modify, and/or distribute this software for any
 * purpose with or without fee is hereby granted.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
 * OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 * PERFORMANCE OF THIS SOFTWARE.
 * }
 */
/*==============================================================================
    GUARD
==============================================================================*/
#ifndef FMPI_CORE_H_20211231181158
#define FMPI_CORE_H_20211231181158
/*==============================================================================
    INCLUDE
==============================================================================*/
// C Standard Library
// Internal
#include "internal/fmpi_ctx.h"
/*==============================================================================
    PUBLIC FUNCTION
==============================================================================*/
/*------------------------------------------------------------------------------
    fmpi_init()
------------------------------------------------------------------------------*/
/**
 * Initializes the fmpi library.
 *
 * @param[in,out] argc : A pointer to the `argc` parameter of `main()`.
 * @param[in,out] argv  : A triple pointer to the `argv` parameter of `main()`.
 *
 * @return
 * - @success: A pointer to a newly allocated `fmpi_ctx`.
 * - @failure: `NULL`.
 *
 * @example{
 *  struct fmpi_ctx * ctx = fmpi_init(&argc, &argv);
 *  if(ctx == NULL) {
 *      fprintf(stderr, "fmpi_init() failed!\n");
 *      fmpi_abort(NULL);
 *  }
 * }
 */
struct fmpi_ctx * fmpi_init(int * argc, char ** argv[]);
/*------------------------------------------------------------------------------
    fmpi_exit()
------------------------------------------------------------------------------*/
/**
 * Exits the fmpi library and sets \p{ctx} to `NULL` after freeing it.
 *
 * @param[in,out] ctx : A double pointer to a valid `fmpi_ctx` allocated with
 *                      `fmpi_init()`.
 *
 * @return
 * - @success: `0`.
 * - @failure: A non-zero value.
 *
 * @warning
 * - \b [UB] \p{ctx} must not be `NULL`.
 * - \b [UB] \p{*ctx} must not be `NULL`.
 *
 * @example{
 *  struct fmpi_ctx * ctx = fmpi_init(&argc, &argv);
 *  if(fmpi_exit(ctx) != 0) {
 *      fprintf(stderr, "fmpi_exit() failed!\n");
 *  }
 * }
 */
int fmpi_exit(struct fmpi_ctx ** const ctx);
/*------------------------------------------------------------------------------
    fmpi_abort()
------------------------------------------------------------------------------*/
/**
 * TODO
 *
 * @example{
 *  TODO
 * }
 */
_Noreturn void fmpi_abort(void);
/*------------------------------------------------------------------------------
    fmpi_is_root()
------------------------------------------------------------------------------*/
/**
 * TODO
 *
 * @param[in] ctx : A pointer to a fmpi_ctx.
 *
 * @return TODO
 *
 * @warning
 * - \b [UB] \p{ctx} must not be `NULL`.
 *
 * @example{
 *  TODO
 * }
 */
_Bool fmpi_is_root(const struct fmpi_ctx * ctx);
/*------------------------------------------------------------------------------
    fmpi_root_printf()
------------------------------------------------------------------------------*/
#define fmpi_root_printf(ctx, ...) \
do { \
    if(fmpi_is_root((ctx))) { \
        printf(__VA_ARGS__); \
    } \
} while(0)
/*==============================================================================
    GUARD
==============================================================================*/
#endif // FMPI_CORE_H_20211231181158