1# libutp - The uTorrent Transport Protocol library. 2Copyright (c) 2010 BitTorrent, Inc. 3 4uTP is a TCP-like implementation of [LEDBAT][ledbat] documented as a BitTorrent 5extension in [BEP-29][bep29]. uTP provides provides reliable, ordered delivery 6while maintaining minimum extra delay. It is implemented on top of UDP to be 7cross-platform and functional today. As a result, uTP is the primary transport 8for uTorrent peer-to-peer connections. 9 10uTP is written in C++, but the external interface is strictly C (ANSI C89). 11 12## The Interface 13 14The uTP socket interface is a bit different from the Berkeley socket API to 15avoid the need for our own select() implementation, and to make it easier to 16write event-based code with minimal buffering. 17 18When you create a uTP socket, you register a set of callbacks. Most notably, the 19on_read callback is a reactive callback which occurs when bytes arrive off the 20network. The write side of the socket is proactive, and you call UTP_Write to 21indicate the number of bytes you wish to write. As packets are created, the 22on_write callback is called for each packet, so you can fill the buffers with 23data. 24 25The libutp interface is not thread-safe. It was designed for use in a 26single-threaded asyncronous context, although with proper synchronization 27it may be used from a multi-threaded environment as well. 28 29See utp.h for more details and other API documentation. 30 31## Examples 32 33See the utp_test and utp_file directories for examples. 34 35## Building 36 37uTP has been known to build on Windows with MSVC and on linux and OS X with gcc. 38On Windows, use the MSVC project files (utp.sln, and friends). On other platforms, 39building the shared library is as simple as: 40 41 make 42 43To build one of the examples, which will statically link in everything it needs 44from libutp: 45 46 cd utp_test && make 47 48## Packaging and API 49 50The libutp API is considered unstable, and probably always will be. We encourage 51you to test with the version of libutp you have, and be mindful when upgrading. 52For this reason, it is probably also a good idea to bundle libutp with your 53application. 54 55## License 56 57libutp is released under the [MIT][lic] license. 58 59## Related Work 60 61Research and analysis of congestion control mechanisms can be found [here.][survey] 62 63[ledbat]: http://datatracker.ietf.org/wg/ledbat/charter/ 64[bep29]: http://www.bittorrent.org/beps/bep_0029.html 65[lic]: http://www.opensource.org/licenses/mit-license.php 66[survey]: http://datatracker.ietf.org/doc/draft-ietf-ledbat-survey/ 67