mpi_sync_clocks documentation — mpi_sync

This is the public API for mpi_sync_clocks, the library to get a clock consistently synchronized accross MPI processes. More...

Collaboration diagram for mpi_sync_clocks public API.:

Modules
	functions to deal with local clocks.
	Clock backends are defined here.

	sync clocks with generic backend.
	mpi_sync_clocks may use different backends for synchronization.

typedef struct sync_clocks_generic_s *	mpi_sync_clocks_t
	opaque type for MPI sync clocks More...

static mpi_sync_clocks_t	mpi_sync_clocks_init (MPI_Comm comm)
	create an MPI sync clock object on the given communicator (collective operation) More...

static void	mpi_sync_clocks_shutdown (mpi_sync_clocks_t p_clocks)
	destroy the given clock More...

static double	mpi_sync_clocks_get_time_usec (mpi_sync_clocks_t p_clocks)
	get local time, in usec. More...

static double	mpi_sync_clocks_get_time_origin_usec (sync_clocks_generic_t p_clocks)
	get origin of local time, in usec. More...

static double	mpi_sync_clocks_local_to_global (mpi_sync_clocks_t p_clocks, double local_time)
	convert local time to global time More...

static double	mpi_sync_clocks_remote_to_global (mpi_sync_clocks_t p_clocks, int rank, double remote_time)
	convert remote local time to global time More...

static double	mpi_sync_clocks_global_to_local (mpi_sync_clocks_t p_clocks, double global_time)
	convert global time to local time More...

static void	mpi_sync_clocks_synchronize (mpi_sync_clocks_t p_clocks)
	synchronize clocks (collective operation); must have been called before any clock conversion More...

static int	mpi_sync_clocks_barrier (mpi_sync_clocks_t p_clocks, double *barrier_local_time)
	a barrier with precise synchronization; return 0 in case of success, -1 if we missed the deadline; barrier_local_time returns the local time at which barrier was supposed to take place More...

Detailed Description

This is the public API for mpi_sync_clocks, the library to get a clock consistently synchronized accross MPI processes.

It is able to interpolate clocks, extrapolated, and perform a synchronized barrier: a barrier where all process are guaranteed to exit at the same time so as to be used for distributed performance measures such as MPI collective benchmark.

Usage is as follows:

init library with mpi_sync_clocks_init(). It returns an object of type mpi_sync_clocks_t which represents the instantiation of mpi_sync_clocks.
capture local time stamps with mpi_sync_clocks_get_time_usec(). It returns a clock that is local to the process, with time origin at init time.
synchronize clocks with mpi_sync_clocks_synchronize(). This is a blocking collective operation. It is required before any clock computation may be performed.
compute syncnronized times with mpi_sync_clocks_local_to_global() to convert local time stamps to global time stamps.

For a synchronized barrier, call mpi_sync_clocks_barrier().

Steps 3 & 4 may be repeated as needed.
Free resources with mpi_sync_clocks_shutdown()

See example bellow (from mpi_sync_clocks_basic.c):

/*
 * MPI sync clocks
 * Copyright (C) 2006-2024 (see AUTHORS file)
 *
 * This library 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 2.1 of the License, or (at your option) any later version.
 *
 * This library 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.
 */
 
#include <mpi.h>
 
#include <mpi_sync_clocks.h>
 
int main(int argc, char**argv)
{
  MPI_Init(&argc,&argv);
 
  int rank = -1;
  MPI_Comm_rank(MPI_COMM_WORLD, &rank);
 
  /* initialize sync clocks */
  mpi_sync_clocks_t p_clocks = mpi_sync_clocks_init(MPI_COMM_WORLD);
 
  /* get time before and after MPI_Barrier */
  double local_t1 = mpi_sync_clocks_get_time_usec(p_clocks);
  MPI_Barrier(MPI_COMM_WORLD);
  double local_t2 = mpi_sync_clocks_get_time_usec(p_clocks);
 
  /* synchronize clocks to interpolate t1 & t2 */
  mpi_sync_clocks_synchronize(p_clocks);
 
  printf("rank = %d; local_t1 = %g usec.; global = %g usec. [before MPI_Barrier]\n",
         rank, local_t1, mpi_sync_clocks_local_to_global(p_clocks, local_t1));
  printf("rank = %d; local_t2 = %g usec.; global = %g usec. [after MPI_Barrier]\n",
         rank, local_t2, mpi_sync_clocks_local_to_global(p_clocks, local_t2));
 
  /* get time before and after sync clocks barrier */
  double local_t3 = mpi_sync_clocks_get_time_usec(p_clocks);
  mpi_sync_clocks_barrier(p_clocks, NULL);
  double local_t4 = mpi_sync_clocks_get_time_usec(p_clocks);
 
  /* synchronize clocks to interpolate t2 & t3 */
  mpi_sync_clocks_synchronize(p_clocks);
 
  printf("rank = %d; local_t3 = %g usec.; global = %g usec.\n",
         rank, local_t3, mpi_sync_clocks_local_to_global(p_clocks, local_t3));
  printf("rank = %d; local_t4 = %g usec.; global = %g usec. [after sync clocks barrier]\n",
         rank, local_t4, mpi_sync_clocks_local_to_global(p_clocks, local_t4));
 
  /* shut down mpi sync clocks */
  mpi_sync_clocks_shutdown(p_clocks);
  MPI_Finalize();
  return 0;
}

Typedef Documentation

◆ mpi_sync_clocks_t

typedef struct sync_clocks_generic_s* mpi_sync_clocks_t

opaque type for MPI sync clocks

Definition at line 72 of file mpi_sync_clocks.h.

Function Documentation

◆ mpi_sync_clocks_barrier()

static int mpi_sync_clocks_barrier	(	mpi_sync_clocks_t	p_clocks,
		double *	barrier_local_time
	)

inlinestatic

a barrier with precise synchronization; return 0 in case of success, -1 if we missed the deadline; barrier_local_time returns the local time at which barrier was supposed to take place

Definition at line 205 of file mpi_sync_clocks.h.

References sync_clocks_generic_barrier().

Here is the call graph for this function: