e8bd737db4
The API is simplified: do not expose the user code to several
queues. A "connection queue" is now an internal concept.
The user processes connections using the single function
lsquic_engine_process_conns(). When this function is called,
only those connections are processed that need to be processed.
A connection needs to be processed when:
1. New incoming packets have been fed to the connection.
2. User wants to read from a stream that is readable.
3. User wants to write to a stream that is writeable.
4. There are buffered packets that can be sent out. (This
means that the user wrote to a stream outside of the
lsquic library callback.)
5. A control frame (such as BLOCKED) needs to be sent out.
6. A stream needs to be serviced or delayed stream needs to
be created.
7. An alarm rings.
8. Pacer timer expires.
To achieve this, the library places the connections into two
priority queues (min heaps):
1. Tickable Queue; and
2. Advisory Tick Time queue (ATTQ).
Each time lsquic_engine_process_conns() is called, the Tickable
Queue is emptied. After the connections have been ticked, they are
queried again: if a connection is not being closed, it is placed
either in the Tickable Queue if it is ready to be ticked again or
it is placed in the Advisory Tick Time Queue. It is assumed that
a connection always has at least one timer set (the idle alarm).
The connections in the Tickable Queue are arranged in the least
recently ticked order. This lets connections that have been quiet
longer to get their packets scheduled first.
This change means that the library no longer needs to be ticked
periodically. The user code can query the library when is the
next tick event and schedule it exactly. When connections are
processed, only the tickable connections are processed, not *all*
the connections. When there are no tick events, it means that no
timer event is necessary -- only the file descriptor READ event
is active.
The following are improvements and simplifications that have
been triggered:
- Queue of connections with incoming packets is gone.
- "Pending Read/Write Events" Queue is gone (along with its
history and progress checks). This queue has become the
Tickable Queue.
- The connection hash no longer needs to track the connection
insertion order.
|
||
|---|---|---|
| docs | ||
| include | ||
| src | ||
| test | ||
| wincompat | ||
| APIs.txt | ||
| BUILD-WINDOWS.md | ||
| CHANGELOG | ||
| CMakeLists.txt | ||
| CONTRIBUTORS.txt | ||
| Dockerfile | ||
| dox.cfg | ||
| EXAMPLES.txt | ||
| LICENSE | ||
| LICENSE.chrome | ||
| README.md | ||
LiteSpeed QUIC (LSQUIC) Client Library README
Description
LiteSpeed QUIC (LSQUIC) Client Library is an open-source implementation of QUIC functionality for clients. It is released in the hope to speed the adoption of QUIC. Most of the code in this distribution is used in our own products: LiteSpeed Web Server and ADC. We think it is free of major problems. Nevertheless, do not hesitate to report bugs back to us. Even better, send us fixes and improvements!
Currently supported QUIC versions are Q035, Q037, Q038, Q039, and Q041. Support for newer versions will be added soon after they are released. The version(s) specified by IETF QUIC WG will be added once the IETF version of the protocol settles down a little.
Documentation
The documentation for this module is admittedly sparse. The API is
documented in include/lsquic.h. If you have doxygen, you can run
doxygen dox.cfg or make docs. The example program is
test/http_client.c: a bare-bones, but working, QUIC client. Have a look
in EXAMPLES.txt to see how it can be used.
Requirements
To build LSQUIC, you need CMake, zlib, and BoringSSL. The example program uses libevent to provide the event loop.
Building BoringSSL
BoringSSL is not packaged; you have to build it yourself. The process is
straightforward. You will need go installed.
- Clone BoringSSL by issuing the following command:
git clone https://boringssl.googlesource.com/boringssl
cd boringssl
- Check out stable branch:
git checkout chromium-stable
- Compile the library
cmake . && make
If you want to turn on optimizations, do
cmake -DCMAKE_BUILD_TYPE=Release . && make
- Install the library
This is the manual step. You will need to copy library files manually.
LSQUIC client library needs two: ssl/libssl.a and crypto/libcrypto.a.
To install these in /usr/local/lib, you should do the following:
BORINGSSL_SOURCE=$PWD
cd /usr/local/lib
sudo cp $BORINGSSL_SOURCE/ssl/libssl.a .
sudo cp $BORINGSSL_SOURCE/crypto/libcrypto.a .
If you do not want to install the library (or do not have root), you can do this instead:
BORINGSSL_SOURCE=$PWD
mkdir -p $HOME/tmp/boringssl-libs
cd $HOME/tmp/boringssl-libs
ln -s $BORINGSSL_SOURCE/ssl/libssl.a
ln -s $BORINGSSL_SOURCE/crypto/libcrypto.a
Building LSQUIC Client Library
LSQUIC's http_client and the tests link BoringSSL libraries statically.
Following previous section, you can build LSQUIC as follows:
- Get the source code
git clone https://github.com/litespeedtech/lsquic-client.git
cd lsquic-client
- Compile the library
cmake -DBORINGSSL_INCLUDE=$BORINGSSL_SOURCE/include \
-DBORINGSSL_LIB=$HOME/tmp/boringssl-libs .
make
- Run tests
make test
Building with Docker
The library and http_client example can be built with Docker.
docker build -t lsquic-client .
Then you can use the http_client example from the command line.
docker run -it --rm lsquic-client http_client -H www.google.com -s 74.125.22.106:443 -p /
Platforms
The client library has been tested on the following platforms:
- Linux
- x86_64
- ARM (Raspberry Pi 3)
- FreeBSD
- i386
- Windows
- x86_64
- MacOS
- x86_64
Have fun,
LiteSpeed QUIC Team.
Copyright (c) 2017 LiteSpeed Technologies Inc