.\" Extracted by src2man from /build/rpma-7QsoUa/rpma-0.11.0/src/include/librpma.h
.\" Text automatically generated by txt2man
.TH rpma_cq_get_completion 3 "11 February 2022" "RPMA" "RPMA Programmer's Manual"
.SH NAME
\fBrpma_cq_get_completion \fP- receive a completion of an operation (deprecated)
.SH SYNOPSIS
.nf
.fam C
      #include <librpma.h>

      struct rpma_cq;
      enum rpma_op {
              RPMA_OP_READ,
              RPMA_OP_WRITE,
              RPMA_OP_FLUSH,
              RPMA_OP_SEND,
              RPMA_OP_RECV,
              RPMA_OP_RECV_RDMA_WITH_IMM,
      };
      struct rpma_completion {
              void *op_context;
              enum rpma_op op;
              uint32_t byte_len;
              enum ibv_wc_status op_status;
              unsigned flags;
              uint32_t imm;
      };

      int \fBrpma_cq_get_completion\fP(struct rpma_cq *cq,
                      struct rpma_completion *cmpl);

.fam T
.fi
.fam T
.fi
.SH DESCRIPTION
\fBrpma_cq_get_completion\fP() receives the next available completion of
an already posted operation. All operations generate completion on error.
The operations posted with the RPMA_F_COMPLETION_ALWAYS flag also
generate a completion on success.
.PP
The rpma_completion structure provides the following fields:
.IP \(bu 3
op_context - context of the operation provided by the user to
either \fBrpma_conn_req_recv\fP(3), \fBrpma_flush\fP(3), \fBrpma_read\fP(3), \fBrpma_recv\fP(3),
\fBrpma_send\fP(3), \fBrpma_send_with_imm\fP(3), \fBrpma_write\fP(3), \fBrpma_write_atomic\fP(3),
\fBrpma_write_with_imm\fP(3)
.IP \(bu 3
op - type of the operation, for available values please see
the description below
.IP \(bu 3
byte_len - number of bytes transferred
.IP \(bu 3
op_status - status of the operation
.IP \(bu 3
flags - flags of the operation, for available values please
see \fBibv_poll_cq\fP(3)
.IP \(bu 3
imm - immediate data (in host byte order)
.PP
The available op values are:
.IP \(bu 3
RPMA_OP_READ - RMA read operation
.IP \(bu 3
RPMA_OP_WRITE - RMA write operation
.IP \(bu 3
RPMA_OP_FLUSH - RMA flush operation
.IP \(bu 3
RPMA_OP_SEND - messaging send operation
.IP \(bu 3
RPMA_OP_RECV - messaging receive operation
.IP \(bu 3
RPMA_OP_RECV_RDMA_WITH_IMM - messaging receive operation for
RMA write operation with immediate data
.PP
Note that if the provided cq is the main CQ and the receive CQ is present
on the same connection this function won't return RPMA_OP_RECV and
RPMA_OP_RECV_RDMA_WITH_IMM at any time. The receive CQ has to be used
instead to collect these completions. Please see the \fBrpma_conn_get_rcq\fP(3)
for details about the receive CQ.
.SH RETURN VALUE
The \fBrpma_cq_get_completion\fP() function returns 0 on success or a negative
error code on failure. On success, it writes the first available completion
to cmpl. If op_status of the written cmpl is not equal to IBV_WC_SUCCESS
then only op_context of the returned cmpl is valid.
.SH ERRORS
\fBrpma_cq_get_completion\fP() can fail with the following errors:
.IP \(bu 3
RPMA_E_INVAL - cq or cmpl is NULL
.IP \(bu 3
RPMA_E_NO_COMPLETION - no completions available
.IP \(bu 3
RPMA_E_PROVIDER - \fBibv_poll_cq\fP(3) failed with a provider error
.IP \(bu 3
RPMA_E_UNKNOWN - \fBibv_poll_cq\fP(3) failed but no provider error is available
.IP \(bu 3
RPMA_E_NOSUPP - not supported opcode
.SH DEPRECATED
This is an example snippet of code using the old API:
.PP
.nf
.fam C
        struct rpma_completion cmpl;

        ret = rpma_cq_get_completion(cq, &cmpl);
        if (ret) { error_handling_code() }

        if (cmpl.op_status != IBV_WC_SUCCESS) { error_handling_code() }
        if (cmpl.op != RPMA_OP_READ) { error_handling_code() }

        void *op_context = cmpl.op_context;
        uint32_t byte_len = cmpl.byte_len;
        enum ibv_wc_status op_status = cmpl.op_status;
        unsigned flags = cmpl.flags;
        uint32_t imm = cmpl.imm;

.fam T
.fi
The above snippet should be replaced with
the following one using the new API:
.PP
.nf
.fam C
        struct ibv_wc wc;

        ret = rpma_cq_get_wc(cq, 1, &wc, NULL);
        if (ret) { error_handling_code() }

        if (wc.status != IBV_WC_SUCCESS) { error_handling_code() }
        if (wc.opcode != IBV_WC_RDMA_READ) { error_handling_code() }

        void *op_context = (void *)wc.wr_id;
        uint32_t byte_len = wc.byte_len;
        enum ibv_wc_status op_status = wc.status;
        unsigned flags = (unsigned)wc.wc_flags;
        uint32_t imm = ntohl(wc.imm_data);

.fam T
.fi
.SH SEE ALSO
\fBrpma_conn_get_cq\fP(3), \fBrpma_conn_get_rcq\fP(3), \fBrpma_conn_req_recv\fP(3),
\fBrpma_cq_wait\fP(3), \fBrpma_cq_get_fd\fP(3), \fBrpma_flush\fP(3), \fBrpma_read\fP(3),
\fBrpma_recv\fP(3), \fBrpma_send\fP(3), \fBrpma_send_with_imm\fP(3), \fBrpma_write\fP(3),
\fBrpma_write_atomic\fP(3), \fBrpma_write_with_imm\fP(3), \fBlibrpma\fP(7) and
https://pmem.io/rpma/