#include <time.h>
#include <stdint.h>

Include dependency graph for dlb_talp.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	dlb_monitor_t

struct	dlb_pop_metrics_t

struct	dlb_node_metrics_t

struct	dlb_node_times_t

Macros
#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

Enumerations
enum	{ DLB_MONITOR_NAME_MAX = 128 }

Functions
int	DLB_TALP_Attach (void)
	Attach current process to DLB system as TALP administrator. More...

int	DLB_TALP_Detach (void)
	Detach current process from DLB system. More...

int	DLB_TALP_GetNumCPUs (int *ncpus)
	Get the number of CPUs in the node. More...

int	DLB_TALP_GetPidList (int pidlist, int nelems, int max_len)
	Get the list of running processes registered in the DLB system. More...

int	DLB_TALP_GetTimes (int pid, double mpi_time, double useful_time)
	Get the CPU time spent on MPI and useful computation for the given process. More...

int	DLB_TALP_GetNodeTimes (const char name, dlb_node_times_t node_times_list, int *nelems, int max_len)
	Get the list of raw times for the specified region. More...

int	DLB_TALP_QueryPOPNodeMetrics (const char name, dlb_node_metrics_t node_metrics)
	From either 1st or 3rd party, query node metrics for one region. More...

dlb_monitor_t *	DLB_MonitoringRegionGetGlobal (void)
	Get the pointer of the global application-wide Monitoring Region. More...

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)
	Register a new Monitoring Region, or obtain the associated pointer by name. More...

int	DLB_MonitoringRegionReset (dlb_monitor_t *handle)
	Reset monitoring region. More...

int	DLB_MonitoringRegionStart (dlb_monitor_t *handle)
	Start (or unpause) monitoring region. More...

int	DLB_MonitoringRegionStop (dlb_monitor_t *handle)
	Stop (or pause) monitoring region. More...

int	DLB_MonitoringRegionReport (const dlb_monitor_t *handle)
	Print a report to stderr of the monitoring region. More...

int	DLB_MonitoringRegionsUpdate (void)
	Update all monitoring regions. More...

int	DLB_TALP_CollectPOPMetrics (dlb_monitor_t monitor, dlb_pop_metrics_t pop_metrics)
	Perform an MPI collective communication to collect POP metrics. More...

int	DLB_TALP_CollectPOPNodeMetrics (dlb_monitor_t monitor, dlb_node_metrics_t node_metrics)
	Perform a node collective communication to collect TALP node metrics. More...

int	DLB_TALP_CollectNodeMetrics (dlb_monitor_t monitor, dlb_node_metrics_t node_metrics) __attribute__((deprecated("DLB_TALP_CollectPOPNodeMetrics")))

Macro Definition Documentation

◆ DLB_GLOBAL_REGION_NAME

#define DLB_GLOBAL_REGION_NAME "Global"

◆ DLB_GLOBAL_REGION

#define DLB_GLOBAL_REGION NULL

◆ DLB_MPI_REGION

#define DLB_MPI_REGION NULL /* deprecated in favor of DLB_GLOBAL_REGION */

◆ DLB_IMPLICIT_REGION

#define DLB_IMPLICIT_REGION NULL /* deprecated in favor of DLB_GLOBAL_REGION */

◆ DLB_LAST_OPEN_REGION

#define DLB_LAST_OPEN_REGION (void*)1

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Enumerator
DLB_MONITOR_NAME_MAX

Function Documentation

◆ DLB_TALP_Attach()

int DLB_TALP_Attach ( void )

Attach current process to DLB system as TALP administrator.

Returns: DLB_SUCCESS on success

Once the process is attached to DLB as TALP administrator, it may perform the below actions described in this file. This way, the process is able to obtain some TALP values such as time spent in computation or MPI for each of the DLB running processes.

◆ DLB_TALP_Detach()

int DLB_TALP_Detach ( void )

Detach current process from DLB system.

Returns: DLB_SUCCESS on success; DLB_ERR_NOSHMEM if cannot find shared memory to detach from

If previously attached, a process must call this function to correctly close internal DLB file descriptors and clean data.

◆ DLB_TALP_GetNumCPUs()

int DLB_TALP_GetNumCPUs ( int * ncpus )

Get the number of CPUs in the node.

Parameters

[out] ncpus the number of CPUs

Returns: DLB_SUCCESS on success

◆ DLB_TALP_GetPidList()

int DLB_TALP_GetPidList	(	int *	pidlist,
		int *	nelems,
		int	max_len
	)

Get the list of running processes registered in the DLB system.

Parameters

[out]	pidlist	The output list
[out]	nelems	Number of elements in the list
[in]	max_len	Max capacity of the list

Returns: DLB_SUCCESS on success; DLB_ERR_NOSHMEM if cannot find shared memory

◆ DLB_TALP_GetTimes()

int DLB_TALP_GetTimes	(	int	pid,
		double *	mpi_time,
		double *	useful_time
	)

Get the CPU time spent on MPI and useful computation for the given process.

Parameters

[in]	pid	target Process ID, or 0 if own process
[out]	mpi_time	CPU time spent on MPI in seconds
[out]	useful_time	CPU time spend on useful computation in seconds

Returns: DLB_SUCCESS on success; DLB_ERR_NOPROC if target pid is not registered in the DLB system; DLB_ERR_NOSHMEM if cannot find shared memory; DLB_ERR_NOTALP if target is own process and TALP is not enabled

◆ DLB_TALP_GetNodeTimes()

int DLB_TALP_GetNodeTimes	(	const char *	name,
		dlb_node_times_t *	node_times_list,
		int *	nelems,
		int	max_len
	)

Get the list of raw times for the specified region.

Parameters

[in]	name	Name to identify the region
[out]	node_times_list	The output list
[out]	nelems	Number of elements in the list
[in]	max_len	Max capacity of the list

Returns: DLB_SUCCESS on success; DLB_ERR_NOSHMEM if cannot find shared memory

Note: This function requires DLB_ARGS+=" --talp-external-profiler" even if it's called from 1st-party programs.

◆ DLB_TALP_QueryPOPNodeMetrics()

int DLB_TALP_QueryPOPNodeMetrics	(	const char *	name,
		dlb_node_metrics_t *	node_metrics
	)

From either 1st or 3rd party, query node metrics for one region.

Parameters

[in]	name	Name to identify the region
[out]	node_metrics	Allocated structure where the collected metrics will be stored

Returns: DLB_SUCCESS on success; DLB_ERR_NOENT if no data for the given name; DLB_ERR_NOSHMEM if cannot find shared memory

Note: This function requires DLB_ARGS+=" --talp-external-profiler" even if it's called from 1st-party programs.

◆ DLB_MonitoringRegionGetGlobal()

dlb_monitor_t * DLB_MonitoringRegionGetGlobal ( void )

Get the pointer of the global application-wide Monitoring Region.

Returns: monitor handle to be used on queries, or NULL if TALP is not enabled

◆ DLB_MonitoringRegionGetImplicit()

dlb_monitor_t * DLB_MonitoringRegionGetImplicit ( void )

◆ DLB_MonitoringRegionGetMPIRegion()

const dlb_monitor_t * DLB_MonitoringRegionGetMPIRegion ( void )

◆ DLB_MonitoringRegionRegister()

dlb_monitor_t * DLB_MonitoringRegionRegister ( const char * name )

Register a new Monitoring Region, or obtain the associated pointer by name.

Parameters

[in] name Name to identify the region

Returns: monitor handle to be used on subsequent calls, or NULL if TALP is not enabled

This function registers a new monitoring region or obtains the pointer to an already created region with the same name. The name "Global" is a special reserved name (case-insensitive); invoking this function with this name is equivalent as invoking DLB_MonitoringRegionGetGlobal(). Otherwise, the region name is treated case-sensitive.

◆ DLB_MonitoringRegionReset()

int DLB_MonitoringRegionReset ( dlb_monitor_t * handle )

Reset monitoring region.

Parameters

[in] handle Monitoring handle that identifies the region, or DLB_GLOBAL_REGION

Returns: DLB_SUCCESS on success; DLB_ERR_NOTALP if TALP is not enabled

Reset all values of the monitoring region except num_resets, which is incremented. If the region is open, discard all intermediate values and close it.

◆ DLB_MonitoringRegionStart()

int DLB_MonitoringRegionStart ( dlb_monitor_t * handle )

Start (or unpause) monitoring region.

Parameters

[in] handle Monitoring handle that identifies the region, or DLB_GLOBAL_REGION

Returns: DLB_SUCCESS on success; DLB_ERR_NOTALP if TALP is not enabled; DLB_ERR_PERM if this thread cannot start the monitoring region

Notes on multi-threading:

It is not safe to start or stop regions in OpenMP worksharing constructs.
If a region is started and stopped before the application has reached maximum parallelism (e.g., before a parallel construct), the unused resources will not be taken into account. This can result in higher OpenMP efficiencies than expected.

◆ DLB_MonitoringRegionStop()

int DLB_MonitoringRegionStop ( dlb_monitor_t * handle )

Stop (or pause) monitoring region.

Parameters

[in] handle Monitoring handle that identifies the region, DLB_GLOBAL_REGION, or DLB_LAST_OPEN_REGION

Returns: DLB_SUCCESS on success; DLB_ERR_NOTALP if TALP is not enabled; DLB_ERR_NOENT if DLB_LAST_OPEN_REGION does not match any region; DLB_ERR_PERM if this thread cannot stop the monitoring region

◆ DLB_MonitoringRegionReport()

int DLB_MonitoringRegionReport ( const dlb_monitor_t * handle )

Print a report to stderr of the monitoring region.

Parameters

[in] handle Monitoring handle that identifies the region, or DLB_GLOBAL_REGION

Returns: DLB_SUCCESS on success; DLB_ERR_NOTALP if TALP is not enabled

◆ DLB_MonitoringRegionsUpdate()

int DLB_MonitoringRegionsUpdate ( void )

Update all monitoring regions.

Returns: DLB_SUCCESS on success; DLB_ERR_PERM if this thread cannot update the monitoring region

Monitoring regions are only updated in certain situations, like when starting/stopping a region, or finalizing MPI. This routine forces the update of all started monitoring regions

◆ DLB_TALP_CollectPOPMetrics()

int DLB_TALP_CollectPOPMetrics	(	dlb_monitor_t *	monitor,
		dlb_pop_metrics_t *	pop_metrics
	)

Perform an MPI collective communication to collect POP metrics.

Parameters

[in]	monitor	Monitoring handle that identifies the region, or DLB_GLOBAL_REGION macro (NULL) if global application-wide region
[out]	pop_metrics	Allocated structure where the collected metrics will be stored

Returns: DLB_SUCCESS on success; DLB_ERR_NOTALP if TALP is not enabled

◆ DLB_TALP_CollectPOPNodeMetrics()

int DLB_TALP_CollectPOPNodeMetrics	(	dlb_monitor_t *	monitor,
		dlb_node_metrics_t *	node_metrics
	)

Perform a node collective communication to collect TALP node metrics.

Parameters

[in]	monitor	Monitoring handle that identifies the region, or DLB_GLOBAL_REGION macro (NULL) if global application-wide region
[out]	node_metrics	Allocated structure where the collected metrics will be stored

Returns: DLB_SUCCESS on success; DLB_ERR_NOTALP if TALP is not enabled; DLB_ERR_NOCOMP if support for barrier is disabled, i.e., –no-barrier

This functions performs a node barrier to collect the data. All processes that are running in the node must invoke this function.

◆ DLB_TALP_CollectNodeMetrics()

int DLB_TALP_CollectNodeMetrics	(	dlb_monitor_t *	monitor,
		dlb_node_metrics_t *	node_metrics
	)

Data Structures

Macros

Enumerations

Functions

Macro Definition Documentation

◆ DLB_GLOBAL_REGION_NAME

◆ DLB_GLOBAL_REGION

◆ DLB_MPI_REGION

◆ DLB_IMPLICIT_REGION

◆ DLB_LAST_OPEN_REGION

Enumeration Type Documentation

◆ anonymous enum

Function Documentation

◆ DLB_TALP_Attach()

◆ DLB_TALP_Detach()

◆ DLB_TALP_GetNumCPUs()

◆ DLB_TALP_GetPidList()

◆ DLB_TALP_GetTimes()

◆ DLB_TALP_GetNodeTimes()

◆ DLB_TALP_QueryPOPNodeMetrics()

◆ DLB_MonitoringRegionGetGlobal()

◆ DLB_MonitoringRegionGetImplicit()

◆ DLB_MonitoringRegionGetMPIRegion()

◆ DLB_MonitoringRegionRegister()

◆ DLB_MonitoringRegionReset()

◆ DLB_MonitoringRegionStart()

◆ DLB_MonitoringRegionStop()

◆ DLB_MonitoringRegionReport()

◆ DLB_MonitoringRegionsUpdate()

◆ DLB_TALP_CollectPOPMetrics()

◆ DLB_TALP_CollectPOPNodeMetrics()

◆ DLB_TALP_CollectNodeMetrics()