libibverbs/man/ibv_create_comp_cntr.3.md

---
date: 2026-02-09
footer: libibverbs
header: "Libibverbs Programmer's Manual"
layout: page
license: 'Licensed under the OpenIB.org BSD license (FreeBSD Variant) - See COPYING.md'
section: 3
title: ibv_create_comp_cntr
tagline: Verbs
---

# NAME

**ibv_create_comp_cntr**, **ibv_destroy_comp_cntr** - Create or destroy a
completion counter

**ibv_set_comp_cntr**, **ibv_set_err_comp_cntr** - Set the value of a
completion or error counter

**ibv_inc_comp_cntr**, **ibv_inc_err_comp_cntr** - Increment a completion or
error counter

**ibv_read_comp_cntr**, **ibv_read_err_comp_cntr** - Read the value of a
completion or error counter

# SYNOPSIS

```c
#include <infiniband/verbs.h>

struct ibv_comp_cntr *ibv_create_comp_cntr(struct ibv_context *context,
                                           struct ibv_comp_cntr_init_attr *cc_attr);

int ibv_destroy_comp_cntr(struct ibv_comp_cntr *comp_cntr);

int ibv_set_comp_cntr(struct ibv_comp_cntr *comp_cntr, uint64_t value);
int ibv_set_err_comp_cntr(struct ibv_comp_cntr *comp_cntr, uint64_t value);
int ibv_inc_comp_cntr(struct ibv_comp_cntr *comp_cntr, uint64_t amount);
int ibv_inc_err_comp_cntr(struct ibv_comp_cntr *comp_cntr, uint64_t amount);
int ibv_read_comp_cntr(struct ibv_comp_cntr *comp_cntr, uint64_t *value);
int ibv_read_err_comp_cntr(struct ibv_comp_cntr *comp_cntr, uint64_t *value);
```

# DESCRIPTION

Completion counters provide a lightweight completion mechanism as an
alternative or extension to completion queues (CQs). Rather than generating
individual completion queue entries, a completion counter tracks the aggregate
number of completed operations. This makes them well suited for applications
that need to know how many requests have completed without requiring
per-request details, such as credit based flow control or tracking responses
from remote peers.

Each completion counter maintains two distinct 64-bit values: a completion
count that is incremented on successful completions, and an error count that
is incremented when operations complete in error.

**ibv_create_comp_cntr**() allocates a new completion counter for the RDMA
device context *context*. The properties of the counter are defined by
*cc_attr*. The maximum number of completion counters a device supports is
reported by **ibv_query_comp_cntr_caps**(3).

**ibv_destroy_comp_cntr**() releases all resources associated with the
completion counter *comp_cntr*. The counter must not be attached to any QP
when destroyed.

**ibv_set_comp_cntr**() sets the completion count of *comp_cntr* to *value*.

**ibv_set_err_comp_cntr**() sets the error count of *comp_cntr* to *value*.

**ibv_inc_comp_cntr**() increments the completion count of *comp_cntr* by
*amount*.

**ibv_inc_err_comp_cntr**() increments the error count of *comp_cntr* by
*amount*.

**ibv_read_comp_cntr**() reads the current completion count of *comp_cntr*
into *value*.

**ibv_read_err_comp_cntr**() reads the current error count of *comp_cntr*
into *value*.

# ARGUMENTS

## ibv_comp_cntr

```c
struct ibv_comp_cntr {
	struct ibv_context *context;
	uint32_t handle;
};
```

*context*
:	Device context associated with the completion counter.

*handle*
:	Kernel object handle for the completion counter.

## ibv_comp_cntr_init_attr

```c
enum ibv_comp_cntr_type {
	IBV_COMP_CNTR_TYPE_WRS,
	IBV_COMP_CNTR_TYPE_BYTES,
};

struct ibv_comp_cntr_init_attr {
	uint32_t comp_mask;
	enum ibv_comp_cntr_type type;
	uint32_t flags;
};
```

*comp_mask*
:	Bitmask specifying what fields in the structure are valid.

*type*
:	The counting mode for the completion counter. Not all devices support
	all modes.
	**IBV_COMP_CNTR_TYPE_WRS** counts completed work requests (default).
	**IBV_COMP_CNTR_TYPE_BYTES** counts completed bytes.

*flags*
:	Reserved for future use, for now must be 0.

# RETURN VALUE

**ibv_create_comp_cntr**() returns a pointer to the allocated ibv_comp_cntr
object, or NULL if the request fails (and sets errno to indicate the failure
reason).

**ibv_destroy_comp_cntr**(), **ibv_set_comp_cntr**(),
**ibv_set_err_comp_cntr**(), **ibv_inc_comp_cntr**(),
**ibv_inc_err_comp_cntr**(), **ibv_read_comp_cntr**(), and
**ibv_read_err_comp_cntr**() return 0 on success, or the value of errno on
failure (which indicates the failure reason).

# ERRORS

ENOTSUP
:	Completion counters are not supported on this device, or the
	requested operation is not supported for the given counter
	configuration.

ENOMEM
:	Not enough resources to create the completion counter.

EINVAL
:	Invalid argument(s) passed.

EBUSY
:	The completion counter is still attached to a QP
	(**ibv_destroy_comp_cntr**() only).

# NOTES

Counter values must only be updated using **ibv_set_comp_cntr**(),
**ibv_set_err_comp_cntr**(), **ibv_inc_comp_cntr**(), or
**ibv_inc_err_comp_cntr**().

Updates made to counter values (e.g. via **ibv_set_comp_cntr**() or
**ibv_inc_comp_cntr**()) may not be immediately visible when reading the
counter via **ibv_read_comp_cntr**() or **ibv_read_err_comp_cntr**(). A small
delay may occur between the update and the observed value. However, the final
updated value will eventually be reflected.

Applications should ensure that the counter value is stable before calling
**ibv_set_comp_cntr**() or **ibv_set_err_comp_cntr**(). Otherwise, concurrent
updates may be lost.

# SEE ALSO

**ibv_query_comp_cntr_caps**(3), **ibv_qp_attach_comp_cntr**(3),
**efadv_create_comp_cntr**(3), **ibv_create_cq**(3), **ibv_create_cq_ex**(3),
**ibv_create_qp**(3)

# AUTHORS

Michael Margolin <mrgolin@amazon.com>