README.md

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