INDCompletionQueue::Notify Method

Requests notification for errors and completions.

Syntax

HRESULT Notify(
  [in]  DWORD Type,
  [in]  OVERLAPPED *pOverlapped
);

Parameters

• Type [in]
  Specifies the type of notification to receive. The possible values are:

  Value	Meaning
  ND_CQ_NOTIFY_ERRORS 0	The Notify request will complete if there are any completion queue errors such as a completion queue overrun or catastrophic failure.
  ND_CQ_NOTIFY_ANY 1	The Notify request will complete on the next successful completion in the completion queue.
  ND_CQ_NOTIFY_SOLICITED 2	The Notify request will complete when the completion queue receives a Send request that includes the ND_OP_FLAG_SEND_AND_SOLICIT_EVENT flag.

   

• 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.

Return code	Description
ND_SUCCESS	The operation succeeded.
ND_PENDING	The completion notification request was successfully queued to the completion queue.
ND_FAILURE	The completion queue experienced a catastrophic error and is unusable. All associated endpoints are also unusable. No future completions will be reported. This is generally indicative of a hardware failure.
ND_BUFFER_OVERFLOW	The completion queue attempted to queue more than the maximum number of completions and is now unusable. All associated endpoints are also unusable. No future completions will be reported. This is generally indicative of a programming error.
ND_CANCELED	The completion queue was destroyed.
ND_INSUFFICIENT_RESOURCES	The request for notification could not be queued.
ND_DEVICE_REMOVED	The underlying Network Direct adapter was removed from the system. Only cleanup operations on the Network Direct adapter will succeed.

 

Remarks

You can use this method to get notification when a request completes and use the notification to trigger calls to the INDCompletionQueue::GetResults method.

The Notify overlapped requests are completed if there are any new completions since the last notification. The completions that triggered the overlapped to be completed will not cause a subsequent Notify request to be completed; a completion will cause at most a single triggering of the completion queue (but could complete multiple overlapped if they are queued simultaneously). For example,

• The client calls Notify, which returns pending
• The hardware adds a new completion to the completion queue
• The hardware driver completes the Notify request
• The client calls GetResults, which returns 1 (the first completion)
• The client calls GetResults, which returns 0 (no more completions)
• The client calls Notify, which returns pending
• The hardware adds a new completion to the completion queue
• The hardware driver completes the Notify request
• The client calls GetResults, which returns 1 (the first completion)
• The client calls GetResults, which returns 0 (no more completions)
• The client calls Notify, which returns pending

When notified, applications are expected to call GetResults until all completions have been returned (all completions are returned if the value that GetResults returns is less than the value of the nResults parameter), as more than one entry could be written to the completion queue before a pending Notify request is completed.

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

By default, completion queues are not set to generate completion notifications. This method rearms the completion queue for the desired event type.

Implementation Note

Providers can peek at their completion queues after rearming to see if the next entry holds a valid completion, and if so immediately complete the request. This does not require mapping completion queue ring buffers to the kernel, as the user memory can be dereference while in the context of the user's thread.

Providers are expected to eliminate any potential race conditions that can occur between the time their hardware writes a new completion entry to the completion queue, after the application called GetResults and received a return value of zero (or less than the value of the nResults parameter), and the application calling Notify.

The following two cases effectively provide applications the same behavior:

Case 1

1. GetResults returns 0
2. The hardware adds a new completion to the completion queue
3. Notify completes immediately

Case 2

1. GetResults returns 0
2. Notify returns pending
3. The hardware adds a new completion to the completion queue
4. Notify completes

Note that for Case 1, step 3 could have been broken into the following two steps:

3. Notify returns pending

4. Notify completes

The original case merges steps 3 and 4 and completes the request immediately. It does not matter when Notify is called with respect to the hardware writing new entries to the completion queue; the only thing that matters is that GetResults returned all known entries—any entries written to the completion queue after that point should cause a subsequent Notify call to succeed.

Requirements

Product	Microsoft Message Passing Interface (MS-MPI)
Header	Ndspi.h

See Also

INDCompletionQueue

 

 

Send comments about this topic to Microsoft

Build date: 7/2/2010