dat_ep_recv_query man page on Solaris

Printed from http://www.polarhome.com/service/man/?qf=dat_ep_recv_query&af=0&tf=2&of=Solaris

dat_ep_recv_query(3Direct Access Transport Library Funcdat_ep_recv_query(3DAT)

NAME
       dat_ep_recv_query - provide Endpoint receive queue consumption on SRQ

SYNOPSIS
       cc [ flag... ] file... -ldat [ library... ]
       #include <dat/udat.h>

       DAT_RETURN
	   dat_ep_recv_query (
	       IN      DAT_EP_HANDLE	   ep_handle,
	       OUT     DAT_COUNT	   *nbufs_allocated,
	       OUT     DAT_COUNT	   *bufs_alloc_span
	   )

PARAMETERS
       ep_handle       Handle for an instance of the EP.

       nbufs_allocated The  number  of buffers at the EP for which completions
		       have not yet been generated.

       bufs_alloc_span The span of buffers that EP needs to complete  arriving
		       messages.

DESCRIPTION
       The  dat_ep_recv_query()	 function  provides to the Consumer a snapshot
       for  Recv  buffers  on  EP.  The	  values   for	 nbufs_allocated   and
       bufs_alloc_span are not defined when DAT_RETURN is not DAT_SUCCESS.

       The  Provider  might  not  support  nbufs_allocated, bufs_alloc_span 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 DAT_MODEL_NOT_SUPPORTED.

       If nbufs_allocated is not NULL, the count pointed to by nbufs_allocated
       will  return  a	snapshot  count	 of the number of buffers allocated to
       ep_handle but not yet completed.

       Once a buffer has been allocated to an EP, it will be completed to  the
       EP recv_evd 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 allocated to the EP when EP removes it from SRQ.

       If bufs_alloc_span is not NULL, then the count to which bufs_alloc_span
       pointed will return the span of buffers allocated to the ep_handle. The
       span  is	 the  number of additional successful Recv completions that EP
       can generate if all the messages it is currently	 receiving  will  com‐
       plete successfully.

       If  a message sequence number is assigned to all received messages, the
       buffer span is the difference between the latest message sequence  num‐
       ber of an allocated buffer minus the latest message sequence number for
       which completion has been generated. This sequence number  only	counts
       Send messages of remote Endpoint of the connection.

       The  Message  Sequence Number (MSN) represents the order that Send mes‐
       sages were submitted by the remote Consumer. The ordering of  sends  is
       intrinsic to the definition of a reliable service. Therefore every send
       message does have a MSN whether or not the native transport has a field
       with that name.

       For  both  nbufs_allocated and bufs_alloc_span, the Provider can return
       the reserved value DAT_VALUE_UNKNOWN if it cannot obtain the  requested
       count at a reasonable cost.

RETURN VALUES
       DAT_SUCCESS	       The operation was successful.

       DAT_INVALID_PARAMETER   Invalid parameter.

       DAT_INVALID_HANDLE      The DAT handle ep_handle is invalid.

       DAT_MODEL_NOT_SUPPORTED The  requested  Model  was not supported by the
			       Provider.

USAGE
       If the  Provider	 cannot	 support  the  query  for  nbufs_allocated  or
       bufs_alloc_span,	  the  value  returned	for  that  attribute  must  be
       DAT_VALUE_UNKNOWN.

       An implementation that processes incoming  packets  out	of  order  and
       allocates from SRQs on an arrival basis can have gaps in the MSNs asso‐
       ciated with buffers allocated to an Endpoint.

       For example, suppose Endpoint X has received buffer fragments 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 completed.

       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.  How‐
       ever, it creates a greater vulnerability 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 buf‐
       fers already associated with an EP and  knowing	which  buffer  matches
       which incoming message, though those methods might vary. In particular,
       there are valid implementations such as linked lists, where a count  of
       the  outstanding	 buffers  is not instantly available. Such implementa‐
       tions would have to scan the allocated list to determine both the  num‐
       ber  of	buffers	 and  their  span.  If such a scan is necessary, 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.

       The implementation must never report n buffers in a span that  is  less
       than n.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Interface Stability	     │Standard: uDAPL, 1.2	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │MT-Level		     │Unsafe			   │
       └─────────────────────────────┴─────────────────────────────┘

SEE ALSO
       dat_ep_create(3DAT),	 dat_srq_create(3DAT),	   dat_srq_free(3DAT),
       dat_srq_query(3DAT),	dat_ep_set_watermark(3DAT),	 libdat(3LIB),
       attributes(5)

SunOS 5.10			  16 Jul 2004	       dat_ep_recv_query(3DAT)
[top]

List of man pages available for Solaris

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net