rpma_cq_get_wc(3)

💖 rpma_cq_get_wc — receive one or more completions 💖

okay bestie, welcome to the RPMA Programmer's Manual ✨ this one's about rpma_cq_get_wc(3) and it's literally the function that goes and collects your completions for you, like a little fairy godmother but for work completions 🧚 no cap.

---

✨ SYNOPSIS ✨

#include <librpma.h>

struct rpma_cq;
struct ibv_wc;

int rpma_cq_get_wc(struct rpma_cq *cq, int num_entries, struct ibv_wc *wc,
                int *num_entries_got);

---

🌸 DESCRIPTION 🌸

so rpma_cq_get_wc() polls the CQ for completions and hands you back the first num_entries of them — or literally all the available completions if the CQ has fewer than that number 🫶 — dropped right into the wc array, exactly like ibv_poll_cq(3) does. same energy, fr fr.

the wc argument is a pointer to an array of ibv_wc structs, as defined in <infiniband/verbs.h>. and the number of completions you actually got? that goes into the num_entries_got argument — but only if it's not NULL. 👀

heads up: num_entries_got can be NULL only if num_entries equals 1. that's the rule, periodt.

also know that all operations generate completions on error. and the operations posted with the RPMA_F_COMPLETION_ALWAYS flag? they generate completions on success too 💅.

ngl there's a little trap here that you need to know about: if the cq you're passing in is the main CQ, and the receive CQ is present on the same connection, this function won't return IBV_WC_RECV and IBV_WC_RECV_RDMA_WITH_IMM at any time. like, ever. 😭 the receive CQ has to be used instead to collect those completions. go check rpma_conn_get_rcq(3) for the details about the receive CQ — iykyk 🦋

---

⭐ RETURN VALUE ⭐

rpma_cq_get_wc() returns 0 on success, or a negative error code on failure. 💀

on success it saves all got completions and their number into wc and num_entries_got respectively — cute, tidy, slay. ✨

but if the status of a completion is not equal to IBV_WC_SUCCESS, then only the following attributes are valid: wr_id, status, qp_num, and vendor_err. that's it. don't go reading the other fields, bestie, they're not giving anything 💀

---

🔥 ERRORS 🔥

rpma_cq_get_wc() can fail with the following errors:

• RPMA_E_INVAL — num_entries < 1, cq or wc is NULL, or num_entries > 1 and num_entries_got is NULL
• RPMA_E_NO_COMPLETION — no completions available 🙈
• RPMA_E_PROVIDER — ibv_poll_cq(3) failed with a provider error
• RPMA_E_UNKNOWN — ibv_poll_cq(3) failed but no provider error is available

---

🎀 SEE ALSO 🎀

rpma_conn_get_cq(3), rpma_conn_get_rcq(3), rpma_conn_req_recv(3), rpma_cq_wait(3), rpma_cq_get_fd(3), rpma_flush(3), rpma_read(3), rpma_recv(3), rpma_send(3), rpma_send_with_imm(3), rpma_write(3), rpma_atomic_write(3), rpma_write_with_imm(3), librpma(7) and https://pmem.io/rpma/

---

and that's the whole page, bestie!! 💖 this one came from the RPMA crew, dated 01 April 2024 — go forth and poll responsibly, you absolute icon 👑✨