ibv_get_async_event, ibv_ack_async_event

Gets or acknowledges asynchronous events.

Syntax

#include <rdma/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 returns it through the pointer, event, which is an ibv_async_event struct, as defined in <rdma/verbs.h>.

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  (Not Supported)*/
                int		port_num;					/* port number that got the event */
        } element;
        enum ibv_event_type     event_type;     /* type of the event */
};

The function ibv_create_qp() updates the qp_init_attr->cap struct with the actual QP values of the QP that was created; the values will be greater than or equal to the values requested. ibv_destroy_qp() destroys the QP qp.

One member of the element union is valid, depending on the event_type member of the structure. event_type is one of the following events:
QP events  
IBV_EVENT_QP_FATAL Error occurred on a QP and it transitions 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 is established on a QP.
IBV_EVENT_SQ_DRAINED Send Queue is drained of outstanding messages in progress.
IBV_EVENT_PATH_MIG A connection is migrated to an alternate path.
IBV_EVENT_PATH_MIG_ERR A connection failed to migrate to the alternate path.
CQ events  
IBV_EVENT_CQ_ERR CQ is in error (CQ overrun).
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 is changed on a port.
IBV_EVENT_PKEY_CHANGE The P_Key table is changed on a port.
CA events  
IBV_EVENT_DEVICE_FATAL CA is in FATAL state.

ibv_ack_async_event() acknowledges the async event, event.

Notes:
  • All async events that ibv_get_async_event() returns must be acknowledged using ibv_ack_async_event(). To avoid races, destroying an object (CQor QP) will wait for all affiliated events for the object to be acknowledged; this avoids an application retrieving an affiliated event after the corresponding object has already been destroyed.
  • The ibv_get_async_event() function is a blocking function. If multiple threads call this function simultaneously, then when an async event occurs, only one thread will receive it, and it is not possible to predict which thread receives it.

Input Data

struct ibv_context *context struct ibv_context from ibv_open_device.
struct ibv_async_event *event event pointer.

Return Value

ibv_get_async_event() returns 0 on success, and -1 if the request fails.

ibv_ack_async_event() returns no value.

Example

The following code example demonstrates one possible way to work with async events in nonblocking mode. It performs the following steps:
  1. Sets the async events queue in non-blocked work mode.
  2. Polls the queue until it has an async event.
  3. Gets the async event and acknowledges it.
/* 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 &lt; 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);
Parent topic: Event Management
[ Feedback ]