MPI_T_PVAR_HANDLE_FREE(3)			     Open MPI				 MPI_T_PVAR_HANDLE_FREE(3)

       MPI_T_pvar_handle_alloc	<#mpi-t-pvar-handle-alloc>, MPI_T_pvar_handle_free - Allocate/free MPI performance
       variable handles

SYNTAX
   C Syntax
	  #include <mpi.h>

	  int MPI_T_pvar_handle_alloc(int session, int pvar_index, void *obj_handle,
				      MPI_T_pvar_handle *handle, int *count)

	  int MPI_T_pvar_handle_free(int session, MPI_T_pvar_handle *handle)

DESCRIPTION
       MPI_T_pvar_handle_alloc <#mpi-t-pvar-handle-alloc> binds the performance variable specified  in	pvar_index
       to the MPI object specified in obj_handle in the session identified by the parameter session. The object is
       passed  in  the	argument  obj_handle as an address to a local variable that stores the object’s handle. If
       MPI_T_pvar_get_info <#mpi-t-pvar-get-info> returns MPI_T_BIND_NO_OBJECT as the binding for the variable the
       obj_handle argument is ignored. The handle allocated to reference the variable is returned in the  argument
       handle.	Upon  successful  return,  count  contains  the	 number of elements (of the datatype returned by a
       previous MPI_T_pvar_get_info <#mpi-t-pvar-get-info> call) used to represent this variable.

       The value of pvar_index should be in the range 0 to num_pvar - 1, where num_pvar is the number of available
       performance variables as determined from a prior call to MPI_T_pvar_get_num <#mpi-t-pvar-get-num>. The type
       of the MPI object it references must be consistent with the type returned in the bind argument in  a  prior
       call to MPI_T_pvar_get_info <#mpi-t-pvar-get-info>.

       MPI_T_pvar_handle_free  frees  a handle allocated by MPI_T_pvar_handle_alloc <#mpi-t-pvar-handle-alloc> and
       sets the handle argument to MPI_T_PVAR_HANDLE_NULL.

ERRORS
       MPI_T_pvar_handle_alloc <#mpi-t-pvar-handle-alloc> will fail if:

       • MPI_T_ERR_NOT_INITIALIZED: The MPI Tools interface not initialized

       • MPI_T_ERR_INVALID_INDEX: The performance variable index is invalid

       • MPI_T_ERR_OUT_OF_HANDLES: No more handles available

       MPI_T_pvar_handle_free will fail if:

       • MPI_T_ERR_NOT_INITIALIZED: The MPI Tools interface not initialized

       • MPI_T_ERR_INVALID_HANDLE: The handle is invalid or the handle argument passed in is not  associated  with
	 the session argument

       See also:

	  • MPI_T_pvar_get_info <#mpi-t-pvar-get-info>

	  • MPI_T_pvar_get_num <#mpi-t-pvar-get-num>

Copyright
       2003-2026, The Open MPI Community

						   Mar 05, 2026				 MPI_T_PVAR_HANDLE_FREE(3)
