MPI\_T\_PVAR\_HANDLE\_ALLOC(3) Open MPI MPI\_T\_PVAR\_HANDLE\_ALLOC(3)

MPI\_T\_pvar\_handle\_alloc, MPI\_T\_pvar\_handle\_free <#mpi-t-pvar-handle-free> - Allocate/free MPI performance variable handles

# [SYNTAX](#SYNTAX)

## [C 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](#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 &lt;#mpi-t-pvar-get-info&gt; 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 &lt;#mpi-t-pvar-get-info&gt; 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 &lt;#mpi-t-pvar-get-num&gt;. 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 &lt;#mpi-t-pvar-get-info&gt;.

MPI\_T\_pvar\_handle\_free &lt;#mpi-t-pvar-handle-free&gt; frees a handle allocated by MPI\_T\_pvar\_handle\_alloc and sets the *handle* argument to MPI\_T\_PVAR\_HANDLE\_NULL.

# [ERRORS](#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 &lt;#mpi-t-pvar-handle-free&gt; 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 &lt;#mpi-t-pvar-get-info&gt;
- MPI\_T\_pvar\_get\_num &lt;#mpi-t-pvar-get-num&gt;

# [Copyright](#Copyright)

2003-2026, The Open MPI Community

October 11, 2026

---

Document: MPI_T_pvar_handle_alloc(3) from openmpi-cuda-13.4 5.0.11-r1 (Chainguard OS)