Direct Access Transport Library Functions
dateprecvquery(3DAT)
NAME
dateprecvquery - provide Endpoint receive queue consump-
tion on SRQ
SYNOPSIS
cc [ flag... ] file... -ldat [ library... ]
#include
DATRETURN
dateprecvquery (
IN DATEPHANDLE ephandle,
OUT DATCOUNT *nbufsallocated,
OUT DATCOUNT *bufsallocspan
)
PARAMETERS
ephandle Handle for an instance of the EP.
nbufsallocated The number of buffers at the EP for which
completions have not yet been generated.
bufsallocspan The span of buffers that EP needs to com-
plete arriving messages.
DESCRIPTION
The dateprecvquery() function provides to the Consumer a
snapshot for Recv buffers on EP. The values for
nbufsallocated and bufsallocspan are not defined when
DATRETURN is not DATSUCES.
The Provider might not support nbufsallocated,
bufsallocspan or both. Check the Provider attribute for EP
Recv info support. When the Provider does not support both
of these counts, the return value for the operation can be
DATMODELNOTSUPORTED.
If nbufsallocated is not NUL, the count pointed to by
nbufsallocated will return a snapshot count of the number
of buffers allocated to ephandle but not yet completed.
Once a buffer has been allocated to an EP, it will be com-
pleted to the EP recvevd if the EVD has not overflowed.
When an EP does not use SRQ, a buffer is allocated as soon
as it is posted to the EP. For EP that uses SRQ, a buffer is
SunOS 5.11 Last change: 16 Jul 2004 1
Direct Access Transport Library Functions
dateprecvquery(3DAT)
allocated to the EP when EP removes it from SRQ.
If bufsallocspan is not NUL, then the count to which
bufsallocspan pointed will return the span of buffers
allocated to the ephandle. The span is the number of addi-
tional successful Recv completions that EP can generate if
all the messages it is currently receiving will complete
successfully.
If a message sequence number is assigned to all received
messages, the buffer span is the difference between the
latest message sequence number of an allocated buffer minus
the latest message sequence number for which completion has
been generated. This sequence number only counts Send mes-
sages of remote Endpoint of the connection.
The Message Sequence Number (MSN) represents the order that
Send messages were submitted by the remote Consumer. The
ordering of sends is intrinsic to the definition of a reli-
able service. Therefore every send message does have a MSN
whether or not the native transport has a field with that
name.
For both nbufsallocated and bufsallocspan, the Provider
can return the reserved value DATVALUEUNKNOWN if it cannot
obtain the requested count at a reasonable cost.
RETURN VALUES
DATSUCES The operation was successful.
DATINVALIDPARAMETER Invalid parameter.
DATINVALIDHANDLE The DAT handle ephandle is
invalid.
DATMODELNOTSUPORTED The requested Model was not sup-
ported by the Provider.
USAGE
If the Provider cannot support the query for nbufsallocated
or bufsallocspan, the value returned for that attribute
must be DATVALUEUNKNOWN.
SunOS 5.11 Last change: 16 Jul 2004 2
Direct Access Transport Library Functions
dateprecvquery(3DAT)
An implementation that processes incoming packets out of
order and allocates from SRQs on an arrival basis can have
gaps in the MSNs associated with buffers allocated to an
Endpoint.
For example, suppose Endpoint X has received buffer frag-
ments for MSNs 19, 22, and 23. With arrival ordering, the EP
would have allocated three buffers from the SRQ for messages
19, 22, and 23. The number allocated would be 3, but the
span would be 5. The difference of two represents the
buffers that will have to be allocated for messages 20 and
21. They have not yet been allocated, but messages 22 and 23
will not be delivered until after messages 20 and 21 have
not only had their buffers allocated but have also com-
pleted.
An implementation can choose to allocate 20 and 21 as soon
as any higher buffer is allocated. This makes sense if you
presume that this is a valid connection, because obviously
20 and 21 are in flight. However, it creates a greater vul-
nerability to Denial Of Service attacks. There are also
other implementation tradeoffs, so the Consumer should
accept that different RNICs for iWARP will employ different
strategies on when to perform these allocations.
Each implementation will have some method of tracking the
receive buffers already associated with an EP and knowing
which buffer matches which incoming message, though those
methods might vary. In particular, there are valid implemen-
tations such as linked lists, where a count of the outstand-
ing buffers is not instantly available. Such implementations
would have to scan the allocated list to determine both the
number of buffers and their span. If such a scan is neces-
sary, it is important that it be only a single scan. The set
of buffers that was counted must be the same set of buffers
for which the span is reported.
The implementation should not scan twice, once to count the
buffers and then again to determine their span. Not only is
it inefficient, but it might produce inconsistent results if
buffers were completed or arrived between the two scans.
Other implementations can simply maintain counts of these
values to easily filter invalid packets. If so, these status
counters should be updated and referenced atomically.
SunOS 5.11 Last change: 16 Jul 2004 3
Direct Access Transport Library Functions
dateprecvquery(3DAT)
The implementation must never report n buffers in a span
that is less than n.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Standard: uDAPL, 1.2
MT-Level Unsafe
SEE ALSO
datepcreate(3DAT), datsrqcreate(3DAT),
datsrqfree(3DAT), datsrqquery(3DAT),
datepsetwatermark(3DAT), libdat(3LIB), attributes(5)
SunOS 5.11 Last change: 16 Jul 2004 4
Direct Access Transport Library Functions
dateprecvquery(3DAT)
SunOS 5.11 Last change: 16 Jul 2004 5
|
