int ibv_destroy_qp(struct ibv_qp *qp);

Description

ibv_destroy_qp() destroys a Queue Pair.

When a QP is destroyed any outstanding Work Requests, in either the Send or Receive Queues, won't be processed anymore by the RDMA device and Work Completions won't be generated for them. It is up to the user to clean all of the associated resources of those Work Requests (i.e. memory buffers).

It is considered a good programming practice to modify the Queue Pair into the Error state and poll all of the relevant Work Completions prior to destroying a Queue Pair. Since destroying a Queue Pair does not guarantee that its Work Completions are removed from the CQ upon destruction. Even if the Work Completions are already in the CQ, it might not be possible to retrieve them. Doing so before resizing the CQ, attaching a new Queue Pair to the CQ or reopening the Queue Pair, will help avoiding CQ overflow. If the Queue Pair is associated with an SRQ, it is recommended to wait for the affiliated event IBV_EVENT_QP_LAST_WQE_REACHED
after modifying the Queue Pair to the Error state and prior to destroying a Queue Pair. Not doing so, may cause Work Request leakage. It is advised to perform the following steps when destroying a Queue Pair:

• Move the Queue Pair into the Error state
• Wait for the affiliated event IBV_EVENT_QP_LAST_WQE_REACHED

• Either:

• drain the CQ by calling ibv_poll_cq and either wait for CQ to be empty or the number of Poll CQ operations has exceeded CQ capacity size

or

• post another Work Request that will complete on the same CQ and wait for this Work Request return as a Wore Completion
• Destroy the QP by calling ibv_destroy_qp()

The destruction of an Unreliable Datagram Queue Pair will fail if it is still attached to a multicast group.

If there is any affiliated asynchronous event on that QP that was read, using ibv_get_async_event(), but still wasn't acknowledged, using ibv_ack_async_event(), calling to ibv_destroy_qp() will never end until that event will be acknowledged.

A QP can be destroyed at any state.

Parameters

Return Values

Examples

Create a QP and destroy it:

struct ibv_pd *pd;
struct ibv_cq *cq;
struct ibv_qp *qp;
struct ibv_qp_init_attr qp_init_attr;
 
memset(&qp_init_attr, 0, sizeof(qp_init_attr));
 
qp_init_attr.send_cq = cq;
qp_init_attr.recv_cq = cq;
qp_init_attr.qp_type = IBV_QPT_RC;
qp_init_attr.cap.max_send_wr  = 2;
qp_init_attr.cap.max_recv_wr  = 2;
qp_init_attr.cap.max_send_sge = 1;
qp_init_attr.cap.max_recv_sge = 1;
 
qp = ibv_create_qp(pd, &qp_init_attr);
if (!qp) {
	fprintf(stderr, "Error, ibv_create_qp() failed\n");
	return -1;
}
 
if (ibv_destroy_qp(qp)) {
	fprintf(stderr, "Error, ibv_destroy_qp() failed\n");
	return -1;
}

FAQs

ibv_destroy_qp() failed, what will happen to the multicast groups which this QP is attached to?

Nothing at all. You can continue working with them without any side-effect.

ibv_destroy_qp() failed, can I know to which multicast groups it is attached to and caused this failure?

No, currently the RDMA stack doesn’t have this capability.

Can I destroy a QP that holds outstanding Work Requests?

Yes, you can. When a QP is being destroyed, it doesn't matter if it contains Work Requests or not.

Can I destroy a QP at any state?

Yes, the QP can be destroyed at any state.

I called ibv_destroy_qp(), but it never ended. What happened?

There is at least one affiliated asynchronous event on that QP that was read without a proper acknowledgement.

Written by: Dotan Barak on December 28, 2012.on February 18, 2015.