libRaptorQ-RAW.tex

%    Copyright (C)  2018, Luca Fulchir<luca@fulchir.it>
%    Permission is granted to copy, distribute and/or modify this document
%    under the terms of the GNU Free Documentation License, Version 1.3
%    or any later version published by the Free Software Foundation;
%    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
%    A copy of the license is included in the section entitled "GNU
%    Free Documentation License".



\documentclass[11pt,a4paper]{refart}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{hyperref}
\usepackage{makeidx}
\usepackage{verbatimbox}
\usepackage{listings}
\usepackage{color}

\definecolor{mygreen}{rgb}{0,0.6,0}
\definecolor{mygray}{rgb}{0.5,0.5,0.5}
\definecolor{mymauve}{rgb}{0.58,0,0.82}

\lstset{ %
  backgroundcolor=\color{white},   % choose the background color; you must add \usepackage{color} or \usepackage{xcolor}
  basicstyle=\footnotesize,        % the size of the fonts that are used for the code
  breakatwhitespace=false,         % sets if automatic breaks should only happen at whitespace
  breaklines=true,                 % sets automatic line breaking
  captionpos=b,                    % sets the caption-position to bottom
  commentstyle=\color{mygreen},    % comment style
  deletekeywords={...},            % if you want to delete keywords from the given language
  escapeinside={\%*}{*)},          % if you want to add LaTeX within your code
  extendedchars=true,              % lets you use non-ASCII characters; for 8-bits encodings only, does not work with UTF-8
  frame=single,                    % adds a frame around the code
  keepspaces=true,                 % keeps spaces in text, useful for keeping indentation of code (possibly needs columns=flexible)
  keywordstyle=\color{blue},       % keyword style
  language=C,                 % the language of the code
  %otherkeywords={*,...},            % if you want to add more keywords to the set
  %numbers=left,                    % where to put the line-numbers; possible values are (none, left, right)
  %numbersep=5pt,                   % how far the line-numbers are from the code
  %numberstyle=\tiny\color{mygray}, % the style that is used for the line-numbers
  rulecolor=\color{black},         % if not set, the frame-color may be changed on line-breaks within not-black text (e.g. comments (green here))
  showspaces=false,                % show spaces everywhere adding particular underscores; it overrides 'showstringspaces'
  showstringspaces=false,          % underline spaces within strings only
  showtabs=false,                  % show tabs within strings adding particular underscores
  stepnumber=2,                    % the step between two line-numbers. If it's 1, each line will be numbered
  stringstyle=\color{mymauve},     % string literal style
  tabsize=4,                       % sets default tabsize to 2 spaces
  title=\lstname                   % show the filename of files included with \lstinputlisting; also try caption instead of title
}

\title{Using libRaptorQ library: RAW interface}
\date{\today}
\makeindex

\begin{document}
\maketitle

\begin{abstract}

\textbf{libRaptorQ} is a C++11
 implementation of the RaptorQ Forward Error Correction. It includes two interfaces, one derived from the \href{https://tools.ietf.org/html/rfc6330}{RFC6330} standard, and one RAW API for a more flexible and easy usage.

This document is only about the RAW interface.

The implementation was started as a university laboratory project, and will be later used and included in \href{https://www.fenrirproject.org}{Fenrir}, the
maintainer's master thesis project.



\end{abstract}

\vfill\hfill
\begin{verbbox}[\tiny]
Copyright (C)  2015-2018, Luca Fulchir<luker@fenrirproject.org>
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
\end{verbbox}
\theverbbox

\newpage
\tableofcontents
\newpage

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Contacts}\index{Contacts}

The main development and dicussions on the project, along with bug reporting, happens on
\href{https://fenrirproject.org/Luker/libRaptorQ}{the main website}.

\marginlabel{Mailing Lists} Mailing lists are available at \href{https://fenrirproject.org/lists}{https://fenrirproject.org/lists}\\
The two mailing lists are for development and announcements, but due to the low traffic of the development mailing list, it
can also be used by users for questions on the project.

\marginlabel{IRC} Since there are not many developers for now, the main irc channel is \textbf{\#fenrirproject} on freenode


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Build \& install}
\subsection{Get the source code}
This document follows the 1.0 stable release.

You can get the tarballs from the main website here:\\
\href{https://fenrirproject.org/Luker/libRaptorQ/tags}{https://fenrirproject.org/Luker/libRaptorQ/tags}

Or you can check out the repository (warning: development in progress):

\begin{verbatim}
$ git clone https://fenrirproject.org/Luker/libRaptorQ.git
\end{verbatim}

You can also get it from github:

\begin{verbatim}
$ git clone https://github.com/LucaFulchir/libRaptorQ.git
\end{verbatim}

\index{GPG}\marginlabel{GPG verification:}
Once you have cloned it, it's always a good thing to check the repository gpg
signatures, so you can import my key with:

\begin{verbatim}
$ gpg --keyserver pgp.mit.edu --recv-key 7393DAD255BEB5751DBDA04AB11CD823BA278C85
\end{verbatim}


Now you have the source, and the key, it's enough to check the signature of the
last commit:

\begin{verbatim}
$ git log -n 1 --show-signature
\end{verbatim}

The important part is that you get something like this:

\begin{verbbox}[\footnotesize]
 gpg: Signature made Mon 11 Dec 2017 21:55:28 CET
 gpg:                using RSA key 8F7474044095B405D0F042F0A2CCA134BC7C8572
 gpg: Good signature from "Luca Fulchir <luker@fenrirproject.org>" [unknown]
 gpg:                 aka "Luca Fulchir <luca@fulchir.it>" [unknown]
 gpg: WARNING: This key is not certified with a trusted signature!
 gpg:          There is no indication that the signature belongs to the owner.
 Primary key fingerprint: 7393 DAD2 55BE B575 1DBD A04A B11C D823 BA27 8C85
\end{verbbox}
\theverbbox

And as long as you got the right key, and you find the \textbf{"gpg: Good signature"} string,
you can be sure you have the right code.

The main development happens in the $master$ branch, while we keep one branch for each stable version.


\subsection{Dependencies}\index{dependencies}

libRaptorQ has 4 dependencies:
\begin{description}
\item[\textbf{Eigen3}] This is used for matrix manipulation, which is a big part of RaptorQ.
\item[\textbf{lz4}] Used to compress cached precomputations.
\item[\textbf{git}] This is used not only to get the source, but also by the build system. We get the last git commit id and feed it to clang or gcc as seed for their internal random number generator. This makes it possible to have reproducible builds.
\item[\textbf{optionparser}] Library used to parse the command line easily in C++, without exceptions.
\end{description}

All dependencies are included in the sources, so you do not need to download and compile them.\\
Eigen3 is only needed at build time, so there is no need to download it again. we use the 3.3.4 version.\\
LZ4 is included as a git submodule. if you do not have it, run:
\begin{verbatim}
$ git submodule init
$ git submodule update
\end{verbatim}
and LZ4 w
ill be built
 statically in the library (it will not be installed on the system)

\subsection{Build \& Install}

libRaptorQ uses the cMake build system, so things are fairly standard:

\begin{verbatim}
$ cd libRaptorQ.git
$ mkdir build
$ cd build
$ cmake ../
$ make -j 4
\end{verbatim}

By default, the libRaptorQ project tries to have deterministic builds. This means that if you compile things twice, or with two different computers, the
hash of the resulting library will be the same, provided that the same compiler (clang, gcc 4.8, gcc 4.9 etc) was used. Currently the only exception is the clang
compiler with the \textit{PROFILING} option enabled, and this will not likely be solved.

\index{cMake}
There are lots of options, you can use in cmake. As always, you can change them by adding ``\textbf{-Dcmake\_option=cmake\_value}'' when calling cmake.

You can always use the cmake-gui or ccmake commands to have the list of possible options.

The ones we recognize are:

\begin{description}
\item[LTO] ON/OFF. Default:\textbf{ON}. Enables \textit{Link Time Optimizatios} for clang or gcc. Makes libraries smaller and better optimized.
\item[PROFILING] ON/OFF. Default:\textbf{ON}.
Profiling compiles everything once, then runs a test to see which code paths are used more, and then
recompiles everything again, but making sure that the binary is optimized for those paths. Works with clang and gcc. Provides a slight speedup.
\item[CMAKE\_C\_COMPILER] gcc and clang are directly supported. other should work, too. This is only used if you want to build the C example.
\item[CMAKE\_CXX\_COMPILER] g++, clang++ are directly supported. other should work, too.
\item[CLANG\_STDLIB] ON/OFF. Default:\textbf{OFF}.use clang's libc++ standard library. Only available with clang.
\item[CMAKE\_BUILD\_TYPE] Type of build. you can choose between ``Debug'', ``Release'', ``MinSizeRel'' or ``RelWithDebInfo''
\item[CMAKE\_INSTALL\_PREFIX] Default to \textit{/usr/local}. Change it to fit your distribution guidelines.
\item[RQ\_ENDIANNESS] \texttt{Auto,BigEndian,LittleEndian} Force the build to use one endianness ot the other
\item[RQ\_LINKER] \texttt{Auto,gold,ld,bsd} Force the build to use one linker or the other
\item[USE\_LZ4] ON/OFF. Default:\textbf{ON}. compile with support for lz4
\end{description}

Then you can build everything by running:
\begin{verbatim}
$ make -j 4
\end{verbatim}
Of course, you can configure the number of parallel jobs (the \textit{-j} parameter) to be what you need.

\marginlabel{Optional make targets:}
The following optional targets are also supported:
\begin{verbatim}
$ make docs tests examples
$ make everything
\end{verbatim}
The ``docs'' target builds this document, but you need latex with the refman style.
The tests are only useful to check perfromance of rfc compliance right now. ``examples'' compiles the C and C++ examples, which will not be installed.

\index{Install}\marginlabel{\textbf{Install:}}
The installation process is very simple:

\begin{verbatim}
$ make install DESTDIR=...
\end{verbatim}

You can change the \textit{DESTDIR} parameter to fit your distribution guidelines.

\newpage

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Working with RaptorQ}
\subsection{Theory (you really need this)}\index{Theory}

To be able to work with liRaptorQ, you must first understand how the RaptorQ algorithms works. We won't go into the details, but just what you need
to be able to tune the algorithm to your needs.


\marginlabel{Fountain codes:}
Fountain codes are a special \textit{Forward-Error-Correcting} code class, which characteristic is simple: if you want to send $K$ packets, you actually
send $K+X$ packets, and the receiver only needs to get any $K$ packets to be able to reconstruct your data. The number $X$ of overhead packets can be as big
as you need (theoretically infinite), so you can tune it to be slightly higher than the expected packet loss.

\marginlabel{Systematic codes:} RaptorQ is also a systematic code. This means that those first $K$ packets are the input \textit{as-is} (\textbf{source symbols}),
and the $X$ packets (\textbf{repair symbols}) have the information needed to recover any of the lost source packets. This has the big advantage of
avoiding any kind of time and memory consuming decoding if there is no packet loss during the transmission.

\marginlabel{Complexity:} The RaptorQ algorithm is often presented as having a linear time encoder and decoder. This is both false and misleading.
Generating the source or repair symbols from the intermediate symbols has linear complexity. Generating the intermediate symbols has cubic complexity on the
number of symbols. Which is a completely different thing.
It is still very quick. On a core i7, 2.4Ghz, you need to wait \textit{0.4ms} for $10$ symbols, \textit{280ms} for 1.000 symbols, but it can take an hour for $27.000$ symbols.
RaptorQ handles up to $56.403$ symbols.

\marginlabel{\textbf{Caching}} libRaptorQ can work with big matrices that take a lot of time to compute. For this reason the matrices can be saved once they have
been computed the first time. libRaptorQ uses a \textbf{local} cache. The matrix can be compressed with LZ4.

\subsection{RaptorQ: Blocks \& Symbols}

To understand how to properly use and tune libRaptorQ, you first need to understand how RaptorQ handles its inputs, outputs, and what the time and memory
constraints are.

\index{Sequencing}\marginlabel{Input sequencing:}
The RC6330 needs to have the whole input you want to send before it can start working.\\
This means that You should buffer the data you are sending, and then when you have a block big enough you pass it to libRaptorQ, which will start generating symbols.

Contrary to the RFC6330, the RAW api is about a single block of data. You will have to divide your input in multiple blocks by hand, and decide by yourself how to send the encoded symbols. This will increase your flexibility, at the expense of not being conformant to RFC6330.
Note that a RaptorQ block does not need to be completely filled since the block is automatically padded with zeros, but you need to somehow tell the receiver how much data you have in that block so that it can know where the padding starts. RFC6330 does this with the \texttt{OTI} parameters


\index{Sequencing!Sizes}\marginlabel{Sizes:} Each block can have up to \textit{$56.403$ symbols}, and each
symbol can have up to \textit{size\_t bytes} long ($2^{32}$ on 32 bit machines, $2^{
	64}$ on 64 bits
). Please remember the Complexity discussion before using high values.


\index{Interleaving}\marginlabel{Interleaving:}
Contrary to the RFC6330 the RAW api does not include any kind of interleaving

\marginlabel{Memory and Time:}
Memory and time requirements are to be considered, though, as RaptorQ needs to run a cubic algorithm on matrix of size $K*K$, where $K$ is the number of symbols in each block.\\
The algorithm needs to keep in memory two of these matrices, although most of the work is done on only one.\\
This is actually a lot. More benchmarks and optimizations will come later, for now remember that with 10 symbols it takes something like 0.4ms on a core i7 2.4GHZ, 280ms with 1000 symbols, and up to an hour with 27.000 symbols. YMMV.


\subsection{C++ interface}
\index{Interface!C++}
To use the C++ interface you only need to include the \textbf{RaptorQ/RaptorQ\_v1.hpp} header, and link \textbf{libRaptorQ} and your threading library (usually \textit{libpthread}).

You can also use the library as a header-only include, by including \textbf{RaptorQ/RaptorQ\_v1\_hdr.hpp}. All your code should keep working even if you switch between linked and header-only at a later date. If you use the header-only version, remember to have Eigen3 in your include path, and to include the needed definitions, \texttt{RQ\_LITTLE\_ENDIAN} or \texttt{RQ\_BIG\_ENDIAN}

\marginlabel{Namespace}
Since the libRaptorQ library now has two very different usages, everything was split into two namespaces: \textbf{RFC6330} and \textbf{RaptorQ}. The names should be explanatory: the first namespace is for the RFC interface, while the second namespace is for the low-level interface.

Since we will cover only the \textbf{RaptorQ} namespace here, remember that everything we talk about is in this namespace.

\newpage

\index{Iterators}\marginlabel{Templates}
There are two main classes you will use:
\begin{verbatim}
template <typename Rnd_It, typename Fwd_It>
class Encoder

template <typename In_It, typename Fwd_It>
class Decoder
\end{verbatim}

As you might guess, the classes for the encoder and decoder take two template parameters.\\
For the \textbf{Encoder}, the first parameter \textit{MUST} be a \textit{random access iterator} to the input data, and the second parameter is a
\textit{forward iterator}. The random access iterator will be used to scan your input data. The forward iterator will be used to write the data to your output.\\
The same is done for the \textbf{Decoder}, but the first iterator can be just an input iterator, 
and nothing more.

\subsubsection{Caching precomputations}
\index{Cache!C++'}
libRaptorQ can now cache the most used matrices for a quicker reference. The cache can be scaled up or down dynamically.

\begin{description}

\item[local\_cache\_size] \textbf{const uint64\_t local\_cache}\\
\textbf{return: bool}\\
Set the local cache size. returns false on error.

\item[get\_local\_cache\_size()] \textbf{return: uint64\_t}\\
get the size of our local cache

\item[supported\_compressions()] \textbf{return: Compress} \\
Get the bitmask of all supported compression algorithms. currently only \textbf{Compress::NONE} and \textbf{Compress::LZ4}.

\item[get\_compression()] \textbf{return: Compress} \\
Get the current compression used.

\item [set\_compression] \textbf{const Compress compression} \\
\textbf{return: bool}\\
Try to set a compression algorithm. LZ4 is not a mandatory dependency, so we might not have it

\end{description}


\newpage
\subsubsection{The Encoder}
\index{Encoder!C++}
The constructor is the following:
\begin{lstlisting}[language=C++]
Encoder (const Block_Size symbols, const size_t symbol_size);
\end{lstlisting}

Which is really simple. The first is an Enum that will help you get the correct block size, and the second is your arbitrary symbol size.

Since the RaptorQ algorithm only works with specific block sizes, You can get all the possible block sizes from \texttt{RaptorQ\_\_v1::*blocks}, which is a pointer to an array of 477 possible sizes, from $10$ to $56403$. You can cast each element in this array to \texttt{uint16\_t} to verify the actual value, or directly name them, as in \texttt{RaptorQ\_\_v1::Block\_Size::Block\_42}.

If you pass unsafe values the encoder (or decoder) will refuse to work.

You can instantiate an encoder for example by doing:

\begin{lstlisting}[language=C++]
std::vector<uint32_t> input, output;
...
using T_it = typename std::vector<uint32_t>::iterator;
using RaptorQ = RaptorQ__v1;
RaptorQ::Encoder<T_it, T_it> enc (
						RaptorQ::Block_Size::Block_42,					
						1500);
														
\end{lstlisting}

This will create an Encoder that works on vectors of unsigned 32 bit integers for both input and output, that will be fed to a block of size 42 
symbols of size 1500 bytes.

The available methods for the encoder are the following:

\begin{description}
\item[operator bool()] \textbf{return:bool}\\
False if constructor parameters did not make sense. Else true.


\item[symbol\_size()] \textbf{return: uint16\_t} The size of a symbol.

\item[symbols] \textbf{Input:uint8\_t sbn}\\
\textbf{return: uint16\_t}\\
The number of symbols in a specific block. different blocks can have different symbols.

\item[max\_repair] \textbf{Input: const uint8\_t sbn)}\\
\textbf{return: uint32\_t}\\
The maximum amount of repair symbols that you can generate. Something less than $2^{24}$, but the exact number depends on the number of symbols in a block

\item[begin\_source()] \textbf{return: Symbol\_Iterator<Rnd\_It, Fwd\_It>}\\
This returns an iterator to the symbols in this block. Source symbols only
\item[end\_source()] \textbf{return: const Symbol.\_Iterator<Rnd\_It, Fwd\_It>}\\
This returns an iterator to the end of the source symbols.
\item[begin\_repair()] \textbf{return: Symbol\_Iterator<Rnd\_It, Fwd\_It>}\\
This returns an iterator to the symbols in this block. Source symbols only
\item[end\_repair] \textbf{Input: const uint32\_t max\_repair}\\
\textbf{return: const Symbol.\_Iterator<Rnd\_It, Fwd\_It>}\\
This returns an iterator to the end of the source symbols.

\item[has\_data()] \textbf{return: bool}\\
Did you feed this encoder the data? That is: did you use \texttt{set\_data()} without calling \texttt{clear\_data()} later?

\item[set\_data] \textbf{Input: const Rnd\_It \&from}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const Rnd\_It \&to}\\
\textbf{return: size\_t}\\
Set the iterators from which we load all the data.

\item[clear\_data]\textbf{return: void}\\
clear all data, without deallocating memory so that things might be slightly faster next time.

\item[ready()]\textbf{return: bool}\\
Is everything decoded?

\item[stop()]\textbf{return void}\\
Stop any current decoding and return error.

\item[precompute\_sync()]\textbf{return: bool}\\
Start a precomputation so that next computations might be slightly faster. Only return when the precomputation is done or stop() was called.

\item[compute\_sync()]\textbf{return: bool}\\
Compute internal symbols from the input. Only return when the computation is done or stop() was called.

\item[precompute()] \textbf{return: std::shared\_future<Error>}\\
Start a precomputation so that next computations might be slightly faster. Returns immediately, but the user can wait or poll on the returned future.

\item[compute()] \textbf{return: std::shared\_future<Error>}\\
Start a computation on the data. Returns immediately, but the user can wait or poll on the returned future.

\item[encode]\textbf{Input:Fwd\_It \&output}\\
.\ \ \ \ \ \ \ \ \textbf{const Fwd\_It end}\\
.\ \ \ \ \ \ \ \ \textbf{const uint32\_t id}\\
\textbf{return: size\_t}\\
Once the computation is finished, you can get the encoded symbols. The first \texttt{symbols()} are source symbols, and the next are repair symbols. Returns the number of iterators written into the \texttt{output} iterator, which will point to the first non-written element after the symbol.

\end{description}

\subsubsection{Symbols}
\index{Symbols!C++}
With the \textit{begin\_source()/end\_source()/begin\_repair()/end\_repair(..)} calls you get \textit{input iterators} to the symbols. A symbol has the following type:
\begin{lstlisting}[language=C++]
template <typename Rnd_It, typename Fwd_It>
class Symbol
\end{lstlisting}
and exposes the	 following methods:
\begin{description}
\item[id()]\textbf{return: uint32\_t}
\item[operator()]\textbf{Input: Fwd\_It \&start}\\
.\ \ \ \ \ \ \ \ \ \ \ \textbf{const Fwd\_It end}\\
\textbf{return: uint32\_t}\\
Write the symbol into the start-end iterators provided by the user. Afterwards the start iterator will point to the first non-written element after the symbol
\end{description}



\newpage
\subsubsection{The Decoder}
\index{Decoder!C++}

The decoder is a bit simpler than the encoder.

There are two constructors for the Decoder:

\begin{lstlisting}[language=C++]
 std::vector<uint32_t> input, output;
 using T_it = typename std::vector<uint32_t>::iterator;
 RaptorQ::Decoder<T_it, T_it> dec (
                 const OTI_Common_Data common,
                 const OTI_Scheme_Specific_Data scheme)
                              
 RaptorQ::Decoder<T_it, T_it> dec (uint64_t size,
                                  uint16_t symbol_size,
                                  uint16_t sub_blocks,
                                  uint8_t blocks)
\end{lstlisting}

Which should be pretty self-explanatory, once you understand how the encoder works:
you can either get the \texttt{OTI} parameters from the Encoder or you can provide the raw values by yourself (only if you know what you are doing)

The remaining methods are:
\begin{description}
\item[begin()] \textbf{return: Block\_Iterator<In\_It, Fwd\_It>}\\
This returns an iterator to the blocks in which the RFC divided the input data.
\item[end()] \textbf{return: const Block\_Iterator<In\_It, Fwd\_It>}\\
This returns an iterator to the end of the blocks in which the RFC divided the input data.
\item[operator bool()] \textbf{return: bool}\\
check if the Decoder was initialized properly

\item[compute] \textbf{Input: const Compute flags}\\
\textbf{return: std::future<std::pair<Error, uint8\_t> >}\\
Only enabled if you use C++11. Start the computation as soon as enough data is available.\\
Compute flags:
\begin{lstlisting}[language=C++]
enum class Compute : uint8_t {
NONE 
// report every time there is more data, but only
// if that data starts at the beginning.
PARTIAL_FROM_BEGINNING
PARTIAL_ANY
COMPLETE // only when all the data is available
NO_BACKGROUND // only return after the computation is finished
NO_POOL // do not use the thread pool
NO_RETRY // do not retry if we failed, even if there is more data
};
\end{lstlisting}

\item[end\_of\_input] \textbf{Input: const Fill\_With\_Zeros fill}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint8\_t block}\\
\textbf{return: std::vector<bool>}\\
Tell the decoder that we know that there will be no more data for this block.
The first parameter is an \texttt{enum}, either \textbf{Fill\_With\_Zeros::YES}  or \textbf{Fill\_With\_Zeros::NO}
If you choose \texttt{YES} then the repair symbols will be discarded, the missing symbols will be filled with zeros
and for output you will get the bitmask for which byte was received (true) or was filled with zeros (false).\\
If you choose \textbf{Fill\_With\_Zeros::NO} you will get \textit{an empty vector}
\item[end\_of\_input] \textbf{Input: const Fill\_With\_Zeros fill}\\
\textbf{return: std::vector<bool>}\\
Same as before, but we know that there will be no more inputs for any block.


\item[decode\_symbol]\textbf{Input: Fwd\_It \&start}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const Fwd\_It end}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint16\_t esi}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint8\_t sbn}
\textbf{return: uint64\_t}\\
Decode a single symbol. you need to provide the block number and symbol identifier.

\item[decode\_bytes] \textbf{Input: Fwd\_It \&start}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const Fwd\_It end}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint8\_t skip}\\
\textbf{return: uint64\_t}\\
Decode everything. returns the number of bytes written. You can start writing the output \texttt{skip} bytes after the first iterator in case the parameters you have used do not align (set to $0$ for everyone else).
\item[decode\_bytes] \textbf{Input: Fwd\_It \&start}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const Fwd\_It end}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint8\_t skip}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint8\_t sbn}\\
\textbf{return: uint64\_t}\\
Same as before, but you can specify a \textbf{Single Block Number} instead of the whole output
\newpage
\item[decode\_aligned]\textbf{Input: Fwd\_It \&start}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const Fwd\_It end}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint8\_t skip}\\
\textbf{return: aligned\_res}\\
Same as \texttt{decode\_bytes}, but yu can use this if for some weir reason the data does not align with the type of the output
\begin{lstlisting}[language=C++]
struct aligned_res
{
uint64_t written; // iterators written
uint8_t offset; // bytes written in the last
				// iterator if it was not full
};
\end{lstlisting}
\item[decode\_block\_aligned]\textbf{Input: Fwd\_It \&start}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const Fwd\_It end}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint8\_t skip}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint8\_t sbn}\\
\textbf{return: aligned\_res}\\
Same as before, but now you can choose the block


\item[add\_symbol]\textbf{Input: In\_It \&start}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const In\_It end}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint32\_t esi}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint8\_t sbn}\\
\textbf{return: RFC6330::Error}\\
Add one symbol, while explicitly specifying the symbol id and the block id.

\item[add\_symbol]\textbf{Input: In\_It \&start}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const In\_It end}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint32\_t id}\\
\textbf{return: RFC6330::Error}\\
Same as before, but extract the block id and the symbol id from the \textit{id} parameter

\item[blocks\_ready()]\textbf{return: uint8\_t}\\
return the number of the blocks that are ready for output
\item[is\_ready()]\textbf{return: bool}\\
Whether everything has been decoded or not.
\item[is\_block\_ready]\textbf{Input:const uint8\_t block}\\
\textbf{return: bool}\\
Test if the specified block has been decoded or not


\item[free]\textbf{Input: const uint8\_t sbn}\\
\textbf{return: void}\\
You might have stopped using a block, but the memory is still there. Free it.

\item[bytes()] \textbf{return: uint64\_t}\\
The total bytes of the output
\item[blocks()] \textbf{return: uint8\_t}\\
The number of blocks.

\item[block\_size()] \textbf{Input: const uint8\_t sbn}\\
\textbf{return: uint32\_t}\\
The block size, in bytes. Each block can have different symbols and thus different size.

\item[symbol\_size()] \textbf{return: uint16\_t} The size of a symbol.

\item[symbols] \textbf{Input:uint8\_t sbn}\\
\textbf{return: uint16\_t}\\
The number of symbols in a specific block. different blocks can have different symbols.
\end{description}
\newpage

\subsection{C interface}\index{Interface!C}
The C interface looks a lot like the C++ one.\\
You need to include the \textbf{RaptorQ/RFC6330.h} header, and link the \textit{libRaptorQ} library.\\
\marginlabel{Static linking}\index{Static Linking}
If you are working with the static version of libRaptorQ remember to link the C++ standard library used when
compiling the library (\textit{libstdc++} for gcc or maybe \textit{libc++} for clang), your threding library (usually \textit{libpthread}), and the C math library (\textit{libm}).\\

\marginlabel{\textbf{API versioning}} To better support future changes in the API and to help you with future changes,
there are only 2 API calls in this library:
\begin{description}
\item[RFC6330\_api] \textbf{Input: uint32\_t version}\\
\textbf{return: struct RFC6330\_base\_api*}\\
This will give you a pointer to a struct containing pointers to the calls you will use.
The struct will change depending on which API you request (currently only number $1$ is supported).
Since this pointer works for every api, you have to cast it to the struct you expect, or you will not see
the pointers to the function calls. Then you can use that pointer to access of the functions, like:
\begin{lstlisting}[language=C]
struct RFC6330_v1 *rfc = (struct RFC6330_v1*)
									RFC6330_api (1);
rfc->set_compression (RQ_COMPRESS_LZ4);
\end{lstlisting}
\item[RFC6330\_free\_api] \textbf{Input:struct RFC6330\_base\_api **api}\\
\textbf{return: void}\\
As the name implies, this frees the given structure.
\end{description}

Again, we only support API version 1 at the moment.

\index{Cache!C}
\subsubsection{Cache settings}
As for the C++11 interface, you can get and set the local memory cache.

\begin{description}
\item[supported\_compressions] \textbf{return: RFC6330\_Compress}\\
return the bitmask of all supported compressions. currently either \texttt{RQ\_COMPRESS\_NONE} or \texttt{RQ\_COMPRESS\_LZ4}

\item[get\_compression] \textbf{return: RFC6330\_Compress}\\
Which compression are we currently using?

\item[set\_compression] \textbf{Input: const RFC6330\_Compress compression}\\
\textbf{return: bool}\\
Set a compression method or another.

\item[local\_cache\_size] \textbf{Input: const size\_t bytes}\\
\textbf{return: size\_t}\\
Set the maximum amount of cache usable. Default: $0$
\item[get\_local\_cache\_size] \textbf{return: size\_t}\\
get the amount of cache configured
\end{description}

\subsubsection{C Constructors}
The first thing you need is to allocate the encoder or the decoder.

The C interface is just a wrapper around the C++ code, so you still have to specify the same things as before.
A quick glance at the constructors should give you all the information you need:

\begin{lstlisting}[language=C]
typedef enum { RQ_NONE, RQ_ENC_8, RQ_ENC_16,
               RQ_ENC_32, RQ_ENC_64, RQ_DEC_8,
               RQ_DEC_16, RQ_DEC_32, RQ_DEC_64}
              							RFC6330_type;
\end{lstlisting}

\begin{description}
\item[Encoder] \textbf{Input:const RFC6330\_type type}\\
.\ \ \ \ \ \ \ \ \ \textbf{void *data\_from}\\
.\ \ \ \ \ \ \ \ \ \textbf{const uint64\_t size}\\
.\ \ \ \ \ \ \ \ \ \textbf{const uint16\_t min\_subsymbol\_size}\\
.\ \ \ \ \ \ \ \ \ \textbf{const uint16\_t symbol\_size}\\
.\ \ \ \ \ \ \ \ \ \textbf{const size\_t max\_sub\_block}\\
\textbf{return: RFC6330\_ptr*}\\
Allocate an encoder. The encoder will work with uint8\_t, uint16\_t, uint32\_t or uint64\_t depending on which \texttt{RFC6330\_type} you choose. The best bet is usually to work with uint8\_t

\item[Decoder] \textbf{Input:const RFC6330\_type type}\\
.\ \ \textbf{const RFC6330\_OTI\_Common\_Data common}\\
.\ \ \textbf{const RFC6330\_OTI\_Scheme\_Specific\_Data scheme}\\
\textbf{return: RFC6330\_ptr*}\\
The \texttt{type} parameter works the same as in the encoder. The other two are parameters you get from the encoder.

\item[Decoder\_raw] \textbf{Input: RFC6330\_type type}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint64\_t size}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint16\_t symbol\_size}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint16\_t sub\_blocks}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint8\_t blocks}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint8\_t alignment}\\
\textbf{return: struct RFC6330\_ptr*}\\
Same as before, but here you can specify the parameters by hand.

\item[initialized]\textbf{Input: const struct RFC6330\_ptr *ptr}\\
\textbf{return: bool}\\
check if the encoder or decoder was initialized properly.

\end{description}

\newpage
\subsubsection{Common functions for (de/en)coding}

These functions are used by both the encoder and the decoder, and will be helpful in tracking how much memory
you will need to allocate, or in general in managing the encoder and decoder.

The \textbf{ptr} must be a valid encoder or decoder.
The names for now are self-explanatory. Blocks can have different symbols, so the size of a block and the number of symbols in a block
depend on which block we are talking about.

\marginlabel{\textbf{symbols, blocks, memory}}\\
\begin{description}
\item[set\_thread\_pool] \textbf{Input: const size\_t threads}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint16\_t max\_block\_concurrency}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const RFC6330\_Work exit\_type}\\
\textbf{return: bool}\\
Set the size of the thread pool for concurrent work. Since the decoder can fail, but also retry again if there is more data available,
you can also specify how many times libRaptorQ will try to decode the same block concurrently. $1$ is a safe option.\\
The last parameter, \texttt{RFC6330\_Work} specify what to do when you are downsizing the thread pool and some threads are still working. The possible values are \texttt{RQ\_WORK\_KEEP\_WORKING} and \texttt{RQ\_WORK\_ABORT\_COMPUTATION}.
\item[blocks] \textbf{Input: const struct RFC6330\_ptr *ptr}\\
\textbf{return: uint8\_t}\\
The number of blocks in this RFC6330 instance
\item[symbols]\textbf{Input: const struct RFC6330\_ptr *ptr}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint8\_t sbn}\\
\textbf{return: uint16\_t}\\
The number of symbols in the specified block
\item[extended\_symbols]\textbf{Input: const struct RFC6330\_ptr *ptr}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint8\_t sbn}\\
\textbf{return: uint16\_t}\\
The the \textbf{real, internal} number of symbols in the specified block. You probably \textit{do not want this} unless you are trying to understand more about the RaptorQ algorithm or you are benchmarking

\item[symbol\_size]\textbf{Input:const struct RFC6330\_ptr *ptr}\\
\textbf{return: size\_t}\\
The size of each symbol
\item[free\_block]\textbf{Input: struct RFC6330\_ptr **ptr}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint8\_t sbn}\\
\textbf{return: void}\\
Free the allocated space for a single block
\item[free]\textbf{Input: struct RFC6330\_ptr **ptr}\\
\textbf{return: void}\\
Free the specified decoder or decoder and all its blocks.
\end{description}


\marginlabel{Computation}\label{computation}\\
\begin{description}
\item[compute] \textbf{Input: const struct RFC6330\_ptr *ptr}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const RFC6330\_Compute flags}\\
\textbf{return: RFC6330\_future*}\\
Start the computation as described in the flags. Returns a wrapper to the C++11 futures. You can wait or poll the state of the future in different ways (see right below)\\
\begin{lstlisting}[language=C]
typedef enum {
RQ_COMPUTE_NONE 
// report every time there is more data, but only
// if that data starts at the beginning.
RQ_COMPUTE_PARTIAL_FROM_BEGINNING
RQ_COMPUTE_PARTIAL_ANY
RQ_COMPUTE_COMPLETE // only when all the data
					// is available
RQ_COMPUTE_NO_BACKGROUND // only return after
					 // the computation is finished
RQ_COMPUTE_NO_POOL // do not use the thread pool
RQ_COMPUTE_NO_RETRY // do not retry if we failed,
					// even if there is more data
} RFC6330_Compute;
\end{lstlisting}
\item[future\_state] \textbf{Input: const struct RFC6330\_future *f}\\
\textbf{return: RFC6330\_Error}\\
poll the state of the future. possible results:
\begin{lstlisting}[language=C]
RQ_ERR_WRONG_INPUT // null pointer?
RQ_ERR_NOT_NEEDED  // you have already run
				   // future_get() on this future
RQ_ERR_WORKING	   // still working on it
RQ_ERR_NONE		   // ready to run future_get()
\end{lstlisting}
\newpage
\item[future\_wait\_for] \textbf{Input: const struct RFC6330\_future *f}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint64\_t time}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const RFC6330\_Unit\_Time unit}\\
\textbf{return: RFC6330\_Error}\\
Wait for a future to become ready for X amount of time. the unit is specified in the
last parameter:
\begin{lstlisting}[language=C]
typedef enum {
RQ_TIME_NANOSEC,
RQ_TIME_MICROSEC,
RQ_TIME_MILLISEC,
RQ_TIME_SEC,
RQ_TIME_MIN,
RQ_TIME_HOUR
} RFC6330_Unit_Time;
\end{lstlisting}
\item[future\_wait] \textbf{Input: const struct RFC6330\_future *f}\\
\textbf{return: void}\\
Same as before, but wait indefinitely
\item[future\_get] \textbf{Input: struct RFC6330\_future *future}\\
\textbf{return: struct RFC6330\_Result}\\
Returns the state of the future. If the future is not ready it will wait indefinitely.
\begin{lstlisting}[language=C]
struct RAPTORQ_API RFC6330_Result {
    RFC6330_Error error;
    uint8_t sbn;
};
\end{lstlisting}
The sbn changes meaning depending to be consistent with the flags you passed to the \texttt{compute()} call.
\item[future\_free] \textbf{Input: struct RFC6330\_future **f}\\
\textbf{return: void}\\
Free the memory allocated for the future.
\end{description}

\newpage
\subsubsection{\textbf{Encoding}}
\index{Encoder!C}
Now we will look at the calls specific to the encoder (that is: calls that need an encoder as the first parameter, and don't make sense in a decoder)

\marginlabel{OTI Data}\\
First, we need to tell the receiver all the parameters that the encoder is using, and for that two functions are provided:
\begin{lstlisting}[language=C]
typedef uint64_t RaptorQ_OTI_Common_Data;
typedef uint32_t RaptorQ_OTI_Scheme_Specific_Data;
\end{lstlisting}
\begin{description}
\item[OTI\_Common]\textbf{Input: struct RaptorQ\_ptr *enc}\\
\textbf{return: RFC6330\_OTI\_Common\_Data}\\
Get the OTI\_Common
\item[OTI\_Scheme\_Specific]\textbf{Input: struct RaptorQ\_ptr *enc}\\
\textbf{return: RFC6330\_OTI\_Scheme\_Specific\_Data}\\
Get the OTI\_Scheme\_Specific
\end{description}

\marginlabel{Encoding}

\begin{description}
\item[max\_repair]\textbf{Input: const struct RFC6330\_ptr *enc}\\
.\ \ \ \ \ \ \ \ \ \ \ \textbf{const uint8\_t sbn}\\
\textbf{return: uint32\_t}\\
return the max number of repair packets that block can have. This is around $2^{24}$, so you probably always want to be much, much lower than this. The total number of symbols (source+repair) is limited in the RFC, and since the bigger blocks have more source symbols, the max number of repair symbols has to be lower in bigger blocks. Again, this is always in the ballpark of $2^{24}$, you probably don't want to use this many repair symbols.
\item[precompute\_max\_memory]\textbf{Input: const struct RFC6330\_ptr *enc}\\
\textbf{return: size\_t}\\
Get an estimate of how much memory (bytes) will cost the encoding of a single block. Not 100\% accurate, but close enough.
\item[encode\_id]\textbf{Input: const struct RFC6330\_ptr *enc}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{void **data}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const size\_t size}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint32\_t id}\\
\textbf{return: size\_t}\\
Get one encoded symbol, and store it in \texttt{**data}, which holds a pointer to "\texttt{size}" elements of type uint8\_t, uint16\_t, uint32\_t or uint64\_t depending on how the encoder was initialized. See \texttt{RFC6330\_type} in the encoder initialization. Returns the number of elements written.\\
If you request repair symbols before the computation is finished, the call will block until the data is available. This calls works for both source and repair symbols, just increase the id until you finish the source symbols
\item[encode]\textbf{Input: const struct RFC6330\_ptr *enc}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{void **data}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const size\_t size}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint32\_t esi}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint8\_t sbn}\\
\textbf{return: size\_t}\\
Same as before, but you can specify the symbol and block explicitly.
\item[id]\textbf{Input: const uint32\_t esi}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint8\_t sbn}\\
\textbf{return: uint32\_t}\\
combine the esi and the block number to form an id.
\end{description}


\newpage
\subsubsection{\textbf{Decoding}}
As for the encoder, there are functions which are specific for a decoder. Let's look at them

\marginlabel{General status calls}
\begin{description}
\item[bytes]\textbf{Input: const struct RFC6330\_ptr *dec}\\
\textbf{return: uint64\_t}\\
Return the number of bytes that this decoder should output on complete, successful decoding.
\item[blocks\_ready]\textbf{Input: const struct RFC6330\_ptr *dec}\\
\textbf{return: uint8\_t}\\
Return the number of blocks ready to be returned. Useful if you don't want to wait for the whole data.\\
The number of blocks reported can mean either the number of sequential blocks ready, or the number
of blocks regardless of order, depending on how the \texttt{compute} function was called (see "\texttt{Computation}" on \ref{computation}) 
\item[is\_ready]\textbf{Input: const struct RFC6330\_ptr *dec}\\
\textbf{return: bool}\\
Test if the whole encoder is ready and all data decoded.
\item[is\_block\_ready]\textbf{Input: const struct RFC6330\_ptr *dec}\\
\.\ \ \ \ \ \ \ \ \ \ \textbf{const uint8\_t block}\\
\textbf{return: bool}\\
Test if a single block is ready and its data decoded.
\end{description}

\index{Decoder!C}\marginlabel{Decoding calls}
\begin{description}
\item[end\_of\_input]\textbf{Input: const struct RFC6330\_ptr *dec}\\
.\ \ \ \ \ \ \ \ \ \ 
\textbf{const RFC6330\_Fill\_With\_Zeros fill}\\
\textbf{return: struct RFC6330\_Byte\_Tracker}\\
Tell the decoder that there will be no more input for any block.
The second parameter is an enum, it can be either \textbf{RQ\_NO\_FILL} or \textbf{RQ\_FILL\_WITH\_ZEROS}.\\
If you use \texttt{RQ\_NO\_FILL} the structure returned will be empty, and the decoder will return error if there are not enough repair symbols.\\
If you use \texttt{RQ\_FILL\_WITH\_ZEROS} the decoder will immediately stop decoding and all missing symbols will be filled with zeros. The returned structure will contain a bitmask so you know if each byte comes from the network (true) or it is one of the filled ones (false)
\item[end\_of\_block\_input]\textbf{Input: const struct RFC6330\_ptr *dec}\\
.\ \ \ \ \ \ \ \ \ \ 
\textbf{const RFC6330\_Fill\_With\_Zeros fill}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint8\_t block}\\
\textbf{return: struct RFC6330\_Byte\_Tracker}\\
Same as before, but for a single block instead of the whole data.
\item[add\_symbol\_id]\textbf{Input: const struct RFC6330\_ptr *dec}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const void **data}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint32\_t size}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uin32\_t id}\\
\textbf{return: RFC6330\_Error}\\
Add a symbol to the decoder. The \texttt{void **data} will be cast to the correct type as specified in the decoder construction (RQ\_DEC\_8, RQ\_DEC\_16 etc..). Afterwards data will point \textbf{after} the symbol.
\item[add\_symbol\_id]\textbf{Input: const struct RFC6330\_ptr *dec}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const void **data}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint32\_t size}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uin32\_t esi}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uin8\_t sbn}\\
\textbf{return: RFC6330\_Error}\\
Same as with \texttt{add\_symbol\_id}, but now you can specify the esi and the block number manually
\item[decode\_aligned]\textbf{Input: const struct RFC6330\_ptr *dec}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const void **data}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint32\_t size}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint8\_t skip}\\
\textbf{return: RFC6330\_Dec\_Result}\\
Decode everything as asked by the \texttt{compute()} call (see "\texttt{Computation}" on \ref{computation}).\\
The \texttt{void **data} will be cast to the correct type as specified in the decoder construction (\texttt{RQ\_DEC\_8}, \texttt{RQ\_DEC\_16} etc..). Afterwards data will point \textbf{after} the decoded data. You can skip "skip" bytes at the beginning of **data if the pointer
is not aligned with your data.
\begin{lstlisting}[language=C]
struct RAPTORQ_API RFC6330_Dec_Result {
	uint64_t written;
	uint8_t offset;
};
\end{lstlisting}
The result is the number of written \textbf{elements} (size depending on \texttt{RQ\_DEC\_8}, \texttt{RQ\_DEC\_16} etc).\\
The \texttt{offset} parameter is the amount of bytes written in the last element if the alignment used in the encoder does not fit the
alignment used in the decoder. Usually you keep those synchronized, so it should be zero (element fully written)
\newpage
\item[decode\_block\_aligned]\textbf{Input: const struct RFC6330\_ptr *dec}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const void **data}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint32\_t size}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint8\_t skip}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint8\_t block}\\
\textbf{return: RFC6330\_Dec\_Result}\\
Same as before, but now you can decode a single block.

\item[decode\_symbol]\textbf{Input: const struct RFC6330\_ptr *dec}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const void **data}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint32\_t size}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint8\_t skip}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint32\_t esi}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint8\_t sbn}\\
\textbf{return: uint64\_t}\\
As you can expect, decode a single symbol. The \texttt{void **data} will be cast to the correct type as specified in the decoder construction (\texttt{RQ\_DEC\_8}, \texttt{RQ\_DEC\_16} etc..). Afterwards data will point \textbf{after} the decoded data.\\
Returns the number of bytes written
\item[decode\_bytes]\textbf{Input: const struct RFC6330\_ptr *dec}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const void **data}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint32\_t size}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint8\_t skip}\\
\textbf{return: uint64\_t}\\
Decode everything as asked by the \texttt{compute()} call (see "\texttt{Computation}" on \ref{computation}).\\
The \texttt{void **data} will be cast to the correct type as specified in the decoder construction (\texttt{RQ\_DEC\_8}, \texttt{RQ\_DEC\_16} etc..). Afterwards data will point \textbf{after} the decoded data. You can skip "skip" bytes at the beginning of **data if the pointer is not aligned with your data.\\
Returns the number of written bytes.
\item[decode\_block\_bytes]\textbf{Input: const struct RFC6330\_ptr *dec}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const void **data}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint32\_t size}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint8\_t skip}\\
.\ \ \ \ \ \ \ \ \ \ \textbf{const uint8\_t block}\\
\textbf{return: uint64\_t}\\
Same as before, but now decode a single block
\end{description}




\input{GNU_FDL.tex}

\printindex
\end{document}