All Classes Namespaces Files Functions Pages
What's new in API v2

The second version of our Tcl API brings important new features and a more consistent experience to the user.

This page explains the most fundamental and the rationale behind them. See our migration guide for more practical information on how to port older scripts to the new API v2.

Bringing an API to a new version and breaking full backwards compatibility is not a decision taken overnight. Let us describes some of the key issues with API 1.x that led to this decision, how the new API design alleviates these issues and which parts of the API needed fundamental refactoring to achieve this.

Why a new API?

The ByteBlower Tcl API is available from the very start of ByteBlower as a commercial product. Over the years, a ton of features have been added, while maximum backwards compatibility was maintained.

Several structural constraints kept the product from evolving and made rolling out new functionality hard. The most important of these are:

  • A patchwork client-server communication protocol. The client-server communication has been expanded and patched over the years in order to make new features available. As a key component, it could not be refactored, without breaking compatibility in both client and server simultaneously.
  • Usage of complex nested Tcl list datastructures throughout the API. Such lists are hard to grasp without documentation, hard to debug, hard to process and hard to extend. Since the ByteBlower API has object-oriented facilities, it makes sence to use objects for these complex types of data.
  • Inconsistencies across the API. For example, the unit of timing values required or returned by API methods varied between nanoseconds, microseconds and milliseconds.
  • Inefficiencies at the server side required to support API method signatures. For example, a complete TX size distribution histogram is maintained for each Frame type, even though nearly all of these frames have a fixed size.

Since key parts of the server (network stack, handling of user events, ...) had to be rewritten to make our platform ready for the 10 Gigabit era and to make the long-awaited ByteBlower GUI 2.0 possible, the case for a new API was strong.

Furthermore, with compatibility constraints gone (even though we maintain compatibility calls where possible), some other aspects of the API could be cleaned up as well:

  • Bringing frame modifiers from the Tx.Stream to the Frame type. Aside from being the place where they belong, this allows us to roll out other frame modifiers in future. For example, a content modifier could create packets with varying UDP port numbers.
  • Improving the error handling. We've replaced Tcl errors and arcane exception messages with user-friendly exceptions of a relevant type wherever possible.
  • Consistent method naming. As an example, check out the following calls, which are all part of the previous API: CongestionWindowDowngrades.Get, FinalCongestionWindowSize.Get, MinimumWindowSize.Get, RcvWindowScale.Get and WindowScaling.Get.

Design choices

The first key design choice is Objects over lists. Places that expected structured lists as arguments (e.g. parts of the IGMP protocol) or returned complex structured lists (e.g. the extended stream result) have been refactored.

The second element states that every component references its own results. For example, the result for a stream no longer contains per-frame results. Instead, these results accessible from the frame object itself. This makes sure the user does not have to parse complex structures to find relevant information, but simple asks the data he actually needs!

Major changes

HTTP and TCP sessions


In the 1.x API, all known session parameters/counters where stored in a HTTPSessionInfoObject. This caused that the distinction between parameters/counter on TCP layer and parameters/counters on the HTTP Layer was unclear.

New design

Since we've redesigned our TCP stack we had the opportunity to make things more clear and to split TCP and HTTP up into 2 SessionInfo objects. Our stack keeps also a lot more different usefull counters than those that were exposed to the user e.g. MIN RTT/Avg.RTT/MaxRTT. Those new counters help you to identify TCP/HTTP issues in your DUT.


Result objects


In the 1.x API all counters where returned as a TCL-list. These lists where name-value pairs. In order to retrieve the counter you wanted, you had to use lindex and start counting the number of elements. Using TCL-Lists forced us to keep the order of the counters. Adding a new counter was only possible by putting it at the end of the list. At the beginning of our commercial API we had small lists but as ByteBlower evolved, the lists grow. We've desided to stop using TCL-lists as it isn't maintainable and impossible to introduce our new feature of Result Histories in the 2.x.

Results and result histories

The new design for the results is based upon a proven concept in ByteBlower: Objects. A Rx.Trigger now has a Result-Object. On this object you can request directly the counter-value you want e.g. PacketCount.Get without the need of parsing. This makes your tcl-code readable for your colleagues.

API 1.x

1 set result [ lindex [ $trigger Counters.Get ] 1 ]

API 2.x

1 set result [ [ $trigger Result.Get ] PacketCount.Get ]

One of the most requested features by you was some results over time.

Frame blasting TX: Streams and frames

Frame blasting RX: Triggers and captures

HTTP and TCP results


We've managed to keep the old Counters.Get method but marked it as deprecated. So you still can use the old call.

Frame modifiers

In the 1.x API, frame modifiers are applied to streams instead of specific frames.


Configuring frame modifiers on a stream is not only counter-intuitive but has some downsides as well.

First of all, the old server maintained a TX size distribution table (for framesizes from 60 up to 10000 bytes) for each individual frame of each flow. This was needed, since the extended result contains this distribution for each individual frame on the server. Note that, unless a size modifier was applied to the stream, these distribution tables contained only one non-zero element. To make our server ready for 10 Gigabit processing, this was no longer an option.

Most of the inconsistencies were already solved by moving to result object: each object contains a reference to its own results. Note that this is incompatible with a frame modifier Currently, there is an inconsistency in the API within the following elements:

The framesize modifier is in essence a frame modifier, not a stream modifier.
    Applying a framesize modifier on a Tx.Stream actually overrides the size of each of the (current or future) frames in that stream. A lot happens in the background here.
    This is also shown in the TX size distribution (the result matching the framesize modifier) which is provided at the frame level.
    Intuitively, a Stream is a traffic structure: containing (a mix of) frames; specifying a frame rate, burstiness, etc. 

We use the Tx.Stream object to obtain (aggregate) results about the stream, as well as its individual frames.
    Notice that most scripts have references to Frame objects, which are always part of a single stream.
    But when retrieving the result we have to match results with these frames through the stream. 

A TX size distribution only makes sense if we apply a framesize modifier on a Frame.
    Therefore it should only be activated when such modifier exists...
    ... and the result should be linked to that modifier. 

Differences between Tx (stream) and Rx resulting (triggers, latency,...) should be avoided. The current main differences are:
    Tx.Stream currently has 2 types of result (basic and extended), where as an Rx.<...> has only one.
    Tx.Stream result types contain information about both the stream as a whole and the individual frames. 

New design

In the new API, frame modifiers are moved from the stream object to the frame object.


API compatibility
Full compatibility maintained
Functional compatibility
Order of packets leaving the server may change if a stream contains both multiple frames and a modifier.

The current stream-based methods are deprecated, but are implemented for backwards compatibility. See their documentation for more information:

  • Tx.Stream::Modifier.Frame.Set
  • FrameModifier.RandomSize and FrameModifier.GrowingSize
  • Tx.Stream::Counters.SizeDistribution.Get

In situations where a size modifier is applied to a stream with multiple frames (using the deprecated methods), it will now be applied to every individual frame instead of the stream as a whole. For growing size modifiers, this means the actual packets leaving the server may be different.

Consider an example where a stream has 2 frames A (with UDP destination 2000) and B (with UDP destination 4000) and a growing modifier from 60 bytes to 100 bytes. In the old situation, the packets leaving the server would be

A-60 B-61 A-62 B-63 A-64 B-65 A-66 ...

where as the new situation would result in

A-60 B-60 A-61 B-61 A-62 B-62 A-63 ...

Other changes

Time values

Over the years, a lot of methods that either require or return timing values have been added. The scalar value they return must be interpreted in a variety of ways, which is only clear from the documentation. As of API v2, all values are specified in nanoseconds. If some method requires a value of a smaller resolution (e.g. milliseconds) and an invalid value is passed, a clear exception is thrown.

Multicast: IGMP and MLD

IGMP and MLD got a re-design in method namings. Due to historical reasons the API of both protocols was polluted. With the release of 2.x API we grabed the chance to change this and make the API consitend over both the protocols.