Introduce an API to flush outstanding work requests

[shijin-aws]

Is your feature request related to a problem? Please describe.

The current FI_MORE flag implementation creates ambiguity around error handling and completion semantics, particularly when EAGAIN is returned. The flag indicates that additional requests will immediately follow, allowing providers to optimize fabric hardware access. However, there are scenarios where:

1. Applications may not know ahead of time how many messages to batch with FI_MORE
2. When EAGAIN occurs, it's unclear whether the provider should expect the application to repost the request or if the provider needs to flush pending operations
3. The current definition implicitly restricts implementation by tying it to specific hardware behaviors (like verbs' doorbell mechanism) rather than providing a device-agnostic approach

This creates a situation where applications may get stuck in EAGAIN states with no clear recovery path, and providers lack a standardized way to handle batched operations that don't complete as expected.

Describe the solution you'd like

Introduce a new fi_flush API that allows applications to explicitly signal completion of a batch of FI_MORE operations. This would:

• Provide a device-agnostic mechanism to "ring the doorbell" or complete batched operations without requiring a full work request post
• Give providers the opportunity to integrate with hardware-specific semantics (like verbs' ibv_wr_complete) while maintaining a consistent API surface
• Resolve EAGAIN handling by allowing applications to flush pending operations without reposting
• Enable the pattern where providers can defer completion calls (like ibv_wr_complete) until flush is called, rather than on every operation

API Signature:

fi_flush(struct fid_ep *ep)

API Implementation:

For verbs semantics, the fi_flush implementation would work as follows:

• When FI_MORE flag is provided, the provider does not call ibv_wr_complete
• The provider only calls ibv_wr_complete during a flush operation
• This allows batching of work requests at the verbs level while providing an explicit completion mechanism

This approach integrates naturally with verbs' doorbell mechanism and can be adapted to other hardware implementations that support similar batching optimizations.

Describe alternatives you've considered

1. Status quo with clarified EAGAIN semantics: Define that EAGAIN handling is the provider's responsibility, allowing providers to flush without new posts. However, this doesn't give applications explicit control and may not work well when applications don't know batch sizes ahead of time.

2. Zero-byte transfer to clear FI_MORE: Use a 0-byte transfer operation to signal batch completion. This was rejected as it's not clear whether devices can optimize this or if it requires posting a full work request, potentially negating the performance benefits.

3. Application pattern without explicit flush:

for (i = 0; i < num - 1; i++)
    fi_writemsg(..., FI_MORE);
fi_write()  // Final call without FI_MORE

This only works when the application knows the batch size ahead of time and doesn't address EAGAIN recovery scenarios.

4. Redefine FI_MORE to imply doorbell semantics: Force all implementations to support doorbell-style completion. This would restrict implementations and may not align with all hardware architectures.

Additional context

This discussion originated from analyzing how FI_MORE interacts with verbs semantics, where ibv_wr_complete can be deferred until a flush operation. The proposed fi_flush API would align with this pattern while remaining implementation-agnostic.

Key considerations:

• The flush API should work without requiring a new work request post on hardware that supports doorbell mechanisms
• The definition should not force specific hardware implementations but allow optimization opportunities
• EAGAIN handling becomes clearer: providers can flush pending operations when needed, and applications have an explicit recovery mechanism
• As noted in the discussion, if we claim this behavior for EAGAIN, fi_flush makes sense and is aligned with the overall design

[shijin-aws]

Meanwhile, #12014 clarify the provider's error handling behavior with FI_MORE

[j-xiong]

I have been thinking along the line of adding new op to the fi_control interface for endpoints, and fi_flush can be a wrapper for that.

[j-xiong]

Adding a new op to fi_ops_ep should also work.

[j-xiong]

Per discussion on today's OFIWG meeting, the proposal would be adding a new member to struct fi_ops_ep (fi_endpoint.h):

 struct fi_ops_ep {
         size_t  size;
         ssize_t (*cancel)(fid_t fid, void *context);
         int     (*getopt)(fid_t fid, int level, int optname,
                         void *optval, size_t *optlen);
         int     (*setopt)(fid_t fid, int level, int optname,
                         const void *optval, size_t optlen);
         int     (*tx_ctx)(struct fid_ep *sep, int index,
                         struct fi_tx_attr *attr, struct fid_ep **tx_ep,
                         void *context);
         int     (*rx_ctx)(struct fid_ep *sep, int index,
                         struct fi_rx_attr *attr, struct fid_ep **rx_ep,
                         void *context);
         ssize_t (*rx_size_left)(struct fid_ep *ep);
         ssize_t (*tx_size_left)(struct fid_ep *ep);
+        void     (*flush)(struct fid_ep *ep);
 };

+static inline void fi_flush(struct fid_ep *ep)
+{
+       ep->ops->flush(ep);
+}

[j-xiong]

Alternative approach using fi_control:

fabric.h:

 /* control commands */
 enum {
         FI_GETFIDFLAG,          /* uint64_t flags */
         FI_SETFIDFLAG,          /* uint64_t flags */
         FI_GETOPSFLAG,          /* uint64_t flags */
         FI_SETOPSFLAG,          /* uint64_t flags */
         FI_ALIAS,               /* struct fi_alias * */
         FI_GETWAIT,             /* void * wait object */
         FI_ENABLE,              /* NULL */
         FI_BACKLOG,             /* integer * */
         FI_GET_RAW_MR,          /* fi_mr_raw_attr */
         FI_MAP_RAW_MR,          /* fi_mr_map_raw */
         FI_UNMAP_KEY,           /* uint64_t key */
         FI_QUEUE_WORK,          /* struct fi_deferred_work */
         FI_CANCEL_WORK,         /* struct fi_deferred_work */
         FI_FLUSH_WORK,          /* NULL */
         FI_REFRESH,             /* mr: fi_mr_modify */
         FI_DUP,                 /* struct fid ** */
         FI_GETWAITOBJ,          /* enum fi_wait_obj * */
         FI_GET_VAL,             /* struct fi_fid_var */
         FI_SET_VAL,             /* struct fi_fid_var */
         FI_EXPORT_FID,          /* struct fi_fid_export */
         FI_GET_FD,              /* int */
+        FI_FLUSH,               /* NULL */
 };

fi_endpoint.h:

+static inline void fi_flush(struct fid_ep *ep)
+{
+        (void) ep->fid.ops->control(&ep->fid, FI_FLUSH, NULL);
+}

[shijin-aws]

I am still working on it, one thing comes to my mind is why cannot we just reuse the FI_FLUSH_WORK enum in fi_control, also I am thinking to make it support FI_PREPARE_WORK command to support prepare a work in a given buffer.

[shijin-aws]

#12695