Range and bucket data type

Range and bucket data type

The range data type in Vue is designed to handle the distribution of data points for certain defined ranges. Each range of the variable defined of the range data type displays the count of the number of elements within the corresponding range value. The range data type will support Integral and String types of ranges. The distribution of range values for integral ranges can be the power of two distributions or a linear distribution. An example of linear and power of two distributions of range values follow:

Linear distribution:

Range	Count
0 - 5	2
5 - 10	4
10 - 15	1
Others	20

Power of 2 distribution:

Range	Count
1 - 2	2
2 - 4	9
4 - 8	2005
8 - 16	4
16 - 32	1999
32 - 64	7
Others	5

The previous distributions indicates the count of the number of elements greater than or equal to the lower bound of the range and less than the upper bound of the range value. For example, in the power of two distributions, the count of data starting from 4 and lesser than 8 is 2005. The count of the value that does not come under the defined ranges is displayed in the Others range.

Example of string ranges

Example:

Range	Count
Read, write, open	87
Close, foo1	3
foo2	1
Others	51

In the previous example, the distribution indicates the number of times a particular string occurs within the range values. In this example, read, write, and open has been called 87 times.

Declaration and initialization of the range data type:

The range data type can be declared by using the range_t keyword. For example, the following declaration in the Vue script defines two range data type variables:

range_t T1, T2;  // T1 and T2 are of Range data type variables.

The set_range and the add_range routines are used initialize the integral and string ranges for any particular range data type variables.

Initializing integral range data type: The set_range routine will be used to initialize the integral ranges. The syntax of the set_range differs for linear and power of two distributions of range values. The syntax of the set_range routine for linear distribution follows:

void set_range(range_t range_data, LINEAR, int min, int max, int step);

Example:

set_range(T1, LINEAR, 0, 100, 10);

In the previous example, the set_range routine initializes the range data T1. The range data T1 has the linear distribution of values. The lower bound of T1 is 0 and the upper bound is 100. The size of each range is 10. The distribution for the previous example will look like the following:

Range	Count
0 - 10	...
10 - 20	...
20 - 30	...
...	...
...	...
90 - 100	...

The syntax for the initialization of the power of 2 distribution follows:

set_range(range_t range_data, POWER, 2);

Example:

set_range(T2, POWER, 2);

In this example the routine initializes the range data type T2 as the power of 2 distribution range type.

Initializing the string range data type: The add_range routine initializes the string range data type.

Sytax:

void add_range(range_t range_data , String S1, String S2, ..., String Sn);

Example:

add_range(T1, “read”, “write”, “open”);

This routine add the strings read, write and open to a single slot of range_t data T1. Another add_range on the same range_t data T1 adds the strings to the next slot.

add_range(T1, “close”, “func1”, “func2”);

This routine adds the strings close, func1 and func2 to the range_t data T1 in the next slot.

Note: The range_t range data type is a special data type for Vue, which only can be used to store as a value inside an associative array. For any other operations (such as arithmetic, logical, bitwise, and relational) on the range_t data type, they will fail and error out.

Notes: This information discusses various uses and initialization routines of the range_t data type.

Declaration of the range_t data type can be done only in the @@BEGIN clause.
Initialization of the set_range routine can be used only inside the @@BEGIN clause.

A range data type whose range values are integral can be initialized only once. The same variable cannot be initialized twice.

Example:

set_range(T1, LINEAR, 0, 50, 5);        // Valid syntax
    set_range(T1, LINERA, 10, 100, 10); // Error, cannot initialize an already
                                        // initialized T1.
    set_range(T1, POWER, 2);            // Error, T1 has already initialized.
    add_range(T1, “read”, “write”);     // Error, T1 has already initialized.

The parameters of min, max and step are integral constants for set_range routine.

Storing and printing the range data type:

The range data type can be stored in an associative array as a value by using the qrange routine. The qrange routine finds the slot number whose frequency and count need to be incremental.

Example:

For this example, T1 is a range_t data type whose range values are of the integral type.

qrange(aso[“read”], T1, time_spent);

In this example, the qrange routine finds the slot number in which the time_spent fails and the count for that slot number are incremented for the associative aso array corresponding to the read key.

In the following example, the T2 is a range_t data type and range values are of the string type.

qrange(aso[“function usage”], T2,get_function());

In this example, qrangeroutine finds the slot number in which the function passed as the third argument fails and increments the count for that slot for aso associative array corresponding to the function usage key.

Notes:

For any ASO, only one range_t type variable can be stored as a value. Using qrange for two different types of range_t variable type for the same ASO will fail.
Example:
```
qrange(aso[“read”], T1,time_spent);  // Correct syntax.
qrange(aso[“read”], T2,time_spent);  // Error. Two different range_t types
                                       // cannot be used for the same ASO.
```
The quantize and lquantize functions of the associative array whose value type is range_t shows the visual quantization of frequency and count of ranges.
While printing the string range a maximum of 40 characters (including the comma) can be printed for a particular slot. If the strings in a slot have more than 40 characters, the string range is truncated and is printed with the last 3 characters as dots(…).

Examples of range data type and the qrange routine:

@@BEGIN
{
  __thread start ;
  range_t T1;
  set_range(T1, LINEAR, 0, 150, 10) ;
}
@@syscall :$__CPID :read :entry
{
  thread :tracing = 1 ;
  start = timestamp() ;
}
@@syscall :$__CPID :read :exit
         when(thread :tracing == 1)
{
  __auto long time_spent;
  currtime = timestamp() ;
  time_spent = diff_time(start, currtime, MICROSECONDS);
  qrange(aso[“read”], T1, time_spent);
}
@@END
{
  print(aso);
  quantize(aso);
}

Expected output for this example:

Key                                     Value

Read           Range                    count
               0-11	                     4
               10-20                     6
               60-70                     7
               Others                   32

Key                                     Value

Read           Range                    count
               0-10                       4      ===
               10-20                      6      ====
               60-70                      7      =====
               Others                    32      ================