./udt4/ 0000700 0001750 0001750 00000000000 12111175615 012021 5 ustar yunhong yunhong ./udt4/doc/ 0000700 0001750 0001750 00000000000 12111175516 012566 5 ustar yunhong yunhong ./udt4/doc/doc/ 0000755 0001750 0001750 00000000000 12111175516 013345 5 ustar yunhong yunhong ./udt4/doc/doc/startup.htm 0000644 0001750 0001750 00000002532 12111175516 015563 0 ustar yunhong yunhong
The startup method initializes the UDT library.
If success, 0 is returned; otherwise, UDT::ERROR is returned and specific error information can be retrieved by getlasterror.
In the current version, this method always succeed.
The startup method initializes the UDT library. In particular, it starts the garbage collection thread. This method must be called before any other UDT calls. Failure to do so may cause memory leak.
If startup is called multiple times in one application, only the first one is effective, while the rest will do nothing.
./udt4/doc/doc/ecode.htm 0000644 0001750 0001750 00000011274 12111175516 015143 0 ustar yunhong yunhong
All UDT API will return an error upon a failed operation. Particularly, UDT defines UDT::INVALID_SOCK and UDT::ERROR as error returned values. (several routines return false as error value.) Application should check the return value against these two constants.
Error Name | Error Code | Comment |
SUCCESS | 0 | success operation. |
ECONNSETUP | 1000 | connection setup failure. |
ENOSERVER | 1001 | server does not exist. |
ECONNREJ | 1002 | connection request was rejected by server. |
ESOCKFAIL | 1003 | could not create/configure UDP socket. |
ESECFAIL | 1004 | connection request was aborted due to security reasons. |
ECONNFAIL | 2000 | connection failure. |
ECONNLOST | 2001 | connection was broken. |
ENOCONN | 2002 | connection does not exist. |
ERESOURCE | 3000 | system resource failure. |
ETHREAD | 3001 | could not create new thread. |
ENOBUF | 3002 | no memory space. |
EFILE | 4000 | file access error. |
EINVRDOFF | 4001 | invalid read offset. |
ERDPERM | 4002 | no read permission. |
EINVWROFF | 4003 | invalid write offset. |
EWRPERM | 4004 | no write permission. |
EINVOP | 5000 | operation not supported. |
EBOUNDSOCK | 5001 | cannot execute the operation on a bound socket. |
ECONNSOCK | 5002 | cannot execute the operation on a connected socket. |
EINVPARAM | 5003 | bad parameters. |
EINVSOCK | 5004 | invalid UDT socket. |
EUNBOUNDSOCK | 5005 | cannot listen on unbound socket. |
ENOLISTEN | 5006 | (accept) socket is not in listening state. |
ERDVNOSERV | 5007 | rendezvous connection process does not allow listen and accept call. |
ERDVUNBOUND | 5008 | rendezvous connection setup is enabled but bind has not been called before connect. |
ESTREAMILL | 5009 | operation not supported in SOCK_STREAM mode. |
EDGRAMILL | 5010 | operation not supported in SOCK_DGRAM mode. |
EDUPLISTEN | 5011 | another socket is already listening on the same UDP port. |
ELARGEMSG | 5012 | message is too large to be hold in the sending buffer. |
EASYNCFAIL | 6000 | non-blocking call failure. |
EASYNCSND | 6001 | no buffer available for sending. |
EASYNCRCV | 6002 | no data available for read. |
ETIMEOUT | 6003 | timeout before operation completes. |
EPEERERR | 7000 | Error has happened at the peer side. |
./udt4/doc/doc/t-hello.htm 0000644 0001750 0001750 00000007377 12111175516 015441 0 ustar yunhong yunhong
In this section we will introduce the simplest UDT program that can transfer data in high performance.
This simple "Hello World!" example includes a server program and a client program just like any socket programming tutorial. These are the simpler version of the appserver and appclient examples in ./app directory.
To compile, use gcc -o server server.cpp -I
UDT server example
This simple server tries to bind itself at port 9000. If succeed, it listens at port 9000 and accepts a client and then reads a string.
UDT client example
The client side connects to the local address (127.0.0.1) at port 9000, and sends a "hello world!" message.
Note that in this "Hello World!" example the UDT::send and UDT::recv routines should use a loop to check return value. However, since the string length is very small and can be hold in one packet, we omit the loop part in order to give a simpler example.
./udt4/doc/doc/bind.htm 0000644 0001750 0001750 00000010714 12111175516 014776 0 ustar yunhong yunhong
The bind method binds a UDT socket to a known or an available local address.
If the binding is successful, bind returns 0, otherwise it returns UDT::ERROR and the specific error information can be retrieved using getlasterror.
Error Name | Error Code | Comment |
EBOUNDSOCK | 5001 | u has already been bound to certain address. |
EINVPARAM | 5003 | the address is either invalid or unavailable. |
EINVSOCK | 5004 | u is an invalid UDT socket. |
The bind method is usually to assign a UDT socket a local address, including IP address and port number. If INADDR_ANY is used, a proper IP address will be used once the UDT connection is set up. If 0 is used for the port, a randomly available port number will be used. The method getsockname can be used to retrieve this port number.
The second form of bind allows UDT to bind directly on an existing UDP socket. This is usefule for firewall traversing in certain situations: 1) a UDP socket is created and its address is learned from a name server, there is no need to close the UDP socket and open a UDT socket on the same address again; 2) for certain firewall, especially some on local system, the port mapping maybe changed or the "hole" may be closed when a UDP socket is closed and reopened, thus it is necessary to use the UDP socket directly in UDT.
Use the second form of bind with caution, as it violates certain programming rules regarding code robustness. Once the UDP socket descriptor is passed to UDT, it MUST NOT be touched again. DO NOT use this unless you clearly understand how the related systems work.
The bind call is necessary in all cases except for a socket to listen. If bind is not called, UDT will automatically bind a socket to a randomly available address when a connection is set up.
By default, UDT allows to reuse existing UDP port for new UDT sockets, unless UDT_REUSEADDR is set to false. When UDT_REUSEADDR is false, UDT will create an exclusive UDP port for this UDT socket. UDT_REUSEADDR must be called before bind. To reuse an existing UDT/UDP port, the new UDT socket must explicitly bind to the port. If the port is already used by a UDT socket with UDT_REUSEADDR as false, the new bind will return error. If 0 is passed as the port number, bind always creates a new port, no matter what value the UDT_REUSEADDR sets.
listen, connect, setsockopt, getsockopt
./udt4/doc/doc/sockname.htm 0000644 0001750 0001750 00000007334 12111175516 015666 0 ustar yunhong yunhong
The getsockname method retrieves the local address associated with a UDT socket.
On success, getlasterror returns 0 and the local address information is stored in name; otherwise it returns UDT::ERROR and the specific error information can be retrieved using getlasterror.
Error Name | Error Code | Comment |
EINVPARAM | 5003 | Invalid parameters. |
EINVSOCK | 5004 | u is an invailid UDT socket. |
EUNBOUNDSOCK | 5005 | u is not bound to a local address yet. |
The getsockname retrieves the local address associated with the socket. The UDT socket must be bound explicitly (via bind) or implicitly (via connect), otherwise this method will fail because there is no meaningful address bound to the socket.
If getsockname is called after an explicit bind, but before connect, the IP address returned will be exactly the IP address that is used for bind and it may be 0.0.0.0 if ADDR_ANY is used. If getsockname is called after connect, the IP address returned will be the address that the peer socket sees. In the case when there is a proxy (e.g., NAT), the IP address returned will be the translated address by the proxy, but not a local address. If there is no proxy, the IP address returned will be a local address. In either case, the port number is local (i.e, not the translated proxy port).
Because UDP is connection-less, using getsockname on a UDP port will almost always return 0.0.0.0 as IP address (unless it is bound to an explicit IP) . As a connection oriented protocol, UDT will return a meaningful IP address by getsockname if there is no proxy translation exist.
UDT has no multihoming support yet. When there are multiple local addresses and more than one of them can be routed to the destination address, UDT may not behave properly due to the multi-path effect. In this case, the UDT socket must be explicitly bound to one of the local addresses.
./udt4/doc/doc/error.htm 0000644 0001750 0001750 00000002630 12111175516 015211 0 ustar yunhong yunhong
The getlasterror method the last UDT error within the same thread.
The last UDT error within the same thread is retrieved and returned in an ERRORINFO structure. If there is no error, a special SUCCESS code (0) will be returned. The getlasterror will always succeed. The returned value is a reference to the internal UDT ERRORINFO structure and application may clear it if necessary.
The getlasterror method reads the last UDT error in the thread where this method is called. The error information is stored in thread specific storage.
Error Code List, Error Handling
./udt4/doc/doc/structure.htm 0000644 0001750 0001750 00000016023 12111175516 016121 0 ustar yunhong yunhong
The structures used in UDT API are listed in the table below:
Structures | Comments |
UDTSOCKET | UDT socket descriptor |
ERRORINFO | Description of UDT system errors |
UDSET | Set of UDT sockets |
TRACEINFO | UDT performance statistics and protocol parameters |
This is used as the descriptor of a UDT socket. Its internal is not exposed to application and subject to future changes.
The ERRORINFO structure contains the specific information of a UDT error. It has two helper functions to let applications know an integral error code and a piece of text information.
Functions | Comments |
int getErrorCode() | read the UDT error code |
const char* getErrorMessage() | read the text information about the error. |
void clear() | clear the error information (set to SUCCESS). |
The UDSET structure is used with select call to access multiple UDT descriptors.
Four macros are defined on the UDSET structure to processing a UDT socket set. They are very similar to the fd_set structure and macros in traditional standard socket API.
Macros | Comments |
UD_CLR(u, *set) | remove socket u from set. |
UD_ISSET(u, *set) | check if u is in set. |
UD_SET(u, *set) | add u into the set. |
UD_ZERO(*set) | initialize set to empty. |
The TRACEINFO structure stores the performance trace information. Its member attributes can be read directly by applications.
Members | Comments |
The following attributes are aggregate values since the UDT socket is created. | |
int64_t msTimeStamp | time elapsed since the UDT socket is created, in milliseconds |
int64_t pktSentTotal | total number of sent packets, including retransmissions |
int64_t pktRecvTotal | total number of received packets |
int pktSndLossTotal | total number of lost packets, measured in the sending side |
int pktRcvLossTotal | total number of lost packets, measured in the receiving side |
int pktRetransTotal | total number of retransmitted packets, measured in the sending side |
int pktSentACKTotal | total number of sent ACK packets |
int pktRecvACKTotal | total number of received ACK packets |
int pktSentNAKTotal | total number of sent NAK packets |
int pktRecvNAKTotal | total number of received NAK packets |
The following attributes are local values since the last time they are recorded. | |
int64 pktSent | number of sent packets, including retransmissions |
int64 pktRecv | number of received packets |
int pktSndLoss | number of lost packets, measured in the sending side |
int pktRcvLoss | number of lost packets, measured in the receiving side |
int pktRetrans | number of retransmitted packets, measured in the sending side |
int pktSentACK | number of sent ACK packets |
int pktRecvACK | number of received ACK packets |
int pktSentNAK | number of sent NAK packets |
int pktRecvNAK | number of received NAK packets |
double mbpsSendRate | sending rate in Mbps |
double mbpsRecvRate | receiving rate in Mbps |
The following attributes are instant values at the time they are observed. | |
double usPktSndPeriod | packet sending period, in microseconds |
int pktFlowWindow | flow window size, in number of packets |
int pktCongestionWindow | congestion window size, in number of packets |
int pktFlightSize | number packets on the flight |
double msRTT | round trip time, in milliseconds |
double mbpsBandwidth | estimated bandwidth, in Mbps |
int byteAvailSndBuf | available sending buffer size, in bytes |
int byteAvailRcvBuf | available receiving buffer size, in bytes |
./udt4/doc/doc/socket.htm 0000644 0001750 0001750 00000004253 12111175516 015353 0 ustar yunhong yunhong
The socket method creates a new UDT socket.
If no error occurs, socket returns the new UDT socket descriptor; otherwise, it returns UDT::INVALID_SOCK and the error information can be retrieved by getlasterror.
Error Name | Error Code | Comment |
EINVPARAM | 5003 | Invalid parameters. |
The socket methods creates a new socket. The is no limits for the number of UDT sockets in one system, as long as there is enough system resource. UDT supports both IPv4 and IPv6, which can be selected by the af parameter. On the other hand, two socket types are supports in UDT, i.e., SOCK_STREAM for data streaming and SOCK_DGRAM for messaging. Note that UDT sockets are connection oriented in all cases.
./udt4/doc/doc/peername.htm 0000644 0001750 0001750 00000005015 12111175516 015654 0 ustar yunhong yunhong
The getpeername method retrieves the address informtion of the peer side of a connected UDT socket.
On success, getlasterror returns 0 and the peer address information is stored in name; otherwise it returns UDT::ERROR and the specific error information can be retrieved using getlasterror.
Error Name | Error Code | Comment |
ENOCONN | 2002 | u is not connected. |
EINVPARAM | 5003 | Invalid parameters. |
EINVSOCK | 5004 | u is an invailid UDT socket. |
The getpeername retrieves the address of the peer side associated to the connection. The UDT socket must be connected at the time when this method is called. The namelen must provide the leangth of the name parameter, which should be enough to hold the address information. On return, namelen contains the length of the result.
./udt4/doc/doc/t-intro.htm 0000644 0001750 0001750 00000005267 12111175516 015465 0 ustar yunhong yunhong
The prerequisite knowledge for using UDT is sound experience on C++ and socket programing. This is enough to use UDT in distributed applications. If you are familiar with computer networking, you may find UDT more powerful.
UDT is a C++ library, which has almost identical routines as the BSD socket APIs. Using UDT in a C++ program is very straightforward. In fact, you may easily modify your existing code from TCP to UDT.
Because of the similarity between UDT API and BSD socket API, UDT defines its own namespace UDT to differentiate the UDT APIs from the regular socket APIs. A qualifier of UDT:: should be put before the UDT socket call. UDTSOCKET is a data type to describe a UDT socket. For a complete UDT structures and constant definitions, please see Reference:UDT Structures. For a complete description of UDT socket APIs, please see Reference:UDT Functions.
For those socket APIs that does not involve with a socket descriptor, e.g., inet_pton, they are not wrapped by UDT API, and the applications should continue to use the original functions. For those socket APIs or options not appropriate to UDT, e.g., certain TCP options, they are simply not available in UDT API.
For example, using BSD socket, you write:
Its counterpart in UDT is like this:
UDT API is thread-safe. UDT sockets can be shared by multiple threads and UDT API on the same socket can be made concurrently. However, because of its application level nature, UDT sockets cannot be shared among processes. That is, a UDT socket created in one process cannot be used in another process.
If you use a programming language other than C++, you may need to write certain wrapper for the UDT C++ API. For example, you may use "extern C" to wrap UDT API in C; there are also ways to call C++ API in Java.
To use UDT in a C++ application:
Header
#include <udt.h>
Library (depending on platforms)
libudt.so
libudt.a
udt.dll
udt.lib
udt.dylib
Namespace
UDT
./udt4/doc/doc/t-data.htm 0000644 0001750 0001750 00000005142 12111175516 015233 0 ustar yunhong yunhong
This section describes using UDT to transfer data in streaming mode. This is exactly the same as using traditional BSD socket.
In streaming mode, neither a send or a recv call can guarantee that all data are sent or received in one call, because there is no boundary information in the data stream. Application should use loops for both sending and receiving.
Example: send a data block (buf, size) using UDT.
Similarily, to receive data stream, the following example code can be used.
Example: receive "size" of data into buffer "buf"
UDT supports both blocking and non-blocking mode. The above example demonstrated the blocking mode. In non-blocking mode, UDT::send and UDT::recv will return immediately if there is no buffer available. Usually, non-blocking calls are used together with accept.
UDT also supports timed blocking IO with UDT_SNDTIMEO and UDT_RCVTIMEO. This is in the middle between complete blocking and complete non-blocking calls. Timed IO will block the sending or receiving call for a limited period. This is sometimes useful if the application does not know if and when the peer side will send a message.
./udt4/doc/doc/listen.htm 0000644 0001750 0001750 00000004722 12111175516 015362 0 ustar yunhong yunhong
The listen method enables a server UDT entity to wait for clients to connect.
If success, 0 is returned; otherwise, UDT::ERROR is returned and specific error information can be retrieved by getlasterror.
Error Name | Error Code | Comment |
ECONNSOCK | 5002 | u is already connected. |
EINVSOCK | 5004 | u is an invalid socket. |
EUNBOUNDSOCK | 5005 | u is not bound. |
ERDVNOSERV | 5007 | u is in rendezvous mode. |
The listen method lets a UDT socket enter listening state. The socket must call bind before a listen call. In addition, if the socket is enable for rendezvous mode, neither listen nor accept can be used on the socket. A UDT socket can call listen more than once, in which case only the first call is effective, while all subsequent calls will be ignored if the socket is already in listening state.
./udt4/doc/doc/ccc.htm 0000644 0001750 0001750 00000013157 12111175516 014616 0 ustar yunhong yunhong
The following class CCC (some details are omitted) is the base class that a user-define congestion control algorithm should inherit from and overload the proper functions.
The class definition is in ccc.h, all new control algorithms definition should include this header file.
class CCC
{
public:
CCC();
virtual ~CCC() {}
void init()
This is the callback function to be called at the start of a UDT connection. It can be used to initialize the packet sending period, initial sending rate, etc. It can also be used to start timer thread. It is RECOMMENDED that the initializations are done in this method, rather than in the constructor.
void close()
The clear-ups can be done in this method.void onACK(ack)
This is the callback function to be called when an ACK is received. The parameter of ack is the acknowledged packet sequence number.
void onLoss(losslist, size)
This callback function is called when the sender detects a loss event, e.g., by duplicate ACK or explicit loss report. losslist is the packet sequence numbers of the lost packets and size the length of the loss list.
void onTimeout()
This callback function is called when a timeout event occurs if there is unacknowledged data in the sender side.
void onPktSent(pkt)
This callback function is called when a data packet is sent. All the packet information can be accessed though the pkt pointer. This callback function is useful to record the packet timestamp in a delay-based approach and compute RTT in onACK(), because UDT does not compute RTT for all packets.
See UDT specification and ./src/packet.cpp for the packet structure.
void onPktReceived(pkt)
This callback function is called when a data packet is received. Packet information can be accessed through pkt.
void processCustomMsg(pkt)
This callback function tells UDT how to process user defined control message (pkt).
void setACKTimer(msINT)
This method is used to enable timer-based acknowledging and set the ACK timer. It should be called by an inherited class (for example, in init()) if the new congestion control need timer-based acknowledging. msINT is the ACK timer in millisecond. Note that the highest precision of the ACK timer depends on the specific platform, and cannot exceed 1 millisecond.
void setACKInterval(pktINT)
This method is used to configure the number of packets to be received before an ACK is sent. This is the default acknowledging method and by default every packet will be acknowledged. Packet-based and timer-based acknowledging are exclusive. pktINT is the packet interval.
void setRTO(usRTO)
This method is used to set timeout value. The value usRTO is measured by microseconds.
void sendCustomMsg(pkt)
The method can be used to send a user defined control message. The control message pkt must conform to the packet format defined in ./src/packet.cpp. IMPORTANT: This message is sent through UDP; therefore, it is not guaranteed to be sent successfully nor in order.
const UDT::TRACEINFO* getPerfInfo()
The internal UDT parameters and flow statistics can be read using this method. This is similar to the perfmon() method.
double m_dPktSndPeriod
This is the packet sending period that should be updated by a rate control algorithm. If a pure window based algorithm is used, fix this variable to 0. It is measured by microsecond.
double m_dCWndSize
This is the congestion window size that should updated by window control algorithm. If a pure rate control algorithm is used, fix this variable to infinite.
User-defined congestion controls
./udt4/doc/doc/epoll.htm 0000644 0001750 0001750 00000014263 12111175516 015200 0 ustar yunhong yunhong
The epoll method can be used to effectively poll the IO events for a large number of sockets. It includes the following APIs.
If successful, epoll_create returns a new epoll ID, epoll_wait returns the total number of UDT sockets and system sockets ready for IO, and the other three functions return 0. On error, all functions return negative error values. The error can be one of the following.
Error Name | Error Code | Comment |
EINVPARAM | 5003 | Invalid parameters. |
EINVSOCK | 5004 | Invalid socket. |
EINVPOLLID | 5013 | EPoll ID is invalid. |
The epoll functions provides a highly scalable and efficient way to wait for UDT sockets IO events. It should be used instead of select and selectEx when the application needs to wait for a very large number of sockets. In addition, epoll also offers to wait on system sockets at the same time, which can be convenient when an application uses both UDT and TCP/UDP.
Applications should use epoll_create to create an epoll ID and use epoll_add_usock/ssock and epoll_remove_usock/ssock to add/remove sockets. If a socket is already in the epoll set, it will be ignored if being added again. Adding invalid or closed sockets will cause error. However, they will simply be ignored without any error returned when being removed.
Multiple epoll entities can be created and there is no upper limits as long as system resource allows. There is also no hard limit on the number of UDT sockets. The number system descriptors supported by UDT::epoll are platform dependent.
For system sockets on Linux, developers may choose to watch individual events from EPOLLIN (read), EPOLLOUT (write), and EPOLLERR (exceptions). When using epoll_remove_ssock, if the socket is waiting on multiple events, only those specified in events are removed. The events can be a combination (with "|" operation) of any of the following values.
enum EPOLLOpt
{
UDT_EPOLL_IN = 0x1,
UDT_EPOLL_OUT = 0x4,
UDT_EPOLL_ERR = 0x8
};
For all other situations, the parameter events is ignored and all events will be watched.
Note that exceptions are categorized as write events, so when the application choose to write to this socket, it will detect the exception.
Finally, for epoll_wait, negative timeout value will make the function to wait until an event happens. If the timeout value is 0, then the function returns immediately with any sockets associated an IO event. If timeout occurs before any event happens, the function returns 0.
./udt4/doc/doc/make.htm 0000644 0001750 0001750 00000005753 12111175516 015006 0 ustar yunhong yunhongThe UDT library is distributed with source code, example applications, and documentation. Currently the source code can be compiled on both Linux and Windows system.
Here is the content of the distribution:
./src: UDT source code
./app: Example applications
./doc: UDT documentation
./win: Visual C++ project files for Windows version of UDT
The library is in the original source code format without any installation tools, so installation is simply a make command. To make the C++ source code on different platform, the user needs to explicitly tell make the current operating system and hardware architecture with the "-e" option (except for Windows).
The available operating system options are: LINUX, BSD, and OSX.
The available options for hardware architecture are: IA32, IA64, POWERPC, and AMD64.
The command is in the format:
make -e os=XXX arch=YYY
where XXX and YYY are one of the options above. Note that it is case sensitive. There is a default value for Linux on the IA32 architecture, so if UDT is compiled on it, simply use make.
On Windows, use the Visual Studio .Net project files at ./win directory. It requires Visual C++ 7.0 or above to compile. Windows XP or above is also required under the default setting.If other Windows compilers are used, you may need to create your own Makefile or project files. In particular, if you use Visual C++ 6.0 or your system is Windows 2000 or certain embeded Windows systems, please define LEGACY_WIN32 in your Makefile or project files. You may also need to download Windows platform SDK in order to get the <wspiapi.h> header file.
After a successful make, you can begin to use the UDT library. The (only) header file udt.h and the library libudt.a (depending on the target system, libudt.so, libudt.dylib, and udt.dll may be available) are located in ./src directory.
Proper environment configuration should be set up before using UDT library. For example, if using libudt.so, the library path environment variable must be updated as: export LD_LIBRARY_PATH=[location of libudt.so, e.g., ../src]:$LD_LIBRARY_PATHOn Windows, copy udt.dll to the proper directory.
./udt4/doc/doc/treeview.css 0000644 0001750 0001750 00000000506 12111175516 015712 0 ustar yunhong yunhong /* jSh - Stylesheet for JavaScript TreeView documentation */ pre { margin-left:10px; } h1,h2,h3,h4,h5,h6,pre,tt { color:#0000CC; } a.an { text-decoration:none; } a:active { color:#CC0000; text-decoration:none; } a:link { color:#CC0000; text-decoration:underline; } a:visited { color:#990066; text-decoration:underline; } ./udt4/doc/doc/t-firewall.htm 0000644 0001750 0001750 00000005323 12111175516 016130 0 ustar yunhong yunhong
While UDT was originally written for extremely high speed data transfer, there are many other potential benefits from this reliable UDP-based library. One particular usage is to setup reliable connections between machines behind firewalls. To meet this requirement, UDT has added the rendezvous connection setup support.
Traditional BSD socket setup process requires explicit server side and client side. To punch NAT firewalls, a common method is to use the SO_REUSEADDR socket option to open two sockets bound to the same port, one listens and the other connects. UDT provides the more convenient rendezvous connection setup, in which there is no server or client, and two users can connect to each other directly.
With UDT, all sockets within one process can be bound to the same UDP port (but at most one listening socket on the same port is allowed). This is also helpful for system administrators to open a specific UDP port for all UDT traffic.
Example: Rendezvous connection setup. (Note that there is no need to set UDT_REUSEADDR here because it is true by default.)
In addition, UDT also allows to bind on an existing UDP socket. This is useful in two situations. First, sometimes the application must send packet to a name server in order to obtain its address (for example, this is true when behind an NAT firewall). Users may create a UDP socket and send some UDP packets to the name server to obtain the binding address. Then the UDP socket can be used directly for UDT (see bind) so that the application does not need to close the UDP socket and open a new UDT socket on the same address again.
Second, some firewalls working on local system may change the port mapping or close the "hole" is the punching UDP socket is closed, thus a new UDT socket on the same address will not be able to traverse the firewall. In this situation, binding the UDT socket on the existing UDP socket is not only convenient but necessary.
./udt4/doc/doc/copy.htm 0000644 0001750 0001750 00000004122 12111175516 015030 0 ustar yunhong yunhong
Copyright (c) 2001 - 2011, The Board of Trustees of the University of Illinois.
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
When a UDT socket is created as SOCK_DGRAM type, UDT will send and receive data as messages. The boundary of the message is preserved and the message is delivered as a whole unit. Sending or receving messages do not need a loop; a message will be either completely delivered or not delivered at all. However, at the receiver side, if the user buffer is shorter than the message length, only part of the message will be copied into the user buffer while the message will still be discarded.
Example: send and receive messages using UDT.
At the sender side, applications can specify two options for every message. The first is the life time (TTL) of a message. The default value is infinite, which means that the message will always be delivered. If the value is a postive one, UDT will discard the message if it cannot be delivered by the life time expires. The second is the order of the message. An in-order message means that this message will not be delivered unless all the messages prior to it are either delivered or discarded.
Synchronization modes (blocking vs. non-blocking) are also applied to SOCK_DGRAM sockets, so does not other UDT mechanisms including but limited to congestion control, flow control, and connection maintainence. Finally, note that UDT SOCK_DGRAM socket is also connection oriented. A UDT connection can only be set up between the same socket types.
./udt4/doc/doc/t-cc.htm 0000644 0001750 0001750 00000010134 12111175516 014704 0 ustar yunhong yunhong
You can add your own congestion control algorithm into UDT. It is as simple as to define several callback functions that will be triggered on certain events, e.g, when an ACK is received.
All the congestion control callback functions are collected in a C++ class CCC. You have to inherit this class to define your own congestion control algorithm. That is, UDT/CCC uses an object-oriented design. CCC in defined in ccc.h, which you have to include in your files in order to enable this feature.
The CCC class contains two control variables: m_dPktSndPeriod, and m_dCWndSize. m_dPktSndPeriod is a double float number representing the packet sending period (as to be used in rate control), in microseconds. m_dCWndSize is a double float number representing the size of the congestion window (cwnd), in number of packets. The congestion control algorithm will need to update at least one of them. For example, for pure window based approach, m_dPktSndPeriod should always be zero.
The fast way to learn CCC is to use the examples in ./app/cc.h. The file cc.h also includes many more advanced control mechanisms that your control classes can be derived from. For example, if you are designing a new TCP variant, you can implement the new control class directly from CTCP.
Here we demonstrate the usage of UDT/CCC by writing a reliable UDP blast control mechanism.
In this example, CUDPBlast inherits from the base class CCC. In the constructor, it sets the congestion window size to a large value so that it will not affect the packet sending. (This is pure rate based method to blast UDP packets.) The method SetRate() can be used to set a fixed packet sending rate at any time.
The application can use setsockopt/getsockopt to assign this control class to a UDT instance, and/or set its parameters.
The above code assigns the CUDPBlast control algorthm to a UDT socket usock. Note that CCCFactory
To set a specific data sending rate, the application needs to obtain a handle to the concrete CCC class instance used by the UDT socket usock.
The application can then call the method of setRate() to set a 500Mbps data rate.
The UDT/CCC can be used to implement most control mechanims, including but not limited to rate-based approaches, TCP variants (e.g., TCP, Scalable, HighSpeed, BiC, Vegas, FAST), and group-based approaches (e.g., GTP, CM).
1. Do NOT call regular UDT API inside CCC or its derived classes. Unknown error could happen.
2. CCCFactory<...> is a C++ template class. You do not need to derive any classes from it.
3. UDT will not release the CCCFactory<...> instance. The application should release it, at anywhere after the setsockopt() call.
./udt4/doc/doc/function.htm 0000644 0001750 0001750 00000006452 12111175516 015713 0 ustar yunhong yunhong
The UDT socket functions are contained in the UDT namespace. The methods are listed in the table below:
Method | Fuctionality |
accept | accept a connection. |
bind | assign a local name to an unnamed udt socket. |
cleanup | release the complete UDT library. |
close | close the opened UDT entity and shutdown the connection. |
connect | connect to the server or the peer side. |
epoll | watch for a group of UDT and system sockets for IO events. |
getlasterror | retrieve last UDT error in the current thread. |
getpeername | read the address of the peer side of the connection |
getsockname | read the local address of the UDT socket. |
getsockopt | read UDT options. |
listen | enable UDT into listening state and is ready for connection request. |
perfmon | monitor internal protocol parameters and udt performance. |
recv | receive data. |
recvfile | receive data into a file. |
recvmsg | receive a message. |
select | wait for a number of UDT sockets to change status. |
send | send data. |
sendfile | send a file. |
sendmsg | send a message. |
setsockopt | configure UDT options. |
socket | create a new UDT socket. |
startup | initialize the UDT library. |
./udt4/doc/doc/t-config.htm 0000644 0001750 0001750 00000011411 12111175516 015563 0 ustar yunhong yunhong
Options of UDT are read and set through getsockopt and setsockopt methods. Before modifying any option, bear in mind that it is NOT required that you modify the default options. If the application has sound performance with the default options, just use the default configurations.
UDT_MSS is used to configure the packet size. In most situations, the optimal UDT packet size is the network MTU size. The default value is 1500 bytes. A UDT connection will choose the smaller value of the MSS between the two peer sides. For example, if you want to set 9000-byte MSS, you have to set this option at both sides, and one of the value has to be exactly equal to 9000, and the other must not be less than 9000.
UDT uses a different semantics of synchronization mode from traditional sockets. It can set the sending and receiving synchronization independently, which allows more flexibility. However, UDT does not allow non-blocking operation on connection setup and close. The sychronization mode of sending and receiving can be set on UDT_SNDSYN and UDT_RCVSYN, respectively.
The UDT buffer size is (UDT_SNDBUF and UDT_RCVBUF) used to limit the size of temporary storage of sending/receiving data. The buffer size is only a limit and memory is allocated upon necessary. Generally, larger buffer (but not so large that the physical memory is used up) is better. For good performance the the buffer sizes for both sides should be at least Bandwidth*RTT.
UDT uses UDP as the data channel, so the UDP buffer size affects the performance. Again, a larger value is generally better, but the effects become smaller and disappear as the buffer size increases. Generally, the sending buffer size can be a small value, because it does not limit the packet sending much but a large value may increase the end-to-end delay.
UDT_FC is actually an internal parameter and you should set it to not less than UDT_RCVBUF/UDT_MSS. The default value is relatively large, therefore unless you set a very large receiver buffer, you do not need to change this option.
UDT_LINGER is similar to the SO_LINGER option on the regular sockets. It allows the UDT socket continue to sent out data in the sending buffer when close is called.
UDT_RENDEZVOUS is used to enable rendezvous connection setup. When rendezvous mode is enabled, a UDT socket cannot call listen or accept; instead, in order to set up a rendezvous connection, both the peer sides must call connect at approximately the same time. This is useful in traversing a firewall.
UDT_SNDTIMEO and UDT_RCVTIMEO are similar to SO_SNDTIMEO and SO_RCVTIMEO, respectively. They are used to set a timeout value for packet sending and receiving.
UDT_REUSEADDR allows applications to decide whether to share a UDP port with other UDT connections. By default this option is true, which means all UDT connections that are bind to 0 will try to reuse any existing UDP socket. In addition, multiple UDT connections can bind to the same port number other than 0. If UDT_REUSEADDR is set to false, an exclusive UDP port will be assign to this UDT socket. There are a few situations when UDT_REUSEADDR should be set to false. First, two UDT sockets cannot listen on the same port number, so either the second UDT socket is explicitly bound to a different port, or UDT_REUSEADDR is set to false for this UDT socket. Second, a UDT socket bound to a specific port number cannot connect to the other UDT socket bound to the same port on the same IP address.
Example: read current UDT settings
Example: modify UDT settings
The send method sends out certain amount of data from an application buffer.
On success, send returns the actual size of data that has been sent. Otherwise UDT::ERROR is returned and specific error information can be retrieved by getlasterror. If UDT_SNDTIMEO is set to a positive value, zero will be returned if no data is sent before the timer expires.
Error Name | Error Code | Comment |
ECONNLOST | 2001 | connection has been broken. |
ENOCONN | 2002 | u is not connected. |
EINVSOCK | 5004 | u is not an valid socket. |
EDGRAMILL | 5010 | cannot use send in SOCK_DGRAM mode. |
EASYNCSND | 6001 | u is non-blocking (UDT_SNDSYN = false) but buffer space is available for sending. |
ETIMEOUT | 6003 | Timeout on UDT_SNDTIMEO . |
EPEERERR | 7000 | The peer side has an unrecoverable error and this call has to be cancelled. |
The send method sends certain amount of data from the application buffer. If the the size limit of sending buffer queue is reached, send only sends a portion of the application buffer and returns the actual size of data that has been sent.
In blocking mode (default), send waits until there is some sending buffer space available. In non-blocking mode, send returns immediately and returns error if the sending queue limit is already limited.
If UDT_SNDTIMEO is set and the socket is in blocking mode, send only waits a limited time specified by UDT_SNDTIMEO option. If there is still no buffer space available when the timer expires, error will be returned. UDT_SNDTIMEO has no effect for non-blocking socket.
./udt4/doc/doc/udtdoc.css 0000644 0001750 0001750 00000002013 12111175516 015335 0 ustar yunhong yunhong /* CSS Document */ body { background-color: #FFFFFF; font-family: Verdana, Arial, Helvetica, sans-serif; font-size: 12px; line-height: 18px; color: #333333; } .note1 { font-family: Verdana, Arial, Helvetica, sans-serif; font-size: 12px; font-style: normal; line-height: normal; color: #333333; padding: 0px 0px 10px 10px; margin-top: 0; margin-bottom: 0; list-style-image: none; } .ref_head { font-family: Verdana, Arial, Helvetica, sans-serif; font-size: 12px; font-style: italic; font-weight: bold; background-color: #99CCFF; padding: 3px 3px 3px 3px; } .code { font-family: "Courier New", Courier, monospace; font-size: 10px; line-height: 12px; background-color: #C0C0C0; padding: 5px 5px 5px 5px; } .func_name { font-family: Verdana, Arial, Helvetica, sans-serif; font-size: 18px; color: #000000; } .table_headline { font-family: Verdana, Arial, Helvetica, sans-serif; font-size: 12px; background-color: #C0C0C0; padding: 2px 2px 2px 2px; } ./udt4/doc/doc/t-udt3.htm 0000644 0001750 0001750 00000003612 12111175516 015201 0 ustar yunhong yunhong
If you have never used UDT before, please skip this page.
If you are familiar with previous versions of UDT, in particular UDT3, please noted that we have several major changes in UDT4 and you may need to modify your existing code a little in order to use UDT4. In addition, different versions of UDT do not communicate with each other.
UDT4 have made the following improvements
Finally, UDT4 does not provide the NS-2 simulation code (nor any support to previous versions of simulation code) any more.
./udt4/doc/doc/accept.htm 0000644 0001750 0001750 00000006223 12111175516 015321 0 ustar yunhong yunhong
The accept method retrieves an incoming connection.
If no error occurs, accept returns the UDT socket descriptor of the new connection; otherwise, it returns UDT::INVALID_SOCK.
On a successful return, the address of the peer side of the connection is written into addr, and its length is in addrlen, if the addr parameter is not NULL.
If an error is returned, the error information can be retrieved by getlasterror. One of the following error can cause an accept error:
Error Name | Error Code | Comment |
EINVSOCK | 5004 | u is an invalid UDT socket. |
ENOLISTEN | 5006 | u is not in the listening state. |
ERDVNOSERV | 5007 | u is set up to support rendezvous connection. |
EASYNCRCV | 6002 | u is non-blocking (UDT_RCVSYN = false) but there is no connection available. |
Once a UDT socket is in listening state, it accepts new connections and maintains the pending connections in a queue. An accept call retrieves the first connection in the queue, removes it from the queue, and returns the associate socket descriptor.
If there is no connections in the queue when accept is called, a blocking socket will wait until a new connection is set up, whereas a non-blocking socket will return immediately with an error.
The accepted sockets will inherit all proper attributes from the listening socket.
listen, connect, setsockopt, getsockopt
./udt4/doc/doc/reference.htm 0000644 0001750 0001750 00000001354 12111175516 016020 0 ustar yunhong yunhong
This section describes in detail the UDT API, including:
./udt4/doc/doc/sendmsg.htm 0000644 0001750 0001750 00000011527 12111175516 015525 0 ustar yunhong yunhong
The sendmsg method sends a message to the peer side.
On success, sendmsg returns the actual size of message that has just been sent. The size should be equal to len. Otherwise UDT::ERROR is returned and specific error information can be retrieved by getlasterror. If UDT_SNDTIMEO is set to a positive value, zero will be returned if the message cannot be sent before the timer expires.
Error Name | Error Code | Comment |
ECONNLOST | 2001 | connection has been broken. |
ENOCONN | 2002 | u is not connected. |
EINVSOCK | 5004 | u is not an valid socket. |
ESTREAMILL | 5009 | cannot use sendmsg in SOCK_STREAM mode. |
ELARGEMSG | 5012 | the message is too large to be hold in the sending buffer. |
SASYNCSND | 6001 | u is non-blocking (UDT_SNDSYN = false) but no buffer space is available. |
ETIMEOUT | 6003 | Timeout on UDT_SNDTIMEO . |
The sendmsg method sends a message to the peer side. The UDT socket must be in SOCK_DGRAM mode in order to send or receive messages. Message is the minimum data unit in this situation. In particular, sendmsg always tries to send the message out as a whole, that is, the message will either to completely sent or it is not sent at all.
In blocking mode (default), sendmsg waits until there is enough space to hold the whole message. In non-blocking mode, sendmsg returns immediately and returns error if no buffer space available.
If UDT_SNDTIMEO is set and the socket is in blocking mode, sendmsg only waits a limited time specified by UDT_SNDTIMEO option. If there is still no buffer space available when the timer expires, error will be returned. UDT_SNDTIMEO has no effect for non-blocking socket.
The ttl parameter gives the message a limited life time, which starts counting once the first packet of the message is sent out. If the message has not been delivered to the receiver after the TTL timer expires and each packet in the message has been sent out at least once, the message will be discarded. Lost packets in the message will be retransmitted before TTL expires.
On the other hand, the inorder option decides if this message should be delivered in order. That is, the message should not be delivered to the receiver side application unless all messages prior to it are either delivered or discarded.
Finally, if the message size is greater than the size of the receiver buffer, the message will never be received in whole by the receiver side. Only the beginning part that can be hold in the receiver buffer may be read and the rest will be discarded.
./udt4/doc/doc/recv.htm 0000644 0001750 0001750 00000006741 12111175516 015026 0 ustar yunhong yunhong
The recv method reads certain amount of data into a local memory buffer.
On success, recv returns the actual size of received data. Otherwise UDT::ERROR is returned and specific error information can be retrieved by getlasterror. If UDT_RCVTIMEO is set to a positive value, zero will be returned if no data is received before the timer expires.
Error Name | Error Code | Comment |
ECONNLOST | 2001 | connection has been broken and no data left in receiver buffer. |
ENOCONN | 2002 | u is not connected. |
EINVSOCK | 5004 | u is not an valid socket. |
EDGRAMILL | 5010 | cannot use recv in SOCK_DGRAM mode. |
EASYNCRCV | 6002 | u is non-blocking (UDT_RCVSYN = false) but no data is available. |
ETIMEOUT | 6003 | Timeout on UDT_RCVTIMEO . |
The recv method reads certain amount of data from the protocol buffer. If there is not enough data in the buffer, recv only reads the available data in the protocol buffer and returns the actual size of data received. However, recv will never read more data than the buffer size indicates by len.
In blocking mode (default), recv waits until there is some data received into the receiver buffer. In non-blocking mode, recv returns immediately and returns error if no data available.
If UDT_RCVTIMEO is set and the socket is in blocking mode, recv only waits a limited time specified by UDT_RCVTIMEO option. If there is still no data available when the timer expires, error will be returned. UDT_RCVTIMEO has no effect for non-blocking socket.
./udt4/doc/doc/cleanup.htm 0000644 0001750 0001750 00000002714 12111175516 015512 0 ustar yunhong yunhong
The cleanup method releases the UDT library from your application.
If success, 0 is returned; otherwise, UDT::ERROR is returned and specific error information can be retrieved by getlasterror.
In the current version, this method always succeed.
The cleanup method releases the UDT library. All the remaining open connections will be closed. The background garbage collection is closed. However, this method will do nothing if no startup was ever called, or this is a repeated cleanup call.
The method must be called before the application exits, or before the UDT DLL is released, otherwise memory leak could happen.
./udt4/doc/doc/selectex.htm 0000644 0001750 0001750 00000007507 12111175516 015704 0 ustar yunhong yunhong
The selectEx method queries a group of of UDT sockets for IO status.
Note: selectEx is deprecated. Please use epoll instead, which is far more efficienct.
If any of the read, write, or except group is not empty, selectEx returns the number of UDT sockets that are read for read/write or are broken/closed. If no socket is ready before timeout, zero is returned. If there is any error, UDT::ERROR is returned and the specific error information can be retrieved using getlasterror. The readfds,writefds and/or exceptfds will be updated to contain the ready sockets.
Error Name | Error Code | Comment |
EINVPARAM | 5003 | All three socket sets are NULL or at least one of the socket is invalid. |
This function selectEx is an advanced version of select. In contrast to select, selectEx does not modify the input parameter fds, so that applications do not need to replicate or initialize it every time the function is called.
The new function only has one group of input socket descriptors. If a particular event check is not necessary, the corresponding output parameter can be set to NULL. For example, if the application does not care about if a socket is ready for send, the parameter writefds can be NULL.
Finally, selectEx specifies the absolute amount of time to wait, while select requires a clock time in the future to wait until.
Overall, selectEx is more convinient and more efficient.
./udt4/doc/doc/t-file.htm 0000644 0001750 0001750 00000003622 12111175516 015242 0 ustar yunhong yunhongWhile you can always use regular UDT::send and UDT::recv to transfer a file, UDT provides a more convinient and optimized way for file transfer. An application can use UDT::sendfile and UDT::recvfile directly. In addition, file transfer IO API and regular data IO API are orthogonal. E.g., the data stream sent out by UDT::sendfile does not necessarily require UDT::recvfile to accept.
The sendfile and recvfile methods are blocking call and are not affected by UDT_SNDSYN, UDT_RCVSYN, UDT_SBDTIMEO, or UDT_RCVTIMEO. They always complete the call with the specified size parameter for sending or receiving unless errors occur.
UDT uses C++ fstream for file IO.
Example: send a file using UDT.
Example: Receive data into a file.
./udt4/doc/doc/intro.htm 0000644 0001750 0001750 00000003531 12111175516 015214 0 ustar yunhong yunhong
Welcome to the UDT4 SDK documentation.
UDT is a high performance data transfer protocol - UDP-based data transfer protocol. It was designed for data intensive applications over high speed wide area networks, to overcome the efficiency and fairness problems of TCP. As its name indicates, UDT is built on top of UDP and it provides both reliable data streaming and messaging services.
Visit http://udt.sf.net for most recent news on UDT.
Check out most current UDT release at SourceForge or from CVS.
export CVS_RSH=ssh
cvs -d:pserver:anonymous@udt.cvs.sourceforge.net:/cvsroot/udt login
[NOTE: when prompt for password, press the RETURN/ENTER key]
cvs -d:pserver:anonymous@udt.cvs.sourceforge.net:/cvsroot/udt co UDT4
In this documentation:
./udt4/doc/doc/recvfile.htm 0000644 0001750 0001750 00000006013 12111175516 015656 0 ustar yunhong yunhong
The recvfile method reads certain amount of data into a local file.
On success, recvfile returns the actual size of received data. Otherwise UDT::ERROR is returned and specific error information can be retrieved by getlasterror.
Error Name | Error Code | Comment |
ECONNLOST | 2001 | connection has been broken and no data left in receiver buffer. |
ENOCONN | 2002 | u is not connected. |
EFILE | 4000 | File or disk system errors. |
EINVSOCK | 5004 | u is not an valid socket. |
EDGRAMILL | 5010 | cannot use recvfile in SOCK_DGRAM mode. |
The recvfile method reads certain amount of data and write it into a local file. It is always in blocking mode and neither UDT_RCVSYN nor UDT_RCVTIMEO affects this method. The actual size of data to expect must be known before calling recvfile, otherwise deadlock may occur due to insufficient incoming data.
./udt4/doc/doc/header.htm 0000644 0001750 0001750 00000000500 12111175516 015302 0 ustar yunhong yunhong
The close method closes a UDT connection.
If success, 0 is returned; otherwise, UDT::ERROR is returned and specific error information can be retrieved by getlasterror.
Error Name | Error Code | Comment |
EINVSOCK | 5004 | u is an invalid UDT socket. |
The close method gracefully shutdowns the UDT connection and releases all related data structures associated with the UDT socket. If there is no connection associated with the socket, close simply release the socket resources.
On a blocking socket, if UDT_LINGER is non-zero, the close call will wait until all data in the sending buffer are sent out or the waiting time has exceeded the expiration time set by UDT_LINGER. However, if UDT_SYNSND is set to false (i.e., non-blocking sending), close will return immediately and any linger data will be sent at background until the linger timer expires.
The closing UDT socket will send a shutdown message to the peer side so that the peer socket will also be closed. This is a best-effort message. If the message is not successfully delivered, the peer side will also be closed after a time-out. In UDT, shutdown is not supported.
All sockets should be closed if they are not used any more.
./udt4/doc/doc/opt.htm 0000644 0001750 0001750 00000016731 12111175516 014671 0 ustar yunhong yunhong
The getsockopt and setsockopt methods read and set UDT options, respectively.
Name | Type | Meaning | Comment |
UDT_MSS | int | Maximum packet size (bytes). | Including all UDT, UDP, and IP headers. Default 1500 bytes. |
UDT_SNDSYN | bool | Synchronization mode of data sending. | true for blocking sending; false for non-blocking sending. Default true. |
UDT_RCVSYN | bool | Synchronization mode for receiving. | true for blocking receiving; false for non-blocking receiving. Default true. |
UDT_CC | CCCFactory* CCC** |
User defined congestion control algorithm. | optval is a pointer to a CCC Factory class instance (for setsockopt). optval is a pointer of pointer to a CCC class instance (for getsockopt). |
UDT_FC | int | Maximum window size (packets) | Default 25600. Do NOT change this unless you know what you are doing. Must change this before modifying the buffer sizes. |
UDT_SNDBUF | int | UDT sender buffer size limit (bytes) | Default 10MB (10240000). |
UDT_RCVBUF | int | UDT receiver buffer size limit (bytes) | Default 10MB (10240000). |
UDP_SNDBUF | int | UDP socket sender buffer size (bytes) | Default 1MB (1024000). |
UDP_RCVBUF | int | UDP socket receiver buffer size (bytes) | Default 1MB (1024000). |
UDT_LINGER | linger | Linger time on close(). | Default 180 seconds. |
UDT_RENDEZVOUS | bool | Rendezvous connection setup. | Default false (no rendezvous mode). |
UDT_SNDTIMEO | int | Sending call timeout (milliseconds). | Default -1 (infinite). |
UDT_RCVTIMEO | int | Receiving call timeout (milliseconds). | Default -1 (infinite). |
UDT_REUSEADDR | bool | Reuse an existing address or create a new one. | Default true (reuse). |
UDT_MAXBW | int64_t | Maximum bandwidth that one single UDT connection can use (bytes per second). | Default -1 (no upper limit). |
UDT_STATE | int32_t | Current status of the UDT socket. | Read only. |
UDT_EVENT | int32_t | The EPOLL events available to this socket. | Read only. |
UDT_SNDDATA | int32_t | Size of pending data in the sending buffer. | Read only. |
UDT_RCVDATA | int32_t | Size of data available to read, in the receiving buffer. | Read only. |
On success, 0 is returned and proper UDT option is set or read; otherwise UDT::ERROR is returned and the specific error information can be retrieved using getlasterror.
Error Name | Error Code | Comment |
EBOUNDSOCK | 5001 | the sepecific option cannot be set on a bound socket. |
ECONNSOCK | 5002 | the specific option cannot be set on a connected socket. |
EINVPARAM | 5003 | the option value or length is invalid. |
EINVSOCK | 5004 | u is an invalid UDT socket. |
the setsockopt method sets the UDT option optName with the value of optval. The parameter of optlen is checked to verify the goodness of the option value. Not all options can be set at any state of UDT. In fact, most options must be set before bind or connect is called, because these values are necessary to initialize certain data structures when a UDT connection is created.
The getsockopt method reads the current option value. The value is written into the buffer pointed by optval and the length is returned in optlen.
./udt4/doc/doc/recvmsg.htm 0000644 0001750 0001750 00000007207 12111175516 015533 0 ustar yunhong yunhong
The recvmsg method receives a valid message.
On success, recvmsg returns the actual size of received message. Otherwise UDT::ERROR is returned and specific error information can be retrieved by getlasterror. If UDT_RCVTIMEO is set to a positive value, zero will be returned if no message is received before the timer expires.
Error Name | Error Code | Comment |
ECONNLOST | 2001 | connection has been broken and no data left in receiver buffer. |
ENOCONN | 2002 | u is not connected. |
EINVSOCK | 5004 | u is not an valid socket. |
ESTREAMILL | 5009 | cannot use recvmsg in SOCK_STREAM mode. |
EASYNCRCV | 6002 | u is non-blocking (UDT_RCVSYN = false) but no message is available. |
ETIMEOUT | 6003 | Timeout on UDT_RCVTIMEO . |
The recvmsg method reads a message from the protocol buffer. The UDT socket must be in SOCK_DGRAM mode in order to send or receive messages. Message is the minimum data unit in this situation. Each recvmsg will read no more than one message, even if the message is smaller than the size of buf and there are more messages available. On the other hand, if the buf is not enough to hold the first message, only part of the message will be copied into the buffer, but the message will still be discarded after this recvmsg call.
In blocking mode (default), recvmsg waits until there is a valid message received into the receiver buffer. In non-blocking mode, recvmsg returns immediately and returns error if no message available.
If UDT_RCVTIMEO is set and the socket is in blocking mode, recvmsg only waits a limited time specified by UDT_RCVTIMEO option. If there is still no message available when the timer expires, error will be returned. UDT_RCVTIMEO has no effect for non-blocking socket.
./udt4/doc/doc/t-error.htm 0000644 0001750 0001750 00000006165 12111175516 015461 0 ustar yunhong yunhong
All UDT API will return an error upon a failed operation. Particularly, UDT defines UDT::INVALID_SOCK and UDT::ERROR as error returned values. Application should check the return value against these two constants (several routine return false as error value).
On error, getlasterror can be used to retrieve the error information. In fact, the function returns the latest error occurred in the thread where the function is called. getlasterror returns an ERRORINFO structure, it contains both the error code and special text error message. Two helper functions of getErrorCode and getErrorMessage can be used to read these information.
The UDT error information is thread local (that is, an error in another thread will not affect the error information in the current thread). The returned value is a reference to the UDT internal error structure.
Note that a successful call will NOT clear the error. Therefore, applications should use the return value of a UDT API to check the result of a UDT call. getlasterror only provides detailed information when necessary. However, application can use getlasterror().clear() to clear the previously logged error if needed.
Example: check UDT::bind error.
In the example above, the output will be:
The UDT error code only reflects the operation error of the UDT socket level. Applications can still read the system level error (e.g., errno in Linux, GetLastError in Windows) to read more specific error information. However, the error message obtained by getErrorMessage contains information of both the UDT level error and the system level error.
./udt4/doc/doc/connect.htm 0000644 0001750 0001750 00000010117 12111175516 015510 0 ustar yunhong yunhong
The connect method connects to a server socket (in regular mode) or a peer socket (in rendezvous mode) to set up a UDT connection.
If success, 0 is returned; otherwise, UDT::ERROR is returned and specific error information can be retrieved by getlasterror.
Error Name | Error Code | Comment |
ENOSERVER | 1001 | server or peer socket does not exist, or there is no network connection. |
ECONNREJ | 1002 | the connection request was rejected by the peer. |
ESECFAIL | 1004 | connection was aborted due to possible attacks. |
ECONNSOCK | 5002 | the socket is not allowed to do a connectconnect call; it is either in listening state or has been already connected. |
EINVSOCK | 5004 | u is not a valid socket ID. |
ERDVUNBOUND | 5008 | the rendezvous mode has been enable, but bind was not called before connect. |
UDT is connection oriented, for both of its SOCK_STREAM and SOCK_DGRAM mode. connect must be called in order to set up a UDT connection. The name parameter is the address of the server or the peer side. In regular (default) client/server mode, the server side must has called bind and listen. In rendezvous mode, both sides must call bind and connect to each other at (approximately) the same time. Rendezvous connect may not be used for more than one connections on the same UDP port pair, in which case UDT_REUSEADDR may be set to false.
UDT connect takes at least one round trip to finish. This may become a bottleneck if applications frequently connect and disconnect to the same address.
When UDT_RCVSYN is set to false, the connect call will return immediately and perform the actual connection setup at background. Applications may use epoll to wait for the connect to complete.
When connect fails, the UDT socket can still be used to connect again. However, if the socket was not bound before, it may be bound implicitly, as mentioned above, even if the connect fails. In addition, in the situation when the connect call fails, the UDT socket will not be automatically released, it is the applications' responsibility to close the socket, if the socket is not needed anymore (e.g., to re-connect).
./udt4/doc/doc/sendfile.htm 0000644 0001750 0001750 00000006444 12111175516 015660 0 ustar yunhong yunhong
The sendfile method sends out part or the whole of a local file.
On success, sendfile returns the actual size of data that has been sent. Otherwise UDT::ERROR is returned and specific error information can be retrieved by getlasterror.
Error Name | Error Code | Comment |
ECONNLOST | 2001 | connection has been broken. |
ENOCONN | 2002 | u is not connected. |
EINVOP | 4000 | File or disk system errors. |
EINVSOCK | 5004 | u is not an valid socket. |
EDGRAMILL | 5010 | cannot use sendfile in SOCK_DGRAM mode. |
EPEERERR | 7000 | The peer side has an unrecoverable error and this call has to be cancelled. |
The sendfile method sends certain amount of out of a local file. It is always in blocking mode an neither UDT_SNDSYN nor UDT_SNDTIMEO affects this method. However, the sendfile method has a streaming semantics same as send.
Note that sendfile does NOT nessesarily require recvfile at the peer side. Sendfile/recvfile and send/recv are orthogonal UDT methods.
./udt4/doc/doc/trace.htm 0000644 0001750 0001750 00000004744 12111175516 015166 0 ustar yunhong yunhong
The perfmon method retrieves the internal protocol parameters and performance trace.
If success, 0 is returned and trace information is written into trace; otherwise, UDT::ERROR is returned and specific error information can be retrieved by getlasterror.
Error Name | Error Code | Comment |
ECONNLOST | 2001 | connection is broken. |
EINVSOCK | 5004 | u is an invalid socket. |
EUNBOUNDSOCK | 5005 | u is not connected. |
The perfmon method reads the performance data since the last time perfmon is executed, or since the connection is started. The result in written into a TRACEINFO structure.
There are three kinds of performance information that can be read by applications: the total counts since the connection is started, the periodical counts since last time the counts are cleared, and instant parameter values.
./udt4/doc/doc/select.htm 0000644 0001750 0001750 00000010462 12111175516 015341 0 ustar yunhong yunhong
The select method queries one or more groups of UDT sockets.
Note: select is deprecated. Please use epoll instead, which is far more efficienct.
If any of the read or write query is positive, select returns the number of UDT sockets that are read for read/write. If no socket is ready before timeout, zero is returned. If there is any error, UDT::ERROR is returned and the specific error information can be retrieved using getlasterror. The readfds and/or writefds will be updated to contain the ready sockets only.
Error Name | Error Code | Comment |
EINVPARAM | 5003 | All three socket sets are empty or at least one of the socket is invalid. |
The UDSET is a structure to store the UDT socket descriptors. If should only be processed with the following macros.
The UDT descriptors sets originaly contains the sockets whose status is to be queried. When select returns, the descriptors sets only contain the sockets that are ready for IO. UD_ISSET can be used to check which one is ready.
readfds is used to detect if any socket in this set is available for reading (recv, recvmsg), for accepting a new connection (accept), or the associated connection is broken. writefds is used to detect if any socket in this set has available buffer for sending (send, sendmsg). Currently exceptfds is not used.
The following example shows how to check if a UDT socket is available for recv.
UDTSOCKET u;
...
timeval tv;
UDSET readfds;
tv.tv_sec = 1;
tv.tv_usec = 0;
UD_ZERO(&readfds);
UD_SET(u, &readfds);
int res = UDT::select(0, &readfds, NULL, NULL, &tv);
if ((res != UDT::ERROR) && (UD_ISSET(u, &readfds)))
// read data from u.
else
// timeout or error
./udt4/doc/doc/tutorial.htm 0000644 0001750 0001750 00000002551 12111175516 015725 0 ustar yunhong yunhong
This tutorial is a quick guide on how to program with UDT and includes explanations and examples. You can learn the basics of UDT programming in this tutorial. This tutorial supposes that you are familiar with socket programming. The example codes can be found in the ./app directory of the software release, which can be compiled and run directly.
In this section:./udt4/doc/index.htm 0000644 0001750 0001750 00000003501 12111175516 014420 0 ustar yunhong yunhong