.\" Automatically generated by Pandoc 3.10.2
.\"
.TH "ibv_create_comp_cntr" "3" "2026\-02\-09" "libibverbs" "Libibverbs Programmer\(cqs Manual"
.SH NAME
\f[B]ibv_create_comp_cntr\f[R], \f[B]ibv_destroy_comp_cntr\f[R] \-
Create or destroy a completion counter
.PP
\f[B]ibv_set_comp_cntr\f[R], \f[B]ibv_set_err_comp_cntr\f[R] \- Set the
value of a completion or error counter
.PP
\f[B]ibv_inc_comp_cntr\f[R], \f[B]ibv_inc_err_comp_cntr\f[R] \-
Increment a completion or error counter
.PP
\f[B]ibv_read_comp_cntr\f[R], \f[B]ibv_read_err_comp_cntr\f[R] \- Read
the value of a completion or error counter
.SH SYNOPSIS
.IP
.EX
#include \f[B]<infiniband/verbs.h>\f[R]

\f[B]struct\f[R] ibv_comp_cntr *ibv_create_comp_cntr(\f[B]struct\f[R] ibv_context *context,
                                           \f[B]struct\f[R] ibv_comp_cntr_init_attr *cc_attr);

int ibv_destroy_comp_cntr(\f[B]struct\f[R] ibv_comp_cntr *comp_cntr);

int ibv_set_comp_cntr(\f[B]struct\f[R] ibv_comp_cntr *comp_cntr, uint64_t value);
int ibv_set_err_comp_cntr(\f[B]struct\f[R] ibv_comp_cntr *comp_cntr, uint64_t value);
int ibv_inc_comp_cntr(\f[B]struct\f[R] ibv_comp_cntr *comp_cntr, uint64_t amount);
int ibv_inc_err_comp_cntr(\f[B]struct\f[R] ibv_comp_cntr *comp_cntr, uint64_t amount);
int ibv_read_comp_cntr(\f[B]struct\f[R] ibv_comp_cntr *comp_cntr, uint64_t *value);
int ibv_read_err_comp_cntr(\f[B]struct\f[R] ibv_comp_cntr *comp_cntr, uint64_t *value);
.EE
.SH 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.
.PP
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.
.PP
\f[B]ibv_create_comp_cntr\f[R]() allocates a new completion counter for
the RDMA device context \f[I]context\f[R].
The properties of the counter are defined by \f[I]cc_attr\f[R].
The maximum number of completion counters a device supports is reported
by \f[B]ibv_query_comp_cntr_caps\f[R](3).
.PP
\f[B]ibv_destroy_comp_cntr\f[R]() releases all resources associated with
the completion counter \f[I]comp_cntr\f[R].
The counter must not be attached to any QP when destroyed.
.PP
\f[B]ibv_set_comp_cntr\f[R]() sets the completion count of
\f[I]comp_cntr\f[R] to \f[I]value\f[R].
.PP
\f[B]ibv_set_err_comp_cntr\f[R]() sets the error count of
\f[I]comp_cntr\f[R] to \f[I]value\f[R].
.PP
\f[B]ibv_inc_comp_cntr\f[R]() increments the completion count of
\f[I]comp_cntr\f[R] by \f[I]amount\f[R].
.PP
\f[B]ibv_inc_err_comp_cntr\f[R]() increments the error count of
\f[I]comp_cntr\f[R] by \f[I]amount\f[R].
.PP
\f[B]ibv_read_comp_cntr\f[R]() reads the current completion count of
\f[I]comp_cntr\f[R] into \f[I]value\f[R].
.PP
\f[B]ibv_read_err_comp_cntr\f[R]() reads the current error count of
\f[I]comp_cntr\f[R] into \f[I]value\f[R].
.SH ARGUMENTS
.SS ibv_comp_cntr
.IP
.EX
\f[B]struct\f[R] ibv_comp_cntr {
    \f[B]struct\f[R] ibv_context *context;
    uint32_t handle;
};
.EE
.TP
\f[I]context\f[R]
Device context associated with the completion counter.
.TP
\f[I]handle\f[R]
Kernel object handle for the completion counter.
.SS ibv_comp_cntr_init_attr
.IP
.EX
\f[B]enum\f[R] ibv_comp_cntr_type {
    IBV_COMP_CNTR_TYPE_WRS,
    IBV_COMP_CNTR_TYPE_BYTES,
};

\f[B]struct\f[R] ibv_comp_cntr_init_attr {
    uint32_t comp_mask;
    \f[B]enum\f[R] ibv_comp_cntr_type type;
    uint32_t flags;
};
.EE
.TP
\f[I]comp_mask\f[R]
Bitmask specifying what fields in the structure are valid.
.TP
\f[I]type\f[R]
The counting mode for the completion counter.
Not all devices support all modes.
\f[B]IBV_COMP_CNTR_TYPE_WRS\f[R] counts completed work requests
(default).
\f[B]IBV_COMP_CNTR_TYPE_BYTES\f[R] counts completed bytes.
.TP
\f[I]flags\f[R]
Reserved for future use, for now must be 0.
.SH RETURN VALUE
\f[B]ibv_create_comp_cntr\f[R]() returns a pointer to the allocated
ibv_comp_cntr object, or NULL if the request fails (and sets errno to
indicate the failure reason).
.PP
\f[B]ibv_destroy_comp_cntr\f[R](), \f[B]ibv_set_comp_cntr\f[R](),
\f[B]ibv_set_err_comp_cntr\f[R](), \f[B]ibv_inc_comp_cntr\f[R](),
\f[B]ibv_inc_err_comp_cntr\f[R](), \f[B]ibv_read_comp_cntr\f[R](), and
\f[B]ibv_read_err_comp_cntr\f[R]() return 0 on success, or the value of
errno on failure (which indicates the failure reason).
.SH ERRORS
.TP
ENOTSUP
Completion counters are not supported on this device, or the requested
operation is not supported for the given counter configuration.
.TP
ENOMEM
Not enough resources to create the completion counter.
.TP
EINVAL
Invalid argument(s) passed.
.TP
EBUSY
The completion counter is still attached to a QP
(\f[B]ibv_destroy_comp_cntr\f[R]() only).
.SH NOTES
Counter values must only be updated using \f[B]ibv_set_comp_cntr\f[R](),
\f[B]ibv_set_err_comp_cntr\f[R](), \f[B]ibv_inc_comp_cntr\f[R](), or
\f[B]ibv_inc_err_comp_cntr\f[R]().
.PP
Updates made to counter values (e.g.\ via \f[B]ibv_set_comp_cntr\f[R]()
or \f[B]ibv_inc_comp_cntr\f[R]()) may not be immediately visible when
reading the counter via \f[B]ibv_read_comp_cntr\f[R]() or
\f[B]ibv_read_err_comp_cntr\f[R]().
A small delay may occur between the update and the observed value.
However, the final updated value will eventually be reflected.
.PP
Applications should ensure that the counter value is stable before
calling \f[B]ibv_set_comp_cntr\f[R]() or
\f[B]ibv_set_err_comp_cntr\f[R]().
Otherwise, concurrent updates may be lost.
.SH SEE ALSO
\f[B]ibv_query_comp_cntr_caps\f[R](3),
\f[B]ibv_qp_attach_comp_cntr\f[R](3),
\f[B]efadv_create_comp_cntr\f[R](3), \f[B]ibv_create_cq\f[R](3),
\f[B]ibv_create_cq_ex\f[R](3), \f[B]ibv_create_qp\f[R](3)
.SH AUTHORS
Michael Margolin \c
.MT mrgolin@amazon.com
.ME \c