dlb_talp.h

Go to the documentation of this file.

/*********************************************************************************/
/*  Copyright 2009-2025 Barcelona Supercomputing Center                          */
/*                                                                               */
/*  This file is part of the DLB library.                                        */
/*                                                                               */
/*  DLB is free software: you can redistribute it and/or modify                  */
/*  it under the terms of the GNU Lesser General Public License as published by  */
/*  the Free Software Foundation, either version 3 of the License, or            */
/*  (at your option) any later version.                                          */
/*                                                                               */
/*  DLB is distributed in the hope that it will be useful,                       */
/*  but WITHOUT ANY WARRANTY; without even the implied warranty of               */
/*  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the                */
/*  GNU Lesser General Public License for more details.                          */
/*                                                                               */
/*  You should have received a copy of the GNU Lesser General Public License     */
/*  along with DLB.  If not, see <https://www.gnu.org/licenses/>.                */
/*********************************************************************************/
 
#ifndef DLB_API_TALP_H
#define DLB_API_TALP_H
 
#include <time.h>
#include <stdint.h>
 
#define DLB_GLOBAL_REGION_NAME "Global"
#define DLB_GLOBAL_REGION NULL
#define DLB_MPI_REGION NULL         /* deprecated in favor of DLB_GLOBAL_REGION */
#define DLB_IMPLICIT_REGION NULL    /* deprecated in favor of DLB_GLOBAL_REGION */
#define DLB_LAST_OPEN_REGION (void*)1
 
enum { DLB_MONITOR_NAME_MAX = 128 };
 
typedef struct dlb_monitor_t {
    const char  *name;
    int         num_cpus;
    float       avg_cpus;
    int64_t     cycles;
    int64_t     instructions;
    int         num_measurements;
    int         num_resets;
    int64_t     num_mpi_calls;
    int64_t     num_omp_parallels;
    int64_t     num_omp_tasks;
    int64_t     num_gpu_runtime_calls;
    int64_t     start_time;
    int64_t     stop_time;
    int64_t     elapsed_time;
    int64_t     useful_time;
    int64_t     mpi_time;
    int64_t     omp_load_imbalance_time;
    int64_t     omp_scheduling_time;
    int64_t     omp_serialization_time;
    int64_t     gpu_runtime_time;
    int64_t     gpu_useful_time;
    int64_t     gpu_communication_time;
    int64_t     gpu_inactive_time;
    void        *_data;
} dlb_monitor_t;
 
typedef struct dlb_pop_metrics_t {
    char        name[DLB_MONITOR_NAME_MAX];
    int         num_cpus;
    int         num_mpi_ranks;
    int         num_nodes;
    float       avg_cpus;
    int         num_gpus;
    double      cycles;
    double      instructions;
    int64_t     num_measurements;
    int64_t     num_mpi_calls;
    int64_t     num_omp_parallels;
    int64_t     num_omp_tasks;
    int64_t     num_gpu_runtime_calls;
    int64_t     elapsed_time;
    int64_t     useful_time;
    int64_t     mpi_time;
    int64_t     omp_load_imbalance_time;
    int64_t     omp_scheduling_time;
    int64_t     omp_serialization_time;
    int64_t     gpu_runtime_time;
    double      min_mpi_normd_proc;
    double      min_mpi_normd_node;
    /* TBD */
    int64_t     gpu_useful_time;
    /* TBD */
    int64_t     gpu_communication_time;
    /* TBD: remove? */
    int64_t     gpu_inactive_time;
    /* TBD */
    int64_t     max_gpu_useful_time;
    /* TBD */
    int64_t     max_gpu_active_time;
    float       parallel_efficiency;
    float       mpi_parallel_efficiency;
    float       mpi_communication_efficiency;
    float       mpi_load_balance;
    float       mpi_load_balance_in;
    float       mpi_load_balance_out;
    float       omp_parallel_efficiency;
    float       omp_load_balance;
    float       omp_scheduling_efficiency;
    float       omp_serialization_efficiency;
    float       device_offload_efficiency;
    float       gpu_parallel_efficiency;
    float       gpu_load_balance;
    float       gpu_communication_efficiency;
    float       gpu_orchestration_efficiency;
} dlb_pop_metrics_t;
 
typedef struct dlb_node_metrics_t {
    char    name[DLB_MONITOR_NAME_MAX];
    int     node_id;
    int     processes_per_node;
    int64_t total_useful_time;
    int64_t total_mpi_time;
    int64_t max_useful_time;
    int64_t max_mpi_time;
    float   parallel_efficiency;
    float   communication_efficiency;
    float   load_balance;
} dlb_node_metrics_t;
 
typedef struct dlb_node_times_t {
    pid_t pid;
    int64_t mpi_time;
    int64_t useful_time;
} dlb_node_times_t;
 
#ifdef __cplusplus
extern "C"
{
#endif
 
/*********************************************************************************/
/*                                                                               */
/*  The following functions are intended to be called from 1st-party or          */
/*  3rd-party programs indistinctly; that is, DLB applications, or external      */
/*  profilers as long as they invoke DLB_TALP_Attach.                            */
/*                                                                               */
/*********************************************************************************/
 
/*********************************************************************************/
/*    TALP                                                                       */
/*********************************************************************************/
 
int DLB_TALP_Attach(void);
 
int DLB_TALP_Detach(void);
 
int DLB_TALP_GetNumCPUs(int *ncpus);
 
int DLB_TALP_GetPidList(int *pidlist, int *nelems, int max_len);
 
int DLB_TALP_GetTimes(int pid, double *mpi_time, double *useful_time);
 
int DLB_TALP_GetNodeTimes(const char *name, dlb_node_times_t *node_times_list,
        int *nelems, int max_len);
 
int DLB_TALP_QueryPOPNodeMetrics(const char *name, dlb_node_metrics_t *node_metrics);
 
 
/*********************************************************************************/
/*                                                                               */
/*  The functions declared below are intended to be called only from 1st-party   */
/*  programs, and they should return an error if they are called from external   */
/*  profilers.                                                                   */
/*                                                                               */
/*  DISCLAIMER: This header file may be split in two in the next major release.  */
/*                                                                               */
/*********************************************************************************/
 
/*********************************************************************************/
/*    TALP Monitoring Regions                                                    */
/*********************************************************************************/
 
dlb_monitor_t* DLB_MonitoringRegionGetGlobal(void);
 
dlb_monitor_t* DLB_MonitoringRegionGetImplicit(void)
    __attribute__((deprecated("DLB_MonitoringRegionGetGlobal")));
 
const dlb_monitor_t* DLB_MonitoringRegionGetMPIRegion(void)
    __attribute__((deprecated("DLB_MonitoringRegionGetGlobal")));
 
dlb_monitor_t* DLB_MonitoringRegionRegister(const char *name);
 
int DLB_MonitoringRegionReset(dlb_monitor_t *handle);
 
int DLB_MonitoringRegionStart(dlb_monitor_t *handle);
 
int DLB_MonitoringRegionStop(dlb_monitor_t *handle);
 
int DLB_MonitoringRegionReport(const dlb_monitor_t *handle);
 
int DLB_MonitoringRegionsUpdate(void);
 
int DLB_TALP_CollectPOPMetrics(dlb_monitor_t *monitor, dlb_pop_metrics_t *pop_metrics);
 
int DLB_TALP_CollectPOPNodeMetrics(dlb_monitor_t *monitor, dlb_node_metrics_t *node_metrics);
 
int DLB_TALP_CollectNodeMetrics(dlb_monitor_t *monitor, dlb_node_metrics_t *node_metrics)
    __attribute__((deprecated("DLB_TALP_CollectPOPNodeMetrics")));
 
#ifdef __cplusplus
}
#endif
 
 
#endif /* DLB_API_TALP_H */