6. Error Handling

6.1. Return Value Conventions

• Constructors do not return a value. Call isConnected() to check session readiness.

• Memory registration APIs return an opaque pointer on success and nullptr on failure.

• I/O APIs return ssize_t. Synchronous success returns a byte count, asynchronous submission success returns 0, and failure returns a negative errno-style value.

• poll() returns a completion count or a negative errno-style value.

• Channel allocation returns a channel ID or INVALID_CHANNEL_ID.

6.2. I/O API Failure Values

Return value	Meaning
-ENODEV	Server RDMA device is not available.
-EIO	Invalid argument, invalid descriptor, invalid channel, request range failure, submission failure, or completion failure.
-ENOMEM	Allocation failure.
-EAFNOSUPPORT	Address family is not supported by the active path.

6.3. poll() Failure Values

Return value	Meaning
-ENODEV	Server RDMA device is not available.
-EINVAL	events == nullptr, or channel is invalid or unallocated.
-EIO	One or more completions reported failure.

6.4. Completion Status

For synchronous handleGetObject() and handlePutObject(), the optional status parameter is populated after polling when a completion status is available. IBV_WC_SUCCESS (0) means success.

For asynchronous operations, poll() reports completion status in cuObjAsyncEvent_t.status. A non-negative poll() return value gives the number of valid events in the output array.

Common completion status values include:

Value	Status	Meaning
0	IBV_WC_SUCCESS	Operation completed successfully.
5	IBV_WC_WR_FLUSH_ERR	Outstanding work request was flushed after queue-pair error/reset.
8	IBV_WC_LOC_ACCESS_ERR	Local memory registration, key, or access error.
10	IBV_WC_REM_ACCESS_ERR	Remote key, address, or access error.
11	IBV_WC_REM_OP_ERR	Remote operation error.
12	IBV_WC_RETRY_EXC_ERR	Retry count exceeded; usually a path or reachability issue.
13	IBV_WC_RNR_RETRY_EXC_ERR	Receiver-not-ready retry count exceeded.
19	IBV_WC_FATAL_ERR	Fatal completion error.
20	IBV_WC_RESP_TIMEOUT_ERR	Response timeout.
21	IBV_WC_GENERAL_ERR	General completion error.