Skip to content

Latest commit

 

History

History
159 lines (108 loc) · 9.87 KB

IND2SharedReceiveQueue.md

File metadata and controls

159 lines (108 loc) · 9.87 KB

IND2SharedReceiveQueue interface

Use to pool Receive requests among multiple queue pairs. The IND2Adapter::CreateSharedReceiveQueue method returns this interface.

The IND2SharedReceiveQueue interface inherits from IND2Overlapped. In addition, IND2SharedReceiveQueue defines the following methods.

  • GetNotifyAffinity - Returns the assigned affinity for processing Notify requests.

  • Modify - Modifies the number of Receive requests that a shared receive queue supports, and/or the threshold below which the shared receive queue will complete pending Notify requests.

  • Notify - Requests notification for errors or for the number of pending Receive requests that are falling below the notification threshold.

  • Receive - Posts a Receive request for data from a remote peer connected to any of the queue pairs that are associated with the shared receive queue.

Remarks:

Shared receive queue support is optional. Support for shared receive queues is identified by the MaxSharedReceiveQueueDepth member of the ND2_ADAPTER_INFO structure. To get the limit supported by the NetworkDirect adapter, call the IND2Adapter::Query method.

IND2SharedReceiveQueue::GetNotifyAffinity

Returns the assigned affinity for processing Notify requests.

HRESULT GetNotifyAffinity(
 [out] USHORT* pGroup,
 [out] KAFFINITY* pAffinity
);

Parameters:

  • pGroup [out]

    The processor group number. On operating systems that do not support processor groups, this value is returned as zero.

  • pAffinity [out]

    A bitmap that specifies the processor affinity within the specified group.

Return Value:

When you implement this method, you should return the following return values. If you return others, try to use well-known values to aid in debugging issues.

  • ND_SUCCESS - The operation succeeded.
  • ND_INSUFFICIENT_RESOURCES - The requested number of entries could not be allocated.
  • ND_INVALID_PARAMETER - The pGroup or pAffinity parameter was invalid.
  • ND_DEVICE_REMOVED - The underlying NetworkDirect adapter was removed from the system. Only cleanup operations on the NetworkDirect adapter will succeed.
  • ND_NOT_SUPPORTED - The underlying NetworkDirect adapter does not support setting affinity for Notify requests.

Remarks: Provider implementations should set the notify affinity (including interrupt affinity if applicable) to one or more of the processors in the following order - requested affinity, calling thread affinity, preferably the calling thread's ideal processor, or process affinity. If none of these can be supported, the providers should attempt to set affinity to the closest processor to the requested settings, in the same order: requested affinity, calling thread affinity, process affinity.

Providers are encouraged to return affinity information for Notify request completion processing even if they do not support specifying affinity, rather than returning ND_NOT_SUPPORTED. This allows client code to optimize its notification strategy and CPU usage, especially if all notifications go to the same processor.

IND2SharedReceiveQueue::Modify

Modifies the number of Receive requests that a shared receive queue supports, and/or the threshold below which the shared receive queue will complete pending Notify requests.

HRESULT Modify(
 [in] ULONG queueDepth,
 [in] ULONG notifyThreshold
);

Parameters:

  • queueDepth [in]

    The new number of outstanding Receive requests that the shared receive queue should support. If zero, queueDepth does not modify the number of entries the shared receive queue can support.

  • notifyThreshold [in]

    The new number of outstanding Receive requests below which outstanding Notify requests are completed. Used to indicate to the application that it needs to post more Receive requests to prevent starving senders. If zero, notifyThreshold does not modify the threshold.

Return Value:

When you implement this method, you should return the following return values. If you return others, try to use well-known values to aid in debugging issues.

  • ND_SUCCESS - The operation succeeded.
  • ND_INSUFFICIENT_RESOURCES - The requested number of entries could not be allocated.
  • ND_INVALID_PARAMETER - The requested number of entries exceeds the capabilities of the hardware.
  • ND_BUFFER_OVERFLOW - The requested number of entries is less than the number of Receive requests currently outstanding on the shared receive queue.
  • ND_DEVICE_REMOVED - The underlying NetworkDirect adapter was removed from the system. Only cleanup operations on the NetworkDirect adapter will succeed.

Implementation Notes:

Provider implementations may allocate more entries than requested, although there are no mechanisms for advertising these extra entries to clients.

Remarks:

To get the limits that are supported by a NetworkDirect adapter, call the IND2Adapter::Query method.

You can increase or decrease the size of the queue. If the number you specify is less than the number of outstanding Receive requests in the queue, the method returns ND_BUFFER_OVERFLOW (the queue remains unchanged).

IND2SharedReceiveQueue::Notify

Requests notification for errors or when the number of outstanding Receive requests falls below the notifyThreshold specified in IND2Adapter::CreateSharedReceiveQueue or IND2SharedReceiveQueue::Modify.

HRESULT Notify(
 [in] OVERLAPPED *pOverlapped
);

Parameters:

  • pOverlapped [in]

    A pointer to an OVERLAPPED structure that must remain valid for the duration of the operation.

Return Value:

When you implement this method, you should return the following return values. If you return others, try to use well-known values to aid in debugging issues.

  • ND_SUCCESS - The operation succeeded.
  • ND_PENDING - The notification request was successfully queued to the shared receive queue.
  • ND_FAILURE - The shared receive queue experienced a catastrophic error and is unusable. All associated queue pairs are also unusable. No future completions will be reported. This is generally indicative of a hardware failure.
  • ND_CANCELED - The request was canceled.
  • ND_INSUFFICIENT_RESOURCES - The request for notification could not be queued.
  • ND_DEVICE_REMOVED - The underlying NetworkDirect adapter was removed from the system. Only cleanup operations on the NetworkDirect adapter will succeed.

Remarks:

You can use this method to get notification when the number of outstanding Receive requests falls below the specified threshold, to notify the client that more Receive requests should be issued.

Multiple requests for notification can be outstanding for the same shared receive queue. All such requests will be completed by the next notification event on the specified shared receive queue. This is similar to a notification event that releases all callers that are waiting, rather than a synchronization event that releases, at most, one. This allows multiple threads to process notifications in parallel.

By default, shared receive queues are not set to generate notifications. This method arms the shared receive queue for a threshold notification.

IND2SharedReceiveQueue::Receive

Receives data from a peer.

HRESULT Receive(
 [in] VOID *requestContext,
 [in] const ND2_SGE sge[],
 [in] ULONG nSge
);

Parameters:

  • requestContext [in]

    A context value to associate with the request, returned in the RequestContext member of the ND2_RESULT structure that is returned when the request completes.

  • sge [in]

    An array of ND2_SGE structures that describe the buffers that will receive the data that the peer sends. May be nullptr if nSge is zero.

  • nSge [in]

    The number of entries in the sge array. May be zero.

Return Value:

When you implement this method, you should return the following return values. If you return others, try to use well-known values to aid in debugging issues.

  • ND_SUCCESS - The operation succeeded. Completion status will be returned through the outbound completion queue associated with the queue pair.
  • ND_BUFFER_OVERFLOW - The request referenced more data than is supported by the underlying hardware.
  • ND_NO_MORE_ENTRIES - The request would have exceeded the number of Receive requests allowed on this shared receive queue. The queueDepth parameter of the IND2Adapter::CreateSharedReceiveQueue method specifies the limit.
  • ND_DATA_OVERRUN - The number of scatter/gather entries in the scatter/gather list exceeded the number allowed on the queue pair. The maxRequestSge parameter of the IND2Adapter::CreateSharedReceiveQueue method specifies the limit.

Remarks:

You can call this method before any associated queue pairs are connected.

You must post a Receive request before the peer posts a Send request. The buffers that you specify must be large enough to receive the sent data. If not, the Send request fails and the connection is terminated; the completion status for the Receive request is ND_BUFFER_OVERFLOW. If the Receive fails, the shared receive queue can still process existing or future requests.

The protocol determines how many Receive requests you must post and the buffer size that is required for each post.

The array of ND2_SGE structures can be allocated temporarily on the stack.