ibv_create_comp_cntr(3)

💅 ibv_create_comp_cntr(3)

okay bestie, welcome to ibv_create_comp_cntr(3) from the Libibverbs Programmer’s Manual. We’re doing completion counters today, and honestly? They’re kinda iconic. Creating, destroying, setting, incrementing, reading — the whole group chat is here. ✨

---

✨ 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 🌸

#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 are giving lightweight completion mechanism energy — they work as an alternative or an extension to completion queues (CQs). Instead of generating individual completion queue entries, a completion counter tracks the aggregate number of completed operations. That makes them super well suited for apps that just need to know how many requests have completed without needing per-request details — think credit based flow control or tracking responses from remote peers. iykyk. 💅

Each completion counter maintains two distinct 64-bit values: a completion count that gets incremented on successful completions, and an error count that gets incremented when operations complete in error. Two counters, two vibes, zero confusion. 🎀

• 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. No sneaky attachments, bestie. 🫶
• 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

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

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(). Periodt.
• 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. So like… give it a sec, bestie. 😭
• 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. Protect your peace and your counter values. 🫶

---

🌈 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

---

mwah 💋 — this page came from libibverbs, dated 2026-02-09. slay and stay hydrated. 💖✨