rpma_recv(3)

📦
version 1.3.0 · 3 versions
, in ubuntu noble

💖 rpma_recv — the RPMA Programmer's Manual, bestie edition 💖

okay so we're in librpma land and the function we're obsessing over today is rpma_recv(3) from the RPMA Programmer's Manual. sit down, grab a strawberry 🍓, and let's get into it.

✨ NAME ✨

rpma_recv — initiate the receive operation. that's it, that's the whole vibe. you're kicking off a receive, she's giving main character energy 🎀

🌸 SYNOPSIS 🌸

#include <librpma.h>

struct rpma_conn;
struct rpma_mr_local;
int rpma_recv(struct rpma_conn *conn, struct rpma_mr_local *dst, size_t offset, size_t len,
                const void *op_context);

🦋 DESCRIPTION 🦋

so rpma_recv() initiates the receive operation, which literally just means: it prepares a buffer for a message that's gonna get sent from the other side of the connection. think of it as setting out a lil plate 🍽️ before the food arrives. for the send-side lore, go peek at rpma_send(3).

here's the tea: every single buffer you prepare via rpma_recv(3) joins one big unordered set. no queue, no line, no "excuse me I was here first". when a message shows up, it gets dropped into one of the buffers that are waiting, and a completion for the receive operation gets generated. which buffer? doesn't matter. that's the point. ✨

and yes, a buffer for an incoming message has to be prepared beforehand. you can't be out here receiving into a buffer you haven't prepped. that's not a thing. 🙈

also, the order of buffers in the set does NOT affect the order of the completions of receive operations you get via rpma_cq_get_wc(3). set order ≠ completion order. do not conflate them, bestie, that's how you end up crying at 3am. 😭

op_context? it comes back to you in the wr_id field of the completion (struct ibv_wc). so it's your lil note-to-self that gets handed right back. 🫶

⚠️ NOTE ⚠️

in the RDMA standard, receive requests form an ordered queue. the RPMA does NOT inherit this guarantee.

bestie. read that again. it is NOT inherited. if you're coming from RDMA expecting that ordering, you're gonna have a bad time. 💀

🎀 RETURN VALUE 🎀

rpma_recv() returns 0 on success, or a negative error code on failure. zero is the slay, negative is the nay. 💅

💀 ERRORS 💀

rpma_recv() can fail with these, and only these:

  • RPMA_E_INVAL — conn == NULL
  • RPMA_E_INVAL — dst == NULL && (offset != 0 || len != 0)
  • RPMA_E_PROVIDER — ibv_post_recv(3) failed

👑 SEE ALSO 👑

and that's the whole page, no cap. this lil masterpiece is brought to you by RPMA 🌈, dated 01 April 2024 — go forth and receive responsibly, queen. 👑💖✨

📦 where this page comes from