IBV_GET_ASYNC_EVENT(3)

💖 ibv_get_async_event, ibv_ack_async_event — bestie's guide to grabbing & acking async events 💖

okay so ✨ welcome to the Libibverbs Programmer's Manual, the corner of the docs where we talk about RDMA async events and honestly? it's giving main character energy. two functions, one vibe: ibv_get_async_event grabs an event, ibv_ack_async_event says "heard, ty bestie, we're done here." 💅

---

✨ NAME ✨

ibv_get_async_event, ibv_ack_async_event — get or acknowledge asynchronous events 🦋

---

🌸 SYNOPSIS 🌸

#include <infiniband/verbs.h>

int ibv_get_async_event(struct ibv_context *context,
                        struct ibv_async_event *event);

void ibv_ack_async_event(struct ibv_async_event *event);

---

🎀 DESCRIPTION 🎀

ibv_get_async_event() waits for the next async event of the RDMA device context context, and hands it back through the pointer event. That event is an ibv_async_event struct, and it's defined right there in <infiniband/verbs.h> — no cap, go look:

struct ibv_async_event {
        union {
                struct ibv_cq  *cq;             /* CQ that got the event */
                struct ibv_qp  *qp;             /* QP that got the event */
                struct ibv_srq *srq;            /* SRQ that got the event */
                struct ibv_wq  *wq;             /* WQ that got the event */
                int             port_num;       /* port number that got the event */
        } element;
        enum ibv_event_type     event_type;     /* type of the event */
};

here's the tea ☕: only one member of that element union is actually valid at a time, and which one it is depends on the event_type member of the struct. so like, check event_type first, then go touch the union. iykyk.

event_type is gonna be one of the following events, and yes we're listing them ALL because they're all iconic in their own way:

👑 QP events

• IBV_EVENT_QP_FATAL — bestie… an error occurred on a QP and it transitioned to error state 😭
• IBV_EVENT_QP_REQ_ERR — Invalid Request Local Work Queue Error
• IBV_EVENT_QP_ACCESS_ERR — Local access violation error 💀
• IBV_EVENT_COMM_EST — Communication was established on a QP ✨ (good news era)
• IBV_EVENT_SQ_DRAINED — the Send Queue was drained of outstanding messages in progress
• IBV_EVENT_PATH_MIG — a connection has migrated to the alternate path 🌈
• IBV_EVENT_PATH_MIG_ERR — a connection failed to migrate to the alternate path 🙈
• IBV_EVENT_QP_LAST_WQE_REACHED — Last WQE Reached on a QP associated with an SRQ

💜 CQ events

• IBV_EVENT_CQ_ERR — CQ is in error (CQ overrun) 💀

🌸 SRQ events

• IBV_EVENT_SRQ_ERR — an error occurred on an SRQ 😭
• IBV_EVENT_SRQ_LIMIT_REACHED — the SRQ limit was reached

🧚 WQ events

• IBV_EVENT_WQ_FATAL — an error occurred on a WQ and it transitioned to error state

⭐ Port events

• IBV_EVENT_PORT_ACTIVE — Link became active on a port 🔥
• IBV_EVENT_PORT_ERR — Link became unavailable on a port 😭
• IBV_EVENT_LID_CHANGE — LID was changed on a port
• IBV_EVENT_PKEY_CHANGE — P_Key table was changed on a port
• IBV_EVENT_SM_CHANGE — SM was changed on a port
• IBV_EVENT_CLIENT_REREGISTER — SM sent a CLIENT_REREGISTER request to a port
• IBV_EVENT_GID_CHANGE — GID table was changed on a port

🫶 CA events

• IBV_EVENT_DEVICE_FATAL — CA is in FATAL state 💀
• IBV_EVENT_DEVICE_SPEED_CHANGE — speed changed on one or many ports of the device, due to configuration or state changes

and then ibv_ack_async_event() — it acknowledges the async event event. that's it, that's the whole job. queen behavior, minimal effort, maximum importance. 👑

---

🦋 RETURN VALUE 🦋

ibv_get_async_event() returns 0 on success, and -1 on error.

ibv_ack_async_event() returns no value. (it simply does not participate in the return value economy 💅)

---

🌟 NOTES 🌟

⚠️ listen up, this one matters: ALL async events that ibv_get_async_event() returns must be acknowledged using ibv_ack_async_event(). every single one. no skipping. no "i'll do it later." the events are watching. 👀

and here's why that's not just a rule for the sake of rules: to avoid races, destroying an object (CQ, SRQ or QP) will wait for all affiliated events for that object to be acknowledged. this avoids a situation where an application retrieves an affiliated event after the corresponding object has already been destroyed. so like, the destroy call is literally sitting there waiting on you to ack. don't leave it on read. 😭

also important: ibv_get_async_event() is a blocking function. it blocks. it waits. it's patient. so if multiple threads call this function simultaneously, then when an async event occurs, only one thread will receive it — and ngl, it is not possible to predict which thread will receive it. mystery thread. chaos thread. nobody knows. 🙈

---

✨ EXAMPLES ✨

okay so here's a code example that demonstrates one possible way to work with async events in non-blocking mode. it performs the following steps:

1. Set the async events queue work mode to be non-blocked
2. Poll the queue until it has an async event
3. Get the async event and ack it

and here's the code, verbatim, because we do not freestyle code in this house:

/* change the blocking mode of the async event queue */
flags = fcntl(ctx->async_fd, F_GETFL);
rc = fcntl(ctx->async_fd, F_SETFL, flags | O_NONBLOCK);
if (rc < 0) {
        fprintf(stderr, "Failed to change file descriptor of async event queue\n");
        return 1;
}

/*
 * poll the queue until it has an event and sleep ms_timeout
 * milliseconds between any iteration
 */
my_pollfd.fd      = ctx->async_fd;
my_pollfd.events  = POLLIN;
my_pollfd.revents = 0;

do {
        rc = poll(&my_pollfd, 1, ms_timeout);
} while (rc == 0);
if (rc < 0) {
        fprintf(stderr, "poll failed\n");
        return 1;
}

/* Get the async event */
if (ibv_get_async_event(ctx, &async_event)) {
        fprintf(stderr, "Failed to get async_event\n");
        return 1;
}

/* Ack the event */
ibv_ack_async_event(&async_event);

---

🌈 SEE ALSO 🌈

• ibv_open_device(3)

---

💖 AUTHORS 💖

Dotan Barak <dotanba@gmail.com>

---

and that's the whole page bestie!! 🫶 this libibverbs manual entry is dated 2006-10-31, brought to you by libibverbs, and honestly it's been serving reliable async-event knowledge since before most of us could read. stan. ✨💅🎀