RDS in OFED 1.0 Release Notes
=============================

June 2006


NAME
       rds - Reliable Datagram Socket API

STATUS in OFED 1.0
       Technology Preview. 

SYNOPSIS
       #define AF_INET_RDS 30

       rds_socket = socket(AF_INET_RDS, SOCK_DGRAM, 0);

DESCRIPTION
       This is an implementation of the RDS socket API on OpenFabrics.  
       It provides reliable, in-order datagram delivery between sockets.

SOCKET CREATION
       RDS is still in development and as such does not have a reserved proto-
       col family constant.  

BINDING
       A new RDS socket has no local address when it is  first  returned  from
       socket(2).   It  must  be  bound  to a local address by calling bind(2)
       before any messages can be sent or received.  RDS sockets do  not  sup-
       port connecting to remote endpoints with connect(2).  An RDS socket can
       only be bound to one address and only one socket  can  be  bound  to  a
       given  address.  If no port is specified in the binding address then an
       unbound port is selected at random.

MESSAGE TRANSMISSION
       Messages  may  be  sent  using sendmsg(2) once the RDS socket is bound.
       Message length cannot exceed 4 gigabytes, that is an  unsigned  32  bit
       integer.

       RDS does not support any out of band data of any kind.

       A  successful sendmsg(2) call puts the message in the socket's transmit
       queue where it will remain until  the  destination  acknowledges
       that the message is no longer in the network.

       A  given RDS socket has limited transmit buffer space for each destina-
       tion address.  While a message is in the  transmit  queue  its  payload
       bytes  are accounted for.  If an attempt is made to send a message to a
       destination whose buffer does not have room for the  new  message  then
       the sender will block or EAGAIN will be returned depending on MSG_DONT-
       WAIT message flag. 

MESSAGE RECEIPT
       Messages  may  be  received with recvmsg(2) on an RDS socket once it is
       bound to a source address.  The MSG_DONTWAIT message flag determines if
       the  receive will block waiting for message arrival.
       The  MSG_PEEK flag stops the message from being removed from the 
       receive queue.

       The memory consumed by messages waiting for delivery does not limit the
       number of messages that can be queued for  receive.   Senders  must  be
       careful  not  to  overwhelm  the  receiver by sizing their send buffers
       appropriately. 


POLL
       RDS supports a limited poll(2) API.  POLLIN is returned when there is a
       message  waiting  in  the  socket's  receive  queue.  POLLOUT is always
       returned, it is up to the application to back off if poll  is  used  to
       trigger sends.


RELIABILITY
       If  sendmsg(2)  succeeds  then  RDS guarantees that the message will be
       visible to recvmsg(2) on a socket bound to the destination  address  as
       long as that destination socket remains open.

       If  there  is  no  socket  bound on the destination than the message is
       silently dropped.  

       If a socket is closed then all pending sent messages on the socket  are
       canceled and may or may not be seen by the receiver.

       If a receiving socket is closed with pending messages then  the  sender
       considers  those  messages  as  having  left  the  network and will not
       retransmit them.

       A message will only be seen by recvmsg(2) without MSG_PEEK once.   Once
       the  message has been delivered it is removed from the sending socket's
       transmit queue.

       All messages sent from the same socket to the same destination will  be
       delivered  in  the  order  they're  sent.  Messages sent from different
       sockets, or to different destinations, may be delivered in any order.


ADDRESS FORMATS
       RDS uses sockaddr_in as  described  in  ip(7)  to  describe  addresses,
       including  setting  sin_family  to AF_INET_RDS .  
       RDS only supports unicast communication -- broadcast and multicast 
       addresses are not supported.

SEE ALSO
       socket(2),  bind(2),  sendmsg(2),  recvmsg(2), getsockopt(2).  setsock-
       opt(2).

RDS LINKS
       Oracle RDS project

       http://oss.oracle.com/projects/rds/
	


Linux Man Page                                                          RDS(7)
