config.cpp

/**
 * Copyright © 2019 Andrey Nevolin, https://github.com/AndreyNevolin
 * Twitter: @Andrey_Nevolin
 * LinkedIn: https://www.linkedin.com/in/andrey-nevolin-76387328
 *
 * Data structures and utilities to work with the PEF configuration:
 *     - initialization of the configuration
 *     - parsing and validation of command line arguments
 *     - collection and validation of properties from other sources
 *     - calculation of derived properties
 */

/* PEF includes */
#include "config.h"
#include "common.h"
#include "time.h"

/* Standard C/C++ includes */
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <string>

/* Linux, POSIX, GNU includes */
#include <getopt.h>
#include <dirent.h>

/* External tools */
#define WTMLIB_ARCH_X86_64
#include "wtmlib.h"

/**
 * Print error message, simple assistance message and exit
 */
static void pef_ExitWithHint( const char *buff, const char *prog_name)
{
    PEF_ASSERT( buff && prog_name);
    PEF_ERROR( "%s\n\nRun \"%s\" without arguments for usage guidelines", buff,
               prog_name);

    return;
}

/**
 * Textual description of command line format
 */
static const char *usage_format[] =
{
    "Usage: %s -n <number of files> -s <file size> [-t <number of threads>] "
    "[--files_per_dir <number>] [--dd <data directory>] [--sd <statistics directory>] "
    "[--screen_stat <delay in seconds>] [--write_chunk_size <size>] [-v]",
    ""
};

/**
 * Textual description of command line options
 */
static const char *usage_guidance[] =
{
    " ",
    "PEF - a simple tool for File System performance evaluation. The tool writes the "
    "specified amount of files to a locally mounted file system. All the files are of "
    "the same size which is passed to PEF as a command-line argument. Every file is "
    "written sequentially.",
    " ",
    "It's possible to require the tool to write the files in parallel. In this case "
    "every single file will still be written sequentially, but the files themselves will "
    "be distributed evenly between the specified amount of threads.",
    " ",
    "If requested, each thread may put every \"so-many\" files it creates to a separate "
    "directory. \"So-many\" amount is passed to the tool as a command-line argument. If "
    "the threads are required to create the directories, they do that on on-demand "
    "basis. When a thread starts, it creates a directory and begins filling it with the "
    "files. When a \"files per directory\" limit is reached, the thread creates a new "
    "directory, which becomes a home to the new files being created by the thread. "
    "Again, only until the limit is reached. So on... All the directories are created at "
    "the same level inside the same pre-existing directory. The threads don't share "
    "directories they create. Each thread creates directories for its files by its own.",
    " ",
    "If \"files per directory\" limit is not set, then all the threads create their "
    "files inside the same pre-existing directory.",
    " ",
    "After the workload is completed, PEF emits an execution report in a form of two "
    "files named \"pef_TIMESTAMP__stat.summary\" and \"pef_TIMESTAMP__stat.details\", "
    "where \"TIMESTAMP\" is date and time when the tool was started",
    " ",
    "OPTIONS:",
    "   --dd",
    "          Data directory. A directory where all files - and possibly directories -",
    "          generated by PEF will be stored. Non-mandatory argument. If omitted, the",
    "          option defaults to the current directory",
    "   --files_per_dir",
    "          Limit on the number of files that can be stored in a single directory.",
    "          If this argument is passed to PEF, then the tool will create",
    "          intermediate directories between the generated files and output location.",
    "          These directories are not shared by different threads of the tool. Only a",
    "          thread that created a directory can write to it. PEF doesn't create",
    "          nested directories. All the directories are created at the same level",
    "          and inside the same directory, which serves as an output location for the",
    "          tool. The directories are created as necessary. When a thread starts, it",
    "          first creates a directory and then begins generating files. The files are",
    "          stored to the created directory until \"files per directory\" limit is",
    "          reached. When - and if - that happens, the thread creates a new directory",
    "          and stores the newly generated files there, again until the limit is",
    "          reached. So on... If \"files per directory\" argument is omitted, then",
    "          all the threads put their files directly to the output location",
    "   -n, --nf",
    "          Number of files to create. This argument is mandatory",
    "   -s, --fs",
    "          Size of generated files. Every file generated by the tool will have",
    "          exactly this size. The argument is mandatory. The size may be specified",
    "          in different units: 512B, 4K, 8M, 1G, where \"B\" stands for \"bytes\",",
    "          \"K\" for \"kilobytes\", \"M\" for \"megabytes\" and \"G\" for",
    "          \"gigabytes\". It's also allowed to omit units identifer. In which case",
    "          \"bytes\" is implied",
    "   --screen_stat",
    "          Whether and how often PEF should print its progress to the screen. If",
    "          the argument is omitted, PEF doesn't print its progress. Otherwise, the",
    "          argument sets time interval - in seconds - between successive progress",
    "          updates. Progress reporting may potentially interfere with the actual",
    "          workload. The bigger is progress update interval, the less probable and",
    "          less harmful will be the interference. Don't use progress reporting if",
    "          you don't tolerate any interference",
    "   --sd",
    "          Statistics directory. A directory where PEF execution report must be",
    "          stored. Non-obligatory argument. If omitted, the option defaults to the",
    "          current directory. In some cases it may be useful to store the report to",
    "          a file system which is different from a file system where PEF stores the",
    "          generated data. For example, it may happen that a file system where the",
    "          data is stored gets completely full before PEF is able to generate all",
    "          the required files. In this case PEF is expected to stop generating the",
    "          data and emit the report. The latter may still be accomplished if the",
    "          report is stored to a different file system",
    "   -t, --nt",
    "          Number of threads between which the workload must be distributed. The",
    "          argument is not mandatory. The default number of threads is 1",
    "   -v",
    "          Whether to produce verbose output",
    "   --write_chunk_size",
    "          Size of a data chunk that gets written at once. Files created by PEF get",
    "          written in chunks of the same size (maybe except the last chunk of every",
    "          file). All chunks written by PEF hold the same data. This data is",
    "          pre-generated by the tool before the actual workload is executed. The",
    "          size of the chunk may be specified in a variety of units. See description",
    "          of \"-s\" option for details. The argument is not mandatory. The default",
    "          value is 4M",
    ""
};

/**
 * Print help message for this program
 */
static void pef_PrintHelp( const char *const prog_name)
{
    for ( int i = 0; ; i++ )
    {
        if ( !strlen( usage_format[i]) )
        {
            break;
        }

        PEF_OUT( usage_format[i], prog_name);
    }

    for ( int i = 0; ; i++ )
    {
        if ( !strlen( usage_guidance[i]) )
        {
            break;
        }

        PEF_OUT( "%s", usage_guidance[i]);
    }

    return;
}

/**
 * Initialize options
 */
int pef_InitOpts( pef_Opts_t *opts)
{
    /* Default value for the number of threads is 1 */
    opts->num_threads = 1;
    /* Current directory is a default */
    opts->data_output_path = ".";
    /* Current directory is a default */
    opts->stat_output_path = ".";
    opts->num_files = -1;
    opts->file_size = -1;
    /* 4Mb is a default */
    opts->write_chunk_size = 4194304;
    opts->num_files_per_dir = -1;
    opts->screen_stat_timer = -1;
    opts->summary_update_timer = PEF_TIME_ZERO;
    opts->is_verbose = false;
    opts->file_base_name = 0;
    opts->num_digits_threads = -1;
    opts->num_digits_files = -1;
    opts->num_digits_dirs = -1;
    opts->tsc_ticks_per_sec = 0;

    return 0;
}

/**
 * Values returned by "getopt_long()" for parsed options
 *
 * If an option has a short alias, the value returned by "getopt_long()" is equal to this
 * alias
 */
/* Number of worker threads */
#define OPT_VAL_NUM_WORKER_THREADS  't'
/* Path to the data directory */
#define OPT_VAL_DATA_DIR            'd'
/* Path to the statistics directory */
#define OPT_VAL_STAT_DIR            'a'
/* Number of files to create */
#define OPT_VAL_NUM_FILES           'n'
/* Write chunk size */
#define OPT_VAL_WRITE_CHUNK_SIZE    'e'
/* Size of each file */
#define OPT_VAL_FILE_SIZE           's'
/* Number of files per directory */
#define OPT_VAL_FILES_PER_DIR       'b'
/* Pause between updates of on-screen statistics */
#define OPT_VAL_SCREEN_STAT_TIMER   'c'
/* Whether to produce verbose output */
#define OPT_VAL_VERBOSE             'v'

/**
 * Description of command-line arguments intended for "getopt_long()"
 */
static struct option pef_long_options_desc[] =
{
    /* Number of worker threads */
    {"nt",               required_argument, 0, OPT_VAL_NUM_WORKER_THREADS},
    /* Path to the data directory */
    {"dd",               required_argument, 0, OPT_VAL_DATA_DIR},
    /* Path to the statistics directory */
    {"sd",               required_argument, 0, OPT_VAL_STAT_DIR},
    /* Number of files to create */
    {"nf",               required_argument, 0, OPT_VAL_NUM_FILES},
    /* Write chunk size */
    {"write_chunk_size", required_argument, 0, OPT_VAL_WRITE_CHUNK_SIZE},
    /* Size of each file (in bytes) */
    {"fs",               required_argument, 0, OPT_VAL_FILE_SIZE},
    /* Number of files per directory */
    {"files_per_dir",    required_argument, 0, OPT_VAL_FILES_PER_DIR},
    /* Delay (in seconds) between updates of on-screen statistics */
    {"screen_stat",      required_argument, 0, OPT_VAL_SCREEN_STAT_TIMER},
    {0,                  0,                 0, 0}
};

/**
 * Description of short option names
 * 
 * '+' means that parsing stops when first non-option argument is encountered
 * ':' in the beginning means that ':' will be returned by 'getopt_long()' for missing
 *     option values
 * ':' after option character means that this particular option requires a value
 */
std::string pef_short_options_desc = "+:" +
                                     std::string( 1, OPT_VAL_NUM_FILES) + ":" +
                                     std::string( 1, OPT_VAL_FILE_SIZE) + ":" +
                                     std::string( 1, OPT_VAL_NUM_WORKER_THREADS) + ":" +
                                     std::string( 1, OPT_VAL_VERBOSE);

/**
 * Check whether 'strtol' conversion was successful
 */
static bool pef_IsStrtolOK( char first_symb, int err_no, char curr_symb, char base)
{
    PEF_ASSERT( (base > 1) && (base < 11));

    /* We don't allow leading '+' or '-' in command line argument syntax. But these
       symbols are allowed by 'strtol' */
    bool check_res = (first_symb < '0')
                     || (first_symb > '0' + base - 1)
                     || (err_no == ERANGE)
                     || (curr_symb != '\0');

    return !check_res;
}

/**
 * Convert data size units (kilobytes, megabytes, etc) to a size of bitwise shift that
 * must be applied to a value in the given units to convert it to bytes
 */
static int inline pef_ConvertUnitsToShiftSize( char unit,
                                               std::string param_description,
                                               std::string app_name)
{
    switch ( unit )
    {
        /* Units is 'byte' or units wasn't provided */
        case 0:
        case 'b':
        case 'B':
            return 0;

            /* Kilobytes */
        case 'k':
        case 'K':
            return 10;

            /* Megabytes */
        case 'm':
        case 'M':
            return 20;

            /* Gigabytes */
        case 'g':
        case 'G':
            return 30;

        default:
            std::string err_msg = "Unexpected units identifier for the \"" +
                                  param_description + "\"";

            pef_ExitWithHint( err_msg.c_str(), app_name.c_str());
    }

    PEF_ASSERT( 0);

    /* Just a formal "return" statement to make compiler happy */
    return 0;
}

/**
 * The function takes a string representation of data size and returns the number of bytes
 * encoded in this string
 */
static int64_t inline pef_ParseDataSizeAsBytes( std::string size_str,
                                                std::string param_description,
                                                std::string app_name)
{
    std::string arg_copy( size_str);
    char unit = 0;

    /* Check whether units indentifier was provided */
    if ( arg_copy.back() < '0' || arg_copy.back() > '9' )
    {
        /* Save units identifier */
        unit = arg_copy.back();
        /* Delete units identifier from the string */
        arg_copy.erase( arg_copy.size() - 1, 1);
    }

    char *c_ptr = 0;
    int64_t data_size = strtol( arg_copy.c_str(), &c_ptr, 10);

    if ( !pef_IsStrtolOK( arg_copy.front(), errno, *c_ptr, 10) )
    {
        std::string err_msg = "Integer - possibly with units - is expected for the \"" +
                              param_description + "\"";

        pef_ExitWithHint( err_msg.c_str(), app_name.c_str());
    }

    /* Get size of bitwise shift that we need to apply to the data size to convert it from
       user-provided units to bytes */
    int shift_val = pef_ConvertUnitsToShiftSize( unit, param_description, app_name);

    if ( data_size > (INT64_MAX >> shift_val) )
    {
        PEF_ERROR( "\"%s\" is too big. Maximum size is %ld bytes",
                   param_description.c_str(), INT64_MAX);
    }

    return data_size << shift_val;
}

/**
 * Parse command line
 */
int pef_ParseCmdLine( int argc, char *argv[], pef_Opts_t *opts)
{
    PEF_ASSERT( argv && opts);

    int long_opt_index = -1;
    int getopt_res = -1;
    std::string app_name = basename( argv[0]);

    while ( 1 )
    {
        int curr_optind = optind;

        getopt_res = getopt_long( argc, argv, pef_short_options_desc.c_str(),
                                  pef_long_options_desc, &long_opt_index);

        /* This return code means the input was fully parsed */
        if ( getopt_res == -1 ) break;
        
        /* Buffer for error messages */
        char buff[PEF_ERR_MSG_SIZE];

        switch ( getopt_res )
        {
            case OPT_VAL_NUM_WORKER_THREADS:
            {
                char *c_ptr = 0;

                opts->num_threads = strtol( optarg, &c_ptr, 10);

                if ( !pef_IsStrtolOK( optarg[0], errno, *c_ptr, 10) )
                {
                    pef_ExitWithHint( "Integer is expected for the number of worker "
                                      "threads", app_name.c_str());
                }

                if ( opts->num_threads < 1 )
                {
                    PEF_ERROR( "Number of worker threads must be greater or equal to 1");
                }

                break;
            }
            case OPT_VAL_DATA_DIR:
                opts->data_output_path = std::string( optarg);

                break;
            case OPT_VAL_STAT_DIR:
                opts->stat_output_path = std::string( optarg);

                break;
            case OPT_VAL_NUM_FILES:
            {
                char *c_ptr = 0;

                opts->num_files = strtol( optarg, &c_ptr, 10);

                if ( !pef_IsStrtolOK( optarg[0], errno, *c_ptr, 10) )
                {
                    pef_ExitWithHint( "Integer is expected for the number of files",
                                      app_name.c_str());
                }

                if ( opts->num_files < 1 )
                {
                    PEF_ERROR( "Number of files to generate must be greater or equal "
                               "to 1");
                }

                break;
            }
            case OPT_VAL_FILE_SIZE:
            {
                opts->file_size = pef_ParseDataSizeAsBytes( optarg, "File size",
                                                            app_name);

                /* We don't check whether the file size is bigger than zero. Creation of
                   zero-sized files is allowed by PEF */

                break;
            }
            case OPT_VAL_WRITE_CHUNK_SIZE:
            {
                opts->write_chunk_size = pef_ParseDataSizeAsBytes( optarg,
                                                                   "Write chunk size",
                                                                   app_name);

                if ( !opts->write_chunk_size )
                {
                    PEF_ERROR( "Write chunk size cannot be zero");
                }

                break;
            }
            case OPT_VAL_FILES_PER_DIR:
            {
                char *c_ptr = 0;

                opts->num_files_per_dir = strtol( optarg, &c_ptr, 10);

                if ( !pef_IsStrtolOK( optarg[0], errno, *c_ptr, 10) )
                {
                    pef_ExitWithHint( "Integer is expected for the number of files per "
                                      "directory", app_name.c_str());
                }

                if ( opts->num_files_per_dir < 1 )
                {
                    PEF_ERROR( "Number of files per directory must be greater or equal "
                               "to 1");
                }

                break;
            }
            case OPT_VAL_SCREEN_STAT_TIMER:
            {
                char *c_ptr = 0;

                opts->screen_stat_timer = strtol( optarg, &c_ptr, 10);

                if ( !pef_IsStrtolOK( optarg[0], errno, *c_ptr, 10) )
                {
                    pef_ExitWithHint( "Integer is expected for the pause between "
                                      "on-screen statistics updates", app_name.c_str());
                }

                if ( opts->screen_stat_timer < 1 )
                {
                    PEF_ERROR( "Pause between on-screen statistics updates cannot be "
                               "less than 1 second");
                }

                break;
            }
            case OPT_VAL_VERBOSE:
                opts->is_verbose = true;

                break;
            case ':': /* Missing mandatory argument */
                snprintf( buff, sizeof( buff), "Mandatory argument is missing for \"%s\"",
                          argv[curr_optind]);
                pef_ExitWithHint( buff, app_name.c_str());

                break;
            case '?': /* Unknow option */
                snprintf( buff, sizeof( buff), "Unknown option: %s", argv[curr_optind]);
                pef_ExitWithHint( buff, app_name.c_str());

                break;
            default: /* Unexpected return value of 'getopt_long()' */
                PEF_ASSERT( 0);
        }
    }

    if ( argc == 1 )
    {
        pef_PrintHelp( app_name.c_str());

        exit( EXIT_SUCCESS);
    }

    if ( optind != argc )
    {
        PEF_ASSERT( optind < argc);
        PEF_ERROR( "Unknown element of the command line: %s", argv[optind]);
    }

    if ( opts->num_files == -1 )
    {
        pef_ExitWithHint( "Number of files is required", app_name.c_str());
    }

    if ( opts->file_size == -1 )
    {
        pef_ExitWithHint( "File size is required", app_name.c_str());
    }

    return 0;
}

/**
 * Validate user-provided arguments
 *
 * Some simple per-option checks are already implemented in "pef_ParseCmdLine()".
 * "pef_CheckOptsSanity()" implements complex checks (e.g. checks that involve
 * combinations of options or checks that are too "heavy" to be incorporated in options
 * parsing)
 */
static int pef_CheckOptsSanity( const pef_Opts_t* const opts,
                                std::string indent,
                                char *err_msg,
                                int err_msg_size)
{
    PEF_VERBOSE( opts, "%sValidating user-supplied information", indent.c_str());

    char local_err_msg[PEF_ERR_MSG_SIZE];

    if ( opts->num_files < opts->num_threads )
    {
        PEF_BUFF_MSG( err_msg, err_msg_size, "The number of files cannot be less than "
                      "the number of threads");

        return PEF_RET_GENERIC_ERR;
    }

    /* Check whether statistics directory exists. Execution report is emitted at the very
       end of execution. A user may become very upset if non-existence (or inappropriate
       permissions) of the directory will be discovered only at that stage. Especially if
       the execution takes a lot of time. So, we check existence of the directory at the
       very beginning, long before we're going to use it */
    DIR *stat_dir = opendir( opts->stat_output_path.c_str());

    if ( !stat_dir )
    {
        PEF_BUFF_MSG( err_msg, err_msg_size, "Cannot access the statistics directory "
                      "\"%s\": %s", opts->stat_output_path.c_str(),
                      PEF_STRERROR_R( local_err_msg, sizeof( local_err_msg)));

        return PEF_RET_GENERIC_ERR;
    } else
    {
        closedir( stat_dir);
    }

    return 0;
}

/**
 * Compose base name for data and statistics files generated by PEF. The name is based on
 * the current time
 *
 * The function allocates memory to store the name. This memory must be deallocated by
 * calling routines
 */
static int pef_ComposeFileBaseName( char **base_name_ret,
                                    char *err_msg,
                                    int err_msg_size)
{
    char local_err_msg[PEF_ERR_MSG_SIZE];
    /* Get current time */
    time_t curr_time = time( 0);

    if ( curr_time == -1 )
    {
        PEF_BUFF_MSG( err_msg, err_msg_size, "Couldn't get current time: %s",
                      PEF_STRERROR_R( local_err_msg, sizeof( local_err_msg)));

        return PEF_RET_GENERIC_ERR;
    }

    struct tm *serialized_time = localtime( &curr_time);

    if ( !serialized_time )
    {
        PEF_BUFF_MSG( err_msg, err_msg_size, "Error serializing the current time");

        return PEF_RET_GENERIC_ERR;
    }

    const char base_name_template[] = "pef_%04d-%02d-%02d__%02d:%02d:%02d__";
    const int base_name_size = strlen( "pef_YYYY-MM-DD__HH:MM:SS__") + 1;
    char *base_name = (char *)malloc( base_name_size);

    if ( !base_name )
    {
        PEF_BUFF_MSG( err_msg, err_msg_size, "Error allocating memory to keep the name");

        return PEF_RET_GENERIC_ERR;
    }

    int chars_to_write = snprintf( base_name, base_name_size, base_name_template,
                                   1900 + serialized_time->tm_year,
                                   1 + serialized_time->tm_mon,
                                   serialized_time->tm_mday, serialized_time->tm_hour,
                                   serialized_time->tm_min, serialized_time->tm_sec);

    if ( chars_to_write < 0 || chars_to_write >= base_name_size )
    {
        PEF_BUFF_MSG( err_msg, err_msg_size, "Error joining parts of the name");
        free( base_name);

        return PEF_RET_GENERIC_ERR;
    }

    if ( base_name_ret ) *base_name_ret = base_name; else free( base_name);

    return 0;
}

/**
 * Calculate number of decimal digits required to represent a number
 */
static int pef_GetNumDigits( int64_t num)
{
    int num_digits = 0;

    do {
        num_digits++;
        /* Be careful: here we modify the function argument */
        num /= 10;
    } while ( num );

    return num_digits;
}

/**
 * Obtain configuration properties from tools that are external to PEF project
 */
static int pef_ObtainPropsFromExternalTools( pef_Opts_t *opts,
                                             std::string indent,
                                             char *err_msg,
                                             int err_msg_size)
{
    PEF_ASSERT( opts);
    PEF_VERBOSE( opts, "%sObtaining configuration properties from external tools",
                 indent.c_str());

    wtmlib_TSCConversionParams_t conv_params = {.mult = 0,
                                                .shift = -1,
                                                .nsecs_per_tsc_modulus = 0,
                                                .tsc_remainder_length = -1,
                                                .tsc_remainder_bitmask = 0,
                                                .tsc_ticks_per_sec = 0};
    uint64_t secs_before_wrap = 0;
    char local_err_msg[PEF_ERR_MSG_SIZE];
    int ret = 0;
    const char *ind = (indent += "\t").c_str();

    PEF_VERBOSE( opts, "%sCalling \"WTMLIB\" to get TSC conversion parameters", ind);

    ret = wtmlib_GetTSCToNsecConversionParams( &conv_params, &secs_before_wrap,
                                               local_err_msg, sizeof( local_err_msg));

    if ( ret )
    {
        PEF_BUFF_MSG( err_msg, err_msg_size, "Error getting TSC conversion parameters "
                      "from \"WTMLIB\": %s", local_err_msg);

        return PEF_RET_GENERIC_ERR;
    }

    PEF_VERBOSE( opts, "%s\tTSC ticks per second: %lu", ind,
                 conv_params.tsc_ticks_per_sec);
    PEF_VERBOSE( opts, "%s\tSeconds before the earliest TSC wrap: %lu", ind,
                 secs_before_wrap);

    if ( secs_before_wrap < PEF_SECS_TO_REMAIN_BEFORE_TSC_WRAP )
    {
        PEF_BUFF_MSG( err_msg, err_msg_size, "Too little time remains before the "
                      "earliest TSC wrap (%lu seconds, while PEF requires at least %lu "
                      "seconds)", secs_before_wrap, PEF_SECS_TO_REMAIN_BEFORE_TSC_WRAP);

        return PEF_RET_GENERIC_ERR;
    }

    opts->tsc_ticks_per_sec = conv_params.tsc_ticks_per_sec;

    return 0;
}

/**
 * Caclulate configuration properties based on:
 *     - command-line arguments
 *     - execution environment
 *
 * The calculated values are stored in "pef_Opts_t" structure supplied as an argument to
 * the function call
 */
static int pef_CalcDerivedProps( pef_Opts_t *opts,
                                 std::string indent,
                                 char *err_msg,
                                 int err_msg_size)
{
    PEF_ASSERT( opts);
    PEF_VERBOSE( opts, "%sCalculating properties derived from command-line arguments "
                 "and execution environment", indent.c_str());

    char local_err_msg[PEF_ERR_MSG_SIZE];
    const char *ind = (indent += "\t").c_str();
    int ret = 0;
    char *file_base_name = 0;
    int num_digits_threads = -1, num_digits_files = -1, num_digits_dirs = -1;
    pef_time_t summary_update_timer = PEF_TIME_ZERO;

    ret = pef_ComposeFileBaseName( &file_base_name, local_err_msg,
                                   sizeof( local_err_msg));

    if ( ret )
    {
        PEF_BUFF_MSG( err_msg, err_msg_size, "Error composing the base name for output "
                      "files and directories: %s", local_err_msg);

        return PEF_RET_GENERIC_ERR;
    }

    PEF_VERBOSE( opts, "%sBase name for output files and dirs: %s", ind, file_base_name);
    /* Calculate number of decimal digits required to represent number of threads (used to
       emit worker's ID in a field of fixed width) */
    PEF_ASSERT( opts->num_threads > 0);
    /* We start numeration of workers at 0. That's why 1 is subtracted from the number of
       threads */
    num_digits_threads = pef_GetNumDigits( opts->num_threads - 1);
    PEF_VERBOSE( opts, "%sWorker's ID will be printed in a fild of width %d", ind,
                 num_digits_threads);

    /* Calculate number of decimal digits required to represent number of tasks per worker
       (used to emit a task number in a field of fixed width) */
    int64_t files_per_worker = opts->num_files / opts->num_threads;

    PEF_ASSERT( files_per_worker > 0);

    if ( opts->num_files % opts->num_threads )
    {
        files_per_worker++;
    }

    /* We start numeration of tasks at 0 */
    num_digits_files = pef_GetNumDigits( files_per_worker - 1);
    PEF_VERBOSE( opts, "%sTask number will be printed in a field of width %d", ind,
                 num_digits_files);

    if ( opts->num_files_per_dir != -1 )
    {
        PEF_ASSERT( opts->num_files_per_dir > 0);

        /* Calculate number of decimal digits required to represent number of directories
           per worker */
        int64_t dirs_per_worker = files_per_worker / opts->num_files_per_dir;

        if ( files_per_worker % opts->num_files_per_dir )
        {
            dirs_per_worker++;
        }

        /* We start numeration of directories at 0 */
        num_digits_dirs = pef_GetNumDigits( dirs_per_worker - 1);
        PEF_VERBOSE( opts, "%sData directory number will be printed in a field of "
                     "width %d", ind, num_digits_dirs);
    }

    if ( opts->screen_stat_timer != -1 )
    {
        PEF_ASSERT( opts->tsc_ticks_per_sec);
        PEF_SECS2PEF_TIME( summary_update_timer, opts->screen_stat_timer,
                           opts->tsc_ticks_per_sec);
        /* Workers can update execution summary not more than 2 times before PEF prints
           its next overall progress update to screen (or file, or whatever) */
        PEF_TIME_DIV( summary_update_timer, summary_update_timer, 2);
    }

    opts->file_base_name = file_base_name;
    opts->num_digits_threads = num_digits_threads;
    opts->num_digits_files = num_digits_files;
    opts->num_digits_dirs = num_digits_dirs;
    opts->summary_update_timer = summary_update_timer;

    return 0;
}

/**
 * Validate command-line arguments, obtain configuration properties from other sources and
 * calculate derived properties
 */
int pef_CheckOptsAndFillFurther( pef_Opts_t *opts,
                                 std::string indent,
                                 char *err_msg,
                                 int err_msg_size)
{
    PEF_ASSERT( opts);
    PEF_VERBOSE( opts, "%sChecking command-line arguments and obtaining/calculating "
                 "further configuration properties", indent.c_str());

    char local_err_msg[PEF_ERR_MSG_SIZE];
    int ret = 0;

    indent += "\t";

    if ( pef_CheckOptsSanity( opts, indent, local_err_msg, sizeof( local_err_msg)) )
    {
        PEF_BUFF_MSG( err_msg, err_msg_size, "Error validating command-line arguments: "
                      "%s", local_err_msg);

        return PEF_RET_GENERIC_ERR;
    }

    ret = pef_ObtainPropsFromExternalTools( opts, indent, local_err_msg,
                                            sizeof( local_err_msg));

    if ( ret )
    {
        PEF_BUFF_MSG( err_msg, err_msg_size, "Error obtaining configuration properties "
                      "from external tools: %s", local_err_msg);

        return PEF_RET_GENERIC_ERR;
    }

    if ( pef_CalcDerivedProps( opts, indent, local_err_msg, sizeof( local_err_msg)) )
    {
        PEF_BUFF_MSG( err_msg, err_msg_size, "Error calculating derived properties: %s",
                      local_err_msg);

        return PEF_RET_GENERIC_ERR;
    }

    return 0;
}

/**
 * Deallocate memory used to store configuration parameters
 */
void pef_DeallocateOpts( pef_Opts_t* const opts, std::string indent)
{
    PEF_ASSERT( opts);
    PEF_VERBOSE( opts, "%sDeallocating memory occupied by configuration properties",
                 indent.c_str());
    free( opts->file_base_name);
    opts->file_base_name = 0;

    return;
}