ibv_create_cq, ibv_destroy_cq

Creates or destroys a completion queue (CQ).

Syntax

#include <rdma/verbs.h>
struct ibv_cq *ibv_create_cq(struct ibv_context *context, int cqe, void *cq_context, struct ibv_comp_channel *channel, int comp_vector)
int ibv_destroy_cq(struct ibv_cq *cq)

Description

ibv_create_cq creates a completion queue (CQ). A completion queue holds completion queue events (CQE). Each Queue Pair (QP) has an associated send and receive CQ. A single CQ can be shared for sending, receiving, and sharing across multiple QPs.

The parameter cqe defines the minimum size of the queue. The actual size of the queue might be larger than the specified value.

The parameter cq_context is a user defined value. If specified during CQ creation, this value is returned as a parameter in ibv_get_cq_event when using a completion channel (CC).

The parameter channel is used to specify a CC. A CQ is merely a queue that does not have a built in notification mechanism. When using a polling paradigm for CQ processing, a CC is not required. The user simply polls the CQ at regular intervals. However, if you wish to use a pend paradigm, a CC is required. The CC is a mechanism that allows the user to be notified that a new CQE is on the CQ.

The CQ will use the completion vector comp_vector for signaling completion events; it must be at least zero and less than context->num_comp_vectors.

ibv_destroy_cq() destroys the CQ cq.

Notes:
  • ibv_create_cq() might create a CQ with size greater than or equal to the requested size. Check the cqe attribute in the returned CQ for the actual size.
  • ibv_destroy_cq() fails if any queue pair is still associated with this CQ.

Parameters

context struct ibv_context from ibv_open_device.
cqe Minimum number of entries CQ supports.
cq_context (Optional) User defined value returned with completion events.
channel (Optional) Completion channel.
comp_vector (Optional) Completion vector.

Return Value

ibv_create_cq() returns a pointer to the CQ, or NULL if the request fails.

ibv_destroy_cq() returns 0 on success, or the value of errno on failure (which indicates the failure reason).

[ Feedback ]