API: FEC Parameters

This page describes in detail the FEC parameters, how to create and transmit them, and shows some coding examples.

Class net.fec.openrq.parameters.FECParameters (abbreviated here to FECParameters for simplicity) is a container class for the FEC parameters. It is an immutable class and only instances that contain valid parameters can be created.

• Creating FEC Parameters
• Transmitting FEC Parameters
• Coding examples

---

Creating FEC Parameters

To create an instance of FECParameters you may use one of these static factory methods:

• FECParameters.newParameters(dataLength, symbolSize, numSourceBlocks)

In this method you need to explicitly indicate the symbol size and the number of source blocks.

• FECParameters.deriveParameters(dataLength, payloadLength, maxDecodingBlockSize)

In this method the FEC parameters are derived from the provided deriver parameters, which are values typically present in communication protocols:

• The payload length denotes the minimum length of a packet payload containing one encoding symbol. It is equivalent to the symbol size parameter.
• The maximum size for a block decodable in working memory is associated to limitations on the receiver's working memory for flow control purposes, for example.

Hint: Use the first method if you need to control the number of source blocks your data is partitioned into. Use the second method if you need to upper bound the decoder working memory per source block.

Transmitting FEC Parameters

It is possible to convert the parameters to a sequence of bytes in a specific format, and parse FECParameters instances from well defined sequences of bytes. Methods are provided to write/read the sequence of bytes using:

• A byte[]: see write and read methods.
• A ByteBuffer: see write and read methods.
• A DataOutput: see write method; use for example instances of DataOutputStream.
• A DataInput: see read method; use for example instances of DataInputStream.
• A WritableByteChannel: see write method; use for example instances of SocketChannel.
• A ReadableByteChannel: see read method; use for example instances of SocketChannel.

Coding examples

Creating an instance of FECParameters using a fixed payload length value:

import static net.fec.openrq.parameters.ParameterChecker.minDataLength;
import static net.fec.openrq.parameters.ParameterChecker.maxAllowedDataLength;
import static net.fec.openrq.parameters.ParameterChecker.minAllowedDecodingBlockSize;

private static final int PAYLOAD_SIZE = 1500 - 8 - 20; // UDP-Ipv4 payload length
 
public static FECParameters getParameters(long dataLen, int maxDecMem) {
    if (dataLen < minDataLength())
        throw new IllegalArgumentException("data length is too small");
    if (dataLen > maxAllowedDataLength(PAYLOAD_SIZE))
        throw new IllegalArgumentException("data length is too large");
    if (maxDecMem < minAllowedDecodingBlockSize(dataLen, PAYLOAD_SIZE))
        throw new IllegalArgumentException("max decoder memory is too small");

    return FECParameters.deriveParameters(dataLen, PAYLOAD_SIZE, maxDecMem);
}

In this example, we are deriving FEC parameters by fixing the payload length and varying the data length and maximum decoder memory. Since the number of source symbols is upper bounded, there is a maximum allowed source data length, given a certain symbol size (payload length). For a symbol size of (1500 - 8 - 20) bytes, the maximum allowed data length is 21254455296 bytes, or 19,79 GiB. Similarly, the decoder memory for a single source block is lower bounded due to the number of source blocks being upper bounded by 256.