This appendix documents the MTop and Diskstat classes as used in the mtop project in Chapter 3. These are used to gather information to display on an LED matrix, such as:

• General CPU usage (class MTop)

• General disk I/O usage (class Diskstat)

Include Files

With the default build and default install PREFIX=/usr/local, your installed librpi2 header files should be located in /usr/local/include. In your program use:

#include <librpi2/mtop.hpp>

If necessary, add the compiler option -I/usr/local/include.

Linking

With the default build and default install PREFIX=/usr/local, your installed librpi2 library should be located here:

/usr/local/lib/librpi2.a

When linking your program, add the options -L/usr/local/lib -lrpi2 to the link step of your make file.

MTop Class Definition

The public portion of the Matrix class is shown below (note how this class inherits from MAX7219, which is documented in Appendix D):

class MTop {
    ...snipped for clarity...

public:
    MTop();

    int sample(std::vector<double>& cpus);  // Return CPU %s
    double total_cpu_pct() const;           // Return last total CPU %
    double memory_pct();                    // Return memory used (%)
    double swap_pct();                      // Return swap used (%)
};

MTop::MTop

The Mtop class provides a default constructor that internally initializes the object:

MTop();

Its purpose after initializing is to gather system usage information about the CPU and memory. An example instantiation of MTop is given below:

MTop mtop;

MTop::sample

Each time the sample() method is called, the CPU usage information is internally captured. However, before any meaningful information can be returned, this method must be called two or more times. The first time simply preloads the statistics, while each successive call will return the usage difference between the current and previous call. The method prototype is as follows:

int sample(std::vector<double>& cpus);

The values are returned through a std::vector<double> argument, which is passed by reference. The sample() method first clears the vector to an empty container and then populates it according to the number of CPUs found for the system. For the Raspberry Pi 2, this should be four. The value returned in each vector cell is the percentage of utilization between 0 and 100.0.

The following code illustrates an example of the set up and call loop:

#include <vector>

MTop mtop();
std::vector<double> cpus;

mtop.sample(cpus);       // Initial sampling

for (;;) {
    mtop.sample(cpus);   // Return sampling differences
    for ( size_t cpu=0; cpu<cpus.size(); ++cpu ) {
        double pct_utilization = cpus[cpu];
        ...
    }
}

MTop::total_cpu_pct

When the method total_cpu_pct() is called immediately after the sample() method, a total CPU utilization is worked out in a percentage (0.0 to 100.0). This is used by the mtop utility to drive the total CPU usage meter, as described in Chapter 3. The function prototype is:

double total_cpu_pct() const;

An example of the use of this is provided below:

#include <vector>

MTop mtop();
std::vector<double> cpus;
double total_pct;

mtop.sample(cpus);       // Initial sampling

for (;;) {
    mtop.sample(cpus);   // Return sampling differences
    total_pct = mtop.total_cpu_pct();

    for ( size_t cpu=0; cpu<cpus.size(); ++cpu ) {
        double pct_utilization = cpus[cpu];
        ...
    }
}

MTop::memory_pct

The memory_pct() method takes a look at the system at the time of the call and determines the system memory usage as a percentage of the total available memory. Its purpose is to return a percentage that can be displayed on the matrix display. The calling signature is simply:

double memory_pct();

Its use within the sampling loop is shown below:

#include <vector>

MTop mtop();
std::vector<double> cpus;
double total_pct, pct_memory;

mtop.sample(cpus);       // Initial sampling

for (;;) {
    mtop.sample(cpus);   // Return sampling differences
    total_pct = mtop.total_cpu_pct();
    pct_memory = mtop.memory_pct();

    for ( size_t cpu=0; cpu<cpus.size(); ++cpu ) {
        double pct_utilization = cpus[cpu];
        ...
    }
}

MTop::swap_pct

This object method is used to determine the amount of swap in use at the time of the call, in terms of a percentage. The calling signature is:

double swap_pct();

Its use within the sampling loop is shown below:

#include <vector>

MTop mtop();
std::vector<double> cpus;
double total_pct, pct_memory, pct_swap;

mtop.sample(cpus);       // Initial sampling

for (;;) {
    mtop.sample(cpus);   // Return sampling differences
    total_pct = mtop.total_cpu_pct();
    pct_memory = mtop.memory_pct();
    pct_swap = mtop.swap_pct();

    for ( size_t cpu=0; cpu<cpus.size(); ++cpu ) {
        double pct_utilization = cpus[cpu];
        ...
    }
}

MTop Sampling Loop Timing

The sampling loop above did not show the delays used by the mtop command. The following is a recommended starting point if you are changing the code or writing your own version of MTop:

#include <vector>

MTop mtop();
std::vector<double> cpus;
double total_pct, pct_memory, pct_swap;

mtop.sample(cpus);       // Initial sampling
mswait(600);             // Delay 600 ms

for (;;) {
    mtop.sample(cpus);   // Return sampling differences
    total_pct = mtop.total_cpu_pct();
    pct_memory = mtop.memory_pct();
    pct_swap = mtop.swap_pct();

    for ( size_t cpu=0; cpu<cpus.size(); ++cpu ) {
        double pct_utilization = cpus[cpu];
        ...
    }
    mswait(80);          // Delay 80 ms
}

You can provide your own delay or reuse the delays offered in the librpi2 library in the piutils.hpp file:

#include <librpi2/piutils.hpp>

The C++ functions available are:

void nswait(unsigned long ns); // Nanoseconds
void uswait(unsigned long us); // Microseconds
void mswait(unsigned long ms); // Milliseconds

Diskstat Class Definition

The Diskstat class is an object that allows the caller to gather disk utilization statistics, as used by the mtop command in Chapter 3. The public aspects of the Diskstat class are shown below:

class Diskstat {
    ...snipped for clarity...

public:
    Diskstat();

    double pct_io();
};

Diskstat::Diskstat

The default constructor merely initializes the internals of the object for the end user. An example of its instantiation is:

Diskstat diskstat;   // Disk statistics object, ready to go

Diskstat::pct_io

This method calculates the amount of disk I/O that has occurred as a percentage (0.0 through 100.0). Its calling signature is simply:

double pct_io();

An example of its use is shown below:

Diskstat diskstat;
double io_pct;

io_pct = diskstat.pct_io(); // Get percent I/O

There is no Linux resource that indicates what the maximum I/O can be. So the Diskstat class tracks I/O usage with each call to the method pct_io(). As it samples the system, if it encounters more I/O time (provided in milliseconds), the object keeps track of that as a new maximum. In this way, a percentage of I/O can be calculated and returned.

The obvious result of this approach is that early I/O readings will be inflated until higher maximums have been observed. Keep in mind that this facility is meant for a MTop display result, rather than accurate accounting.