Class: Channel

Channel

A channel is a logical stream of Trap messages, multiplexed on the same Trap connection. Essentially, this allows sending multiple streams over the same connection. This is useful when multiple forms of data may need to be transported over a Trap session (e.g. short and long messages mixed), where a long/large message should not hold up a short/small message.

In the default case, there are two channels on every TrapEndpoint. Channel ID 0 will consist of control traffic, ensuring the endpoint is alive, managing transports, etc. It will have the highest priority, ensuring the endpoint can manage itself. Channel ID 1 will consist of application data. It will yield to Channel ID 0, ensuring that the application sending large messages will not cause control traffic to time out.

Trap version 1.2 supports up to 256 different channels. It is not recommended that Channel ID 0 is used for application data, leaving 255 channels for the application to use. Each channel can have its features individually configured.

When instantiated, channels have certain default settings. Trap's default implementation will use a chunk size of 16KB, and limit to 128KB in-flight bytes per channel. The channels will not operate in streaming mode by default. The default priority will be 0, except for Channel ID 0 which has the maximum priority.

The in-flight window will limit the throughput on fast links, while preventing us from oversaturating slow links. As an example, assuming 100ms latency and 128kb window size, we will at most process 10 windows per second, or 1280kb/s. 10ms latency yields 12800kb/s. Increasing the window size on a faster link will yield more throughput, but may risk oversaturating a slower link.

new Channel(endpoint, channelID)

Never instantiate a channel manually. Trap will manage the channels.
Parameters:
Name Type Description
endpoint Trap.Endpoint The endpoint that spawned this channel.
channelID Number The channel ID being created
Properties:
Name Type Description
streamingEnabled Boolean Controls the streaming flag of the channel. When a channel works in streaming mode, it will dispatch trapData events as data is received, although always in the correct order. With streaming mode disabled, each trapData event will represent a single send() event on the other side.

Streaming mode is useful for when Trap is used to transfer larger chunks of data, whose framing is internal to the data transferred. For example, an image, a song, or a video stream. Streaming mode will reduce – but not eliminate – the amount of buffering done in Trap.
chunkSize Integer The maximum number of bytes allowed in each message. Note that the chunk size includes the Trap message header, and this will be automatically subtracted from numBytes, unless numBytes is in the range of [1, TRAP_HEADER_SIZE]. If numBytes is zero or negative, chunking will be disabled.

Note that a chunkSize of Integer.MAX_VALUE will disable chunking. A channel will have that value set if the remote endpoint is suspected of not supporting chunking. Excepting that, chunkSize will automatically be reduced to the trap config option TrapEndpoint#OPTION_MAX_CHUNK_SIZE, which is automatically negotiated between the peers.
maxInFlightBytes Integer The maximum number of in-flight bytes. Combined with the chunk size, this limits the number of messages that the channel will allow to be in transit at any given time.

Increasing the number of in flight bytes will increase the required buffer sizes on both the local and remote ends, as well as the system's network buffers. It may also increase throughput, especially on congested links or when using multiple transports.

Note that in-flight bytes differs from the queue size. The queue denotes how many messages/bytes this channel can buffer, while in-flight bytes denotes how many messages/bytes we allow on the network.
priority Integer The channel priority, relative to the other channels. Channel ID 0 has priority Integer#MAX_VALUE, meaning any traffic on 0 takes precedence of any other traffic, for any reason.

Priority is byte based. A channel with priority n will be allowed to send up to n bytes before ceding transmission rights to a transport with lower priority. Note that if chunkSize exceeds priority, the transport will nevertheless be allowed to send chunkSize number of bytes.

Priority only affects the scheduling order of messages, and not the throughput. For the exact buffering, one must consider the channel's in-flight limit, the endpoint's in-flight limit (if any), as well as the transports' in-flight limit.
Source: