ibv_create_comp_cntr(3) Libibverbs Programmer’s Manual ibv_create_comp_cntr(3)

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

#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);

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.

struct ibv_comp_cntr {
    struct ibv_context *context;
    uint32_t handle;
};
Device context associated with the completion counter.
Kernel object handle for the completion counter.

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;
};
Bitmask specifying what fields in the structure are valid.
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.
Reserved for future use, for now must be 0.

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).

Completion counters are not supported on this device, or the requested operation is not supported for the given counter configuration.
Not enough resources to create the completion counter.
Invalid argument(s) passed.
The completion counter is still attached to a QP (ibv_destroy_comp_cntr() only).

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.

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)

Michael Margolin mrgolin@amazon.com

2026-02-09 libibverbs