1dat_ep_recv_query(3DDAiTr)ect Access Transport Library Functdiaotn_sep_recv_query(3DAT)
2
6 dat_ep_recv_query - provide Endpoint receive queue consumption on SRQ
7
9 cc [ flag... ] file... -ldat [ library... ]
10 #include <dat/udat.h>
11 DAT_RETURN
13 dat_ep_recv_query (
14 IN DAT_EP_HANDLE ep_handle,
15 OUT DAT_COUNT *nbufs_allocated,
16 OUT DAT_COUNT *bufs_alloc_span
17 )
18
21 ep_handle Handle for an instance of the EP.
22 nbufs_allocated The number of buffers at the EP for which comple‐
25 tions have not yet been generated.
26 bufs_alloc_span The span of buffers that EP needs to complete arriv‐
29 ing messages.
30
33 The dat_ep_recv_query() function provides to the Consumer a snapshot
34 for Recv buffers on EP. The values for nbufs_allocated and
35 bufs_alloc_span are not defined when DAT_RETURN is not DAT_SUCCESS.
36 The Provider might not support nbufs_allocated, bufs_alloc_span or
39 both. Check the Provider attribute for EP Recv info support. When the
40 Provider does not support both of these counts, the return value for
41 the operation can be DAT_MODEL_NOT_SUPPORTED.
42 If nbufs_allocated is not NULL, the count pointed to by nbufs_allocated
45 will return a snapshot count of the number of buffers allocated to
46 ep_handle but not yet completed.
47 Once a buffer has been allocated to an EP, it will be completed to the
50 EP recv_evd if the EVD has not overflowed. When an EP does not use SRQ,
51 a buffer is allocated as soon as it is posted to the EP. For EP that
52 uses SRQ, a buffer is allocated to the EP when EP removes it from SRQ.
53 If bufs_alloc_span is not NULL, then the count to which bufs_alloc_span
56 pointed will return the span of buffers allocated to the ep_handle. The
57 span is the number of additional successful Recv completions that EP
58 can generate if all the messages it is currently receiving will com‐
59 plete successfully.
60 If a message sequence number is assigned to all received messages, the
63 buffer span is the difference between the latest message sequence num‐
64 ber of an allocated buffer minus the latest message sequence number for
65 which completion has been generated. This sequence number only counts
66 Send messages of remote Endpoint of the connection.
67 The Message Sequence Number (MSN) represents the order that Send mes‐
70 sages were submitted by the remote Consumer. The ordering of sends is
71 intrinsic to the definition of a reliable service. Therefore every send
72 message does have a MSN whether or not the native transport has a field
73 with that name.
74 For both nbufs_allocated and bufs_alloc_span, the Provider can return
77 the reserved value DAT_VALUE_UNKNOWN if it cannot obtain the requested
78 count at a reasonable cost.
79
81 DAT_SUCCESS The operation was successful.
82 DAT_INVALID_PARAMETER Invalid parameter.
85 DAT_INVALID_HANDLE The DAT handle ep_handle is invalid.
88 DAT_MODEL_NOT_SUPPORTED The requested Model was not supported by the
91 Provider.
92
95 If the Provider cannot support the query for nbufs_allocated or
96 bufs_alloc_span, the value returned for that attribute must be
97 DAT_VALUE_UNKNOWN.
98 An implementation that processes incoming packets out of order and
101 allocates from SRQs on an arrival basis can have gaps in the MSNs asso‐
102 ciated with buffers allocated to an Endpoint.
103 For example, suppose Endpoint X has received buffer fragments for MSNs
106 19, 22, and 23. With arrival ordering, the EP would have allocated
107 three buffers from the SRQ for messages 19, 22, and 23. The number
108 allocated would be 3, but the span would be 5. The difference of two
109 represents the buffers that will have to be allocated for messages 20
110 and 21. They have not yet been allocated, but messages 22 and 23 will
111 not be delivered until after messages 20 and 21 have not only had their
112 buffers allocated but have also completed.
113 An implementation can choose to allocate 20 and 21 as soon as any
116 higher buffer is allocated. This makes sense if you presume that this
117 is a valid connection, because obviously 20 and 21 are in flight. How‐
118 ever, it creates a greater vulnerability to Denial Of Service attacks.
119 There are also other implementation tradeoffs, so the Consumer should
120 accept that different RNICs for iWARP will employ different strategies
121 on when to perform these allocations.
122 Each implementation will have some method of tracking the receive buf‐
125 fers already associated with an EP and knowing which buffer matches
126 which incoming message, though those methods might vary. In particular,
127 there are valid implementations such as linked lists, where a count of
128 the outstanding buffers is not instantly available. Such implementa‐
129 tions would have to scan the allocated list to determine both the num‐
130 ber of buffers and their span. If such a scan is necessary, it is
131 important that it be only a single scan. The set of buffers that was
132 counted must be the same set of buffers for which the span is reported.
133 The implementation should not scan twice, once to count the buffers and
136 then again to determine their span. Not only is it inefficient, but it
137 might produce inconsistent results if buffers were completed or arrived
138 between the two scans.
139 Other implementations can simply maintain counts of these values to
142 easily filter invalid packets. If so, these status counters should be
143 updated and referenced atomically.
144 The implementation must never report n buffers in a span that is less
147 than n.
148
150 See attributes(5) for descriptions of the following attributes:
151 ┌─────────────────────────────┬─────────────────────────────┐
156 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
157 ├─────────────────────────────┼─────────────────────────────┤
158 │Interface Stability │Standard: uDAPL, 1.2 │
159 ├─────────────────────────────┼─────────────────────────────┤
160 │MT-Level │Unsafe │
161 └─────────────────────────────┴─────────────────────────────┘
162
164 dat_ep_create(3DAT), dat_srq_create(3DAT), dat_srq_free(3DAT),
165 dat_srq_query(3DAT), dat_ep_set_watermark(3DAT), libdat(3LIB),
166 attributes(5)
167SunOS 5.11 16 Jul 2004 dat_ep_recv_query(3DAT)