---
name: "MPI_T_pvar_handle_free.openmpi"
section: "3"
platform: "linux"
package: "openmpi-doc"
version: "5.0.7-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/MPI_T_pvar_handle_free.openmpi"
---

# MPI\_T\_pvar\_handle\_free.openmpi(3)

*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* 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* 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* 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*. 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\_handle\_free* frees a handle allocated by *MPI\_T\_pvar\_handle\_alloc* and sets the *handle* argument to MPI\_T\_PVAR\_HANDLE\_NULL.

## ERRORS

*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\_num*

## COPYRIGHT

2003-2025, The Open MPI Community