3 .TH IBV_GET_CQ_EVENT 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual"
5 ibv_get_cq_event, ibv_ack_cq_events \- get and acknowledge completion queue (CQ) events
9 .B #include <infiniband/verbs.h>
11 .BI "int ibv_get_cq_event(struct ibv_comp_channel " "*channel" ,
12 .BI " struct ibv_cq " "**cq" ", void " "**cq_context" );
14 .BI "void ibv_ack_cq_events(struct ibv_cq " "*cq" ", unsigned int " "nevents" );
19 waits for the next completion event in the completion event channel
23 with the CQ that got the event and
25 with the CQ's context\fR.
27 .B ibv_ack_cq_events()
35 returns 0 on success, and \-1 on error.
37 .B ibv_ack_cq_events()
40 All completion events that
42 returns must be acknowledged using
43 .B ibv_ack_cq_events()\fR.
44 To avoid races, destroying a CQ will wait for all completion events to
45 be acknowledged; this guarantees a one-to-one correspondence between
46 acks and successful gets.
49 .B ibv_ack_cq_events()
50 may be relatively expensive in the datapath, since it must take a
51 mutex. Therefore it may be better to amortize this cost by
52 keeping a count of the number of events needing acknowledgement and
53 acking several completion events in one call to
54 .B ibv_ack_cq_events()\fR.
56 The following code example demonstrates one possible way to work with
57 completion events. It performs the following steps:
63 2. Requests for notification upon a new (first) completion event
65 Stage II: Completion Handling Routine
67 3. Wait for the completion event and ack it
69 4. Request for notification upon the next completion event
73 Note that an extra event may be triggered without having a
74 corresponding completion entry in the CQ. This occurs if a completion
75 entry is added to the CQ between Step 4 and Step 5, and the CQ is then
76 emptied (polled) in Step 5.
79 cq = ibv_create_cq(ctx, 1, ev_ctx, channel, 0);
81 fprintf(stderr, "Failed to create CQ\en");
85 /* Request notification before any completion can be created */
86 if (ibv_req_notify_cq(cq, 0)) {
87 fprintf(stderr, "Couldn't request CQ notification\en");
95 /* Wait for the completion event */
96 if (ibv_get_cq_event(channel, &ev_cq, &ev_ctx)) {
97 fprintf(stderr, "Failed to get cq_event\en");
102 ibv_ack_cq_events(ev_cq, 1);
104 /* Request notification upon the next completion event */
105 if (ibv_req_notify_cq(ev_cq, 0)) {
106 fprintf(stderr, "Couldn't request CQ notification\en");
110 /* Empty the CQ: poll all of the completions from the CQ (if any exist) */
112 ne = ibv_poll_cq(cq, 1, &wc);
114 fprintf(stderr, "Failed to poll completions from the CQ\en");
118 /* there may be an extra event with no completion in the CQ */
122 if (wc.status != IBV_WC_SUCCESS) {
123 fprintf(stderr, "Completion with status 0x%x was found\en", wc.status);
129 The following code example demonstrates one possible way to work with
130 completion events in non-blocking mode. It performs the following
133 1. Set the completion event channel to be non-blocked
135 2. Poll the channel until there it has a completion event
137 3. Get the completion event and ack it
140 /* change the blocking mode of the completion channel */
141 flags = fcntl(channel->fd, F_GETFL);
142 rc = fcntl(channel->fd, F_SETFL, flags | O_NONBLOCK);
144 fprintf(stderr, "Failed to change file descriptor of completion event channel\en");
150 * poll the channel until it has an event and sleep ms_timeout
151 * milliseconds between any iteration
153 my_pollfd.fd = channel->fd;
154 my_pollfd.events = POLLIN;
155 my_pollfd.revents = 0;
158 rc = poll(&my_pollfd, 1, ms_timeout);
161 fprintf(stderr, "poll failed\en");
166 /* Wait for the completion event */
167 if (ibv_get_cq_event(channel, &ev_cq, &ev_ctx)) {
168 fprintf(stderr, "Failed to get cq_event\en");
173 ibv_ack_cq_events(ev_cq, 1);
177 .BR ibv_create_comp_channel (3),
178 .BR ibv_create_cq (3),
179 .BR ibv_req_notify_cq (3),
185 .RI < dotanb@mellanox.co.il >