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
The ibv_create_cq() function 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 cqe parameter defines the minimum size of the queue. The actual size of the queue might be larger than the specified value.
The cq_context parameter is a user-defined value. If the value is specified during CQ creation, this value is returned as a parameter in the ibv_get_cq_event() function when using a completion channel (CC).
The channel parameter 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. Poll the CQ at regular intervals. However, if you want 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 uses the comp_vector parameter for
signaling completion events. It must be at least zero and less than
the context->num_comp_vectors parameter.
The ibv_destroy_cq() function destroys the CQ cq.
- The ibv_create_cq() function can create a CQ with a size greater than or equal to the requested size. You can determine the actual size of the function from the cqe attribute in the returned CQ.
- The ibv_destroy_cq() function fails if any queue pair is still associated with the CQ.
Parameters
| Item | Descriptor |
|---|---|
| context | The ibv_context struct for the ibv_open_device() function. |
| cqe | Minimum number of entries that CQ supports. |
| cq_context | (Optional) Specifies a user-defined value that is returned with completion events. |
| channel | (Optional) Specifies the completion channel. |
| comp_vector | (Optional) Specifies the completion vector. |
Return Value
The ibv_create_cq() function returns a pointer to the CQ, or NULL if the request fails.
The ibv_destroy_cq() function returns 0 on success, or the value errno on failure, which indicates the reason for failure.