1dat_srq_create(3DAT)Direct Access Transport Library Functiondsat_srq_create(3DAT)
2
6 dat_srq_create - create an instance of a shared receive queue
7
9 cc [ flag... ] file... -ldat [ library... ]
10 #include <dat/udat.h>
11 DAT_RETURN
13 dat_srq_create (
14 IN DAT_IA_HANDLE ia_handle,
15 IN DAT_PZ_HANDLE pz_handle,
16 IN DAT_SRQ_ATTR *srq_attr,
17 OUT DAT_SRQ_HANDLE *srq_handle
18 )
19
22 ia_handle A handle for an open instance of the IA to which the cre‐
23 ated SRQ belongs.
24 pz_handle A handle for an instance of the Protection Zone.
27 srq_attr A pointer to a structure that contains Consumer-requested
30 SRQ attributes.
31 srq_handle A handle for the created instance of a Shared Receive
34 Queue.
35
38 The dat_srq_create() function creates an instance of a Shared Receive
39 Queue (SRQ) that is provided to the Consumer as srq_handle. If the
40 value of DAT_RETURN is not DAT_SUCCESS, the value of srq_handle is not
41 defined.
42 The created SRQ is unattached to any Endpoints.
45 The Protection Zone pz_handle allows Consumers to control what local
48 memory can be used for the Recv DTO buffers posted to the SRQ. Only
49 memory referred to by LMRs of the posted Recv buffers that match the
50 SRQ Protection Zone can be accessed by the SRQ.
51 The srq_attributes argument specifies the initial attributes of the
54 created SRQ. If the operation is successful, the created SRQ will have
55 the queue size at least max_recv_dtos and the number of entries on the
56 posted Recv scatter list of at lease max_recv_iov. The created SRQ can
57 have the queue size and support number of entries on post Recv buffers
58 larger than requested. Consumer can query SRQ to find out the actual
59 supported queue size and maximum Recv IOV.
60 The Consumer must set low_watermark to DAT_SRQ_LW_DEFAULT to ensure
63 that an asynchronous event will not be generated immediately, since
64 there are no buffers in the created SRQ. The Consumer should set the
65 Maximum Receive DTO attribute and the Maximum number of elements in IOV
66 for posted buffers as needed.
67 When an associated EP tries to get a buffer from SRQ and there are no
70 buffers available, the behavior of the EP is the same as when there are
71 no buffers on the EP Recv Work Queue.
72
74 DAT_SUCCESS The operation was successful.
75 DAT_INSUFFICIENT_RESOURCES The operation failed due to resource lim‐
78 itations.
79 DAT_INVALID_HANDLE Either ia_handle or pz_handle is an
82 invalid DAT handle.
83 DAT_INVALID_PARAMETER One of the parameters is invalid. Either
86 one of the requested SRQ attributes was
87 invalid or a combination of attributes is
88 invalid.
89 DAT_MODEL_NOT_SUPPORTED The requested Model was not supported by
92 the Provider.
93
96 SRQ is created by the Consumer prior to creation of the EPs that will
97 be using it. Some Providers might restrict whether multiple EPs that
98 share a SRQ can have different Protection Zones. Check the
99 srq_ep_pz_difference_support Provider attribute. The EPs that use SRQ
100 might or might not use the same recv_evd.
101 Since a Recv buffer of SRQ can be used by any EP that is using SRQ, the
104 Consumer should ensure that the posted Recv buffers are large enough to
105 receive an incoming message on any of the EPs.
106 If Consumers do not want to receive an asynchronous event when the num‐
109 ber of buffers in SRQ falls below the Low Watermark, they should leave
110 its value as DAT_SRQ_LW_DEFAULT. If Consumers do want to receive a
111 notification, they can set the value to the desired one by calling
112 dat_srq_set_lw(3DAT).
113 SRQ allows the Consumer to use fewer Recv buffers then posting the max‐
116 imum number of buffers for each connection. If the Consumer can upper
117 bound the number of incoming messages over all connections whose local
118 EP is using SRQ, then instead of posting this maximum for each connec‐
119 tion the Consumer can post them for all connections on SRQ. For exam‐
120 ple, the maximum utilized link bandwidth divided over the message size
121 can be used for an upper bound.
122 Depending on the underlying Transport, one or more messages can arrive
125 simultaneously on an EP that is using SRQ. Thus, the same EP can have
126 multiple Recv buffers in its possession without these buffers being on
127 SRQ or recv_evd.
128 Since Recv buffers can be used by multiple connections of the local EPs
131 that are using SRQ, the completion order of the Recv buffers is no
132 longer guaranteed even when they use of the same recv_evd. For each
133 connection the Recv buffers completion order is guaranteed to be in the
134 order of the posted matching Sends to the other end of the connection.
135 There is no ordering guarantee that Receive buffers will be returned in
136 the order they were posted even if there is only a single connection
137 (Endpoint) associated with the SRQ. There is no ordering guarantee
138 between different connections or between different recv_evds.
139
141 See attributes(5) for descriptions of the following attributes:
142 ┌─────────────────────────────┬─────────────────────────────┐
147 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
148 ├─────────────────────────────┼─────────────────────────────┤
149 │Interface Stability │Standard: uDAPL, 1.2 │
150 ├─────────────────────────────┼─────────────────────────────┤
151 │MT-Level │Safe │
152 └─────────────────────────────┴─────────────────────────────┘
153
155 dat_srq_free(3DAT), dat_srq_post_recv(3DAT), dat_srq_query(3DAT),
156 dat_srq_resize(3DAT), dat_srq_set_lw(3DAT), libdat(3LIB), attributes(5)
157SunOS 5.11 11 Sep 2006 dat_srq_create(3DAT)