INDEndpoint::SendAndInvalidate Method

Article
07/02/2010

Sends data to a remote peer and then invalidates the specified memory window on the peer.

Syntax

HRESULT SendAndInvalidate(
  [in]  ND_RESULT *pResult,
  [in]  const ND_SGE *pSgl,
  [in]  SIZE_T nSge,
  [in]  const ND_MW_DESCRIPTOR *pRemoteMwDescriptor,
  [in]  DWORD Flags
);

Parameters

pResult [in]
An ND_RESULT structure which will receive the status of the operation.
pSgl [in]
A list of ND_SGE structures for the Send request. Each entry describes a buffer that contains the data that is sent to the peer. May be NULL if nSge is zero, resulting in a zero-byte send and a corresponding zero-byte receive on the remote peer. The SGL may be stack-based, and is only used in the context of this call.
nSge [in]
The number of entries in the scatter/gather list. May be zero.
pRemoteMwDescriptor [in]
An ND_MW_DESCRIPTOR structure that describes the memory window to invalidate. The INDEndpoint::Bind method returns the descriptor. Invalidating the window lets the window be bound again to a different region of the registered memory.

Flags [in]
The following flags control the behavior of the send operation. You can specify one or more of the following flags:

Value	Meaning
ND_OP_FLAG_SILENT_SUCCESS 0x00000001	The successful completion of the send request does not generate a completion on the associated completion queue. Work requests that fail processing always generate a work completion.
ND_OP_FLAG_READ_FENCE 0x00000002	All prior Read requests must be complete before the hardware begins processing the send request.
ND_OP_FLAG_SEND_AND_SOLICIT_EVENT 0x00000004	You can use this flag if you issue multiple, related Send requests. Set this flag only on the last, related Send request. The peer will receive all the Send requests as normal with the only difference being that when they receive the last Send request (the one with the ND_OP_FLAG_SEND_AND_SOLICIT_EVENT flag set), the completion queue for the peer generates a notification; the notification is generated after the receive completes. This flag has no meaning to the receiver (peer) unless they have previously called the INDCompletionQueue::Notify method with the notification type set to NdCqNotifySolicited. Note that errors always satisfy a Notify request.

ND_OP_FLAG_SILENT_SUCCESS 0x00000001

The successful completion of the send request does not generate a completion on the associated completion queue. Work requests that fail processing always generate a work completion.

ND_OP_FLAG_READ_FENCE 0x00000002

All prior Read requests must be complete before the hardware begins processing the send request.

ND_OP_FLAG_SEND_AND_SOLICIT_EVENT 0x00000004

You can use this flag if you issue multiple, related Send requests. Set this flag only on the last, related Send request. The peer will receive all the Send requests as normal with the only difference being that when they receive the last Send request (the one with the ND_OP_FLAG_SEND_AND_SOLICIT_EVENT flag set), the completion queue for the peer generates a notification; the notification is generated after the receive completes.

This flag has no meaning to the receiver (peer) unless they have previously called the INDCompletionQueue::Notify method with the notification type set to NdCqNotifySolicited. Note that errors always satisfy a Notify request.

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. Completion status will be returned through the outbound completion queue associated with the endpoint.
ND_CONNECTION_INVALID	The endpoint is not connected.
ND_BUFFER_OVERFLOW	The send request referenced more data than is supported by the underlying hardware.
ND_NO_MORE_ENTRIES	The request would have exceeded the number of outbound requests allowed on the endpoint. The nOutboundEntries parameter of the INDConnector::CreateEndpoint method specifies the limit.
ND_DATA_OVERRUN	The number of scatter/gather entries in the scatter/gather list of the request exceeded the number allowed on the endpoint. The nOutboundSge parameter of the INDConnector::CreateEndpoint method specifies the limit.

Remarks

You call this method to tell the peer whose memory window you used for Read or Write operations that you are done with the window.

Invalidating a memory window prevents further access to it; the memory window is no longer bound to the registered memory. Further references to that memory window in an RDMA Read or Write would result in a fatal error on the endpoint and the connection is terminated.

This method behaves the same as the INDEndpoint::Send method, however, the packet includes the memory window descriptor so that the recipient hardware can invalidate the memory window as part of processing the received packet. The results of the Send portion of the request is reported in this endpoint's outbound completion queue.

This method generates a single result for the caller; however, the peer will get two results - one for the receive request and one for the invalidate request.

The SendAndInvalidate request is sent to the connected peer's receive buffer. The peer's inbound completion queue will include the result for the invalidate request followed by the receive request (the SendAndInvalidate request will succeed only if the peer has an outstanding Receive request).

If the send request fails, the endpoint can still process existing or future requests.

Requirements

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